Using the System Browser

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

select the class category, where the new class shall be included in (if you want to add a new category, use the "new class category" menu function in the class category list).
select the "new"-"class" item from the classList's popUp menu. This will present a class definition template in the codeview.
edit the template (change the superclasses name, the class name and add instance and/or class variables as required).
"accept" i.e. select the "accept" menu function in the codeview or type the shortcut key (Ctrl-S or Alt-A)
it is a good idea to add some documentation now (see below)

Notice:
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

select the class and apply the class lists "rename ..." menu function. You will be asked for a new name.
After the rename, the browser will search for all references to the old class and (if any are found) open a browser on the referencing methods. You may or may not want to change those references to the new name.

Notice:
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

select the class and apply the class lists "remove" menu function. You are asked to confirm the removal.

Notice:
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:

select the class
use the method category list popup menu function "add documentation stubs".
edit these documentation methods and "accept" them

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

select the class
select the method category (or create a new method category, by using the "new category" menu function in the method category list)
type in the method into the codeview
You can also get a method template with the "new method" menu function in the method lists popup menu. Alternatively, copy and paste some code from any other textView, and modify it as appropriate.
"accept"

Modifying existing Methods

select class, method category and method; this will bring the methods source into the codeview.
edit the methods code as required
"accept"

"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

select class, method category and method; this will bring the methods source into the codeview.
use the "remove" function from the method lists popup menu

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").

What was Changed / Previous Versions of a Method

ST/X keeps multiple histories where changes are recorded:

Lists of previous versions for individual methods
The "ChangeSet", which remembers changes done during the current session
The "ChangeFile", which remembers all changes ever done
The "Source Code Repository", which records checked in versions of classes and packages

Previous Versions of an individual Method

This is found via the browser's selector list menu, in "Previous Versions" under the "Special" submenu.
Notice, that there are also entries to go back to the selected method's previous version and to compare the current against the previous.

Changes in the Current Session (ChangeSet)

This is shown via the browser's or the launcher's "Changes" toolbar icon.
The full documentation is found in the "Change Browser Documentation".

All Changes (ChangeFile)

This is shown via the launcher's "Changes" toolbar icon.
Refer to the "Change Browser Documentation" for more info.

Repository Versions

If you are conencted to a central source code repository, there are additional menu items to browse through repository versions in the method list, the class list and the package list.

Adding/Removing Instance- or Class Variables

There are two ways to perform this task:

use an appropriate menu function from the variable list menu (add,remove or rename)

or, alternatively,

select the class (this will show its definition in the codeview)
edit the 'instanceVariableNames' or 'classVariableNames'-string as required.
"accept"

Notice:

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

Select the "Senders..." item in the method menu
This opens a DialogBox asking for the selector of interest.
Fill in selector to search for. You can use wildcards (i.e. a matchpattern) and/or specify a case-ignoring search. Also, the scope of the search can be limited in various ways.
(The box will offer a reasonable default text, depending on the context in which you use this function. It will either use the current selection from the code view or the currently selected method. It will even try to interpret the currently selected text and extract the selector from partial expressions).

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

Who Implements a Particular Message

Select the "Implementors... item in the method menu
This opens a DialogBox asking for the selector of interest.
Fill in selector to search for. You can use wildcards (i.e. a matchpattern) and/or specify a case-ignoring search. Also, the scope of the search can be limited in various ways.

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

Who References a Particular Class or Global

Select the "References to Class or Global" menu item from the browse menu (this is found in the browser's main menu).
Enter the name of the global (matchpatterns are allowed)

Notice:

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):

Select the "Browser on References" or "Buffer with References" item in the VAR>"Browse submenu of the classLists popupMenu

Which Method is Executed if I Sent #foo

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

Select the "Response to..." item in the find menu (this is found in the browser's main menu)
This opens a DialogBox asking for the selector of interest.
Fill in the selector to search for

Which Methods Reference/Modify a Particular Instance Variable

Select any of the "instanceVariable" menu items in the variable list menu.

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.

Notice:
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.

Select the "string search" item from the method list.

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:

#keyboard
methods which do some keyboard event handling and somehow depend on the keyboard map.
#style
methods which access the view styleSheet and somehow depend on those definitions.

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

<info@exept.de>

Doc $Revision: 1.14 $ $Date: 2020/09/13 10:47:26 $