[prev] [up] [next]

Browsing a Snapshot Image

The NewSystembrowser is not yet prepared to browse snapshot images (or, simulated environments in general).
For now, please use the old SystemBrowser to do this:
    SystemBrowser openOnSnapShotImage:anImageFileName
For more information, please read the corresponding paragraph in the old Systembrowsers documentation.

How to Perform typical Day-to-Day Tasks

Notice, that the NewSystemBrowser keeps a history, and allows for most changes to be undone/redone. These operations are performed via the browser's "Operation" menu.

Creating a New Class

If the new class is installed in a namespace AND hides a corresponding global class, methods within that namespace which access the class by its name are recompiled (possibly then accessing the new namespace-class).

Renaming a Class

If the rename implies a change of the namespace, all methods which access the class by its old name are recompiled (possibly then accessing the previously hidden global class with the same name).
Do not rename classes programmatically, by changing a classes name and/or storing it under another key in the Smalltalk dictionary, because this will not take care of accessors and especially not recompile them.
(a program should use "Smalltalk renameClass:...to:", instead)

Removing a Class

If the removed class was located in some namespace, and a global class exists with the same name (i.e. the class has hidden the global class within the namespace), all methods which access the class by its old name are recompiled (possibly then accessing the previously hidden global class).
Do not remove classes programmatically, by removing it from the Smalltalk dictionary, because this will not take care of accessors and especially not recompile them.
(a program should use "Smalltalk removeClass:...", instead)

Adding Documentation

We suggest you stay with Smalltalk/X's philosophy of putting the documentation into empty methods under the 'documentation' category. To do so: The advantage of documentation methods vs. a documentation attribute of the class are obvious: all of the code-tools (string search, copy, move, etc.) are also available for documentation strings. The extra memory required by these empty documentation methods is negligible, as the methods text (source) is not stored in the object memory.

Adding Methods

Modifying existing Methods

"accept" installs whatever is currently visible; if the methods selector has been changed, a corresponding (possibly new) method will be generated - independent of the method which was selected in the first place.
Thus, you can select any other method, to take its source code as a starting point for new methods.

Removing Methods

Notice, that the system cannot itself find out, if the method is still required - i.e. if there are any message sends which would possibly invoke that method (since message sends could be constructed by a #perform, or by evaluating a Smalltalk expression from a string).

Therefore, looking at all senders before actually removing any method may not always ensure that the method is not needed.
A good approach is to change the methods visibility to "ignored" instead of removing it. This marks the method as being invisible with respect to the method lookup - its still shown in the browser, but ignored by the program. Ignored methods may later be removed (or changed back to "public").

Adding/Removing Instance- or Class Variables

There are two ways to perform this task: or, alternatively,


existing instances of the class will not be affected by this change. Instead, the original class will get its category changed to "obsolete" and a new class is installed under the original name. This means, that existing instances still have a valid class definition around, but methods can no longer be added, removed or changed to the old class.
In case of a changed class definition (which affects the instance layout), the system will recompile all methods that require recompilation. Have a look at the Transcript, to see what is going on.
If the changed class has many subclasses, this may take a while, since all subclasses may have to be recompiled.

Who Sends a Particular Message

The messages sent by the selected method(s) are also offered in a separate "Senders" submenu.

Who Implements a Particular Message

The messages sent by the selected method(s) are also offered in a separate "Implementors" submenu.

Who References a Particular Class or Global


since classes are (almost) always referenced by globals, this will also find explicit uses of classes. (for example: try searching for "Array")

The outcome of the search will be presented in a browser, which has its search pattern preset to the globals name. Thus a search-next (i.e. "CMD-F") will place the cursor to the next occurence of the string.

Which Methods use the Current Class

If you are interrested in references to the currently selected class, there is a shortcut (without a need to type in the class name):

Which Method is Executed if I Sent #foo

Use this to search up the class inheritance for an implementor of a particular message.

Which Methods Reference/Modify a Particular Instance Variable

A dialog appears, asking for the variables name (matchPatterns are allowed), and the set of classes to limit the search.

Since searching involves parsing the source code, these functions may take a while to show the result. Limiting the search to the current class or category helps here.

Simply selecting a variables name in this list will highlight (underline) all methods in which that variable is accessed.
In addition, a red color shows modification(s) of that variable(s).

Which Method Contains some String

This question is often asked, if you have some method producing a message or output to some stream, and you want to find out quickly where that happens.
For example, which method is responsible for the "compiled: ..." message appearing on the transcript when methods are accepted.
There is no direct search function available for this kind of query. However, you can use the substring search functions to (at least) limit the number of methods that have to be investigated. Notice, that since all source code has to be processed, this function takes somewhat longer than other queries (senders/implementors); therefore, if you know the selector which is used, the senders function is probably better.
Also, if you have any idea of which class (or superclass) the method is contained in, limit the search to the current class or category.

Which Method Contains some Code Construct

Often, you are searching for occurrences of a particular message construct or message-argument combination. In many cases, a pure text search is not sufficient for this, as it requires complicated regular expressions to deal with comments, whitespace, argument/message names, formatting etc.
For example, if you want to search for all senders of the add:-message with a nil-argument, you cannot simply search for the string "add:nil" (within the list returned by allsenders of the add:-message).
Although the above does in fact return some results, it still would not find sends like ""add: nil" (i.e. with a space in-between) or "add: "some comment here" nil" (with embedded comment) etc.
Use the "code search" menu function, to search using a parse-tree matcher algorithm instead of a string match.

The code search allows for very powerful searches - more detailed information is found in the refactoring documentation on Code Search Patterns.

Which Methods Contain a (Specific) Resource Tag

For fast search, methods can be tagged with a "resource:" definition; this has no semantic meaning, but methods tagged this way can be quickly found, without a need to scan its source (there is a corresponding resource-tag-bit in the method object, which is much faster to check).

Within ST/X, methods are marked with the following tags:

Therefore, to find all methods which do keyboard event handling, search for a resource named "keyboard".

You may either search for a resources key (as above) or for some particuler value item; for example, all methods which handle the "Accept" key are found by a search for the resource "keyboard" and a value of "Accept".

You can mark your methods with any resource; for example, in a project it may be useful to tag methods with things like "toBeReviewed", "toBeTested", "preliminary" or whatever.
These methods are later quickly found by searching for an appropriate resource.

Sorry, there is no resource search menu item in the browser; instead, the launcher offers this in its classes pull down menu.

Changing a Classes Namespace

There is now a menu item in the class-list-menu for this operation: "Move to Namespace".

Changing a Classes Category

There is now a menu item in the class-list-menu for this operation: "Move to Category".

Hints & Tips

Prepare Use of the stc Machine Code Compiler

If you plan to compile your classes later to binary modules (which is likely the case), use the "fileout-each" function instead of "fileOut" in the class category list (*).
This will create separate sourcefiles for each class instead of putting them all into one big file. The reason is that the stc-compiler cannot compile files containing multiple classes, but requires one class per sourcefile (except for private classes).

(*) of course, an even better aproach is to use the source code manager and check the classes into a repository, including make- and other build support files.

Use Project Directories

If you are working in multiple projects, define some per project directory in the project view. The System Browser will always save files into the active project's directory.
This avoids having all of your filedOut sourcefiles being saved in one big directory, and helps to structure your project. However, here again we recommend using a source code manager, which will deal with such issues for you)

Keep Your Sourcefiles Consistent

Do not edit existing sourcefiles with the fileBrowser or another (non-ST/X) editor while ST/X is executing within that directory hierarchy. Since methods do not keep the source as a string (but instead the filename and filePosition), editing a sourcefile makes this sourceInfo invalid (you will see funny code in the systemBrowser) in the current Smalltalk executable.
Be also careful about overwriting existing sourcefiles when filing out: since the methods source is typically extracted from some sourcefile, overwriting one of them will lead to funny results. All fileOut functions will be changed in upcoming versions to take care about this, but currently you should never fileOut into one of the "libXXX" directories.

You have to recompile that file and relink a new Smalltalk executable to fix things.

If you see funny sourcecode in the browser, do NEVER fileOut these - the resulting sourcefile may be completely useless.

The above consistency problem does not apply, if the sourceCode manager is used; if enabled, the sourceCode manager can figure out the classes actual version, and extract the corresponding source version from the repository - even if newer versions of the same class are present in local source files or in the repository.

Especially if you do not use a sourceCode manager (but also if you do, to prevent trouble), use two parallel source and execution hierarchies - one from which you execute the current release, and another, on which the next one is maintained. Exchange the two, whenever a stable, tested new release has been built in the other (not-executed) hierarchy.

Next: Settings

[stx logo] Copyright © 2000 eXept Software AG, all rights reserved


Doc $Revision: 1.13 $ $Date: 2017/11/25 12:01:31 $