Help - Programming - Working with Browsers
Working with Browsers
All the code that runs Squeak is available in Squeak: You can read it, try to understand it, and add to it or alter it as you see fit. Moreover, this reprogramming of Squeak takes place as in Squeak as it runs.
The basic tool for reading and editing source code is the system Browser. And yes, like everything else in Squeak its code is in Squeak: Highlight Browser and do Cmd-b on it to see it.
But here we are interesting in using it. In this section I will explain many of the features of the standard system Browser, and say a little about related browsers, and also introduce the Whisker Browser, which is not part of the standard system at present, but can be downloaded from Squeak Map. I mention here because it is quite elegant and a good supplement to the standard system Browser, especially because it allows to open many windows with methods and classes inside one browser.
- System Browser and others
- Whisker Browser
System Browser and others
The standard System Browser, as you may know, looks somewhat like this:
On your systems it may have a different color or different fonts in the different panes. The fonts depend on what you have available and installed on your system, and on what you have set in Preferences.
The system Browser is composed of five panes plus two that you can get from Preferences and are wise to get since they are useful:
- text pane: The lower pane to read or
edit code
- system category pane: The upper left with system categories
- class pane: The upper second with the classes in the selected category
- class category pane: The upper third with categories of the methods of
the class
- method pane: The upper right with the methods of the class
Also there are two horizontal panes
- annotation pane: Under the four upper
panes, with details on the highlighted method.
- button pane: Above the text pane:
If you do not have these in your present system Browser, use Preferences to set them. The options are called annotationPanes and optionalButtons, in the browsing option in Preferences. Then get a new system Browser, and it will have them.
Let's first see what these seven panes are for in general terms.
Of these the two category panes are especially there to help the human users: The system category pane lists the classes in the system in subgroups (or subsets or categories) helpful to humans, and the class category pane lists the methods of the class in subgroups (or subsets or categories) helpful to humans.
The class pane shows the classes in the selected system category. It has three options in its pane: instance ? class. Of these instance button shows the code for objects of the class plus the definition of the class in the textpane. The definition of a class is what you have to start with when you make a new class: The superclass of the class; its instance variables; its class variables; its pool dictionaries and its category. The ? button shows the comment of the class in the text pane. The class button shows the code for the class plus the definition of the class in the textpane. (The code for the class is always runnable without first making an object of that class.)
The class category pane shows the categories of the methods in the selected class. These are up to the programmer of the class, who may have introduced no categories whatsoever. (This doesn't matter for a class with few methods, but tends to make the code less readable with classes with many methods.) There always is at least the category '-- all --' in it, which when selected displays all methods in the method pane that are in the class.
The textpane when viewing a class category pane always shows the unexciting bit of text
message selector and
argument names
"comment stating purpose of message"
| temporary variable names |
statements
which shows you the format of a method AND assures you that the method you will write in place of the just quoted but of text - which must conform to the stated format - will be put automatically in the category the cursor in the class category pane is on. (This can be changed easily from the pop-up of the method pane. See below.)
The method pane shows the list of methods in the class and the textpane shows the method the cursor in the methodpane is on. This allows you to read or edit that method.
The text pane shows editable text. What it shows depends on what is selected in the upper four panes. If a method is highlighted, it displays the text of the method so that you can read or edit it.
The annotation pane shows some details about the method in the method pane that the cursor is on, if it is. What details can be set by Annotations, which you can grab from the Tools flap. If your new to Squeak, these details will convey little, but as you grow more used to Squeak, especially when you program in it, these details are helpful.
The button pane shows a list of buttons that are very useful. Here is a quick listing of the buttons shown in the above picture
- menu button: This is left of the browser button. It pops up a pop-up with many options (inclduing another popup with many options) that are mostly dealt with in the present text. So I will skip these here. But it is nice to know they are there and find out what they are and do. The menubutton is also set by Preferences under browsing. Its name is menuButtonInToolPane.
- browser button: This starts a browser depending the choices in the upper four panes of the browser. Thus, you can get a new Browser on a specific class or method, which tends to be a very handy option when programming (or reading code).
This relativity to the choices in the upper four panes holds for most of the following options, which I shall here briefly explain by saying what they do for methods i.e. if the cursor in the above four panes is everywhere highlighting some item, including some method.
- senders button: This displays the senders of a method. This is very helpful when programming: It tells you where the method (or a method of that name!) is used in the system.
- implementors button:
- versions button: An extra-ordinarily useful button that starts a versions browser. This displays the recent versions of the method, while also neatly showing the changes compared with the previous method. This makes it very easy to revert to an older version, e.g. if a newer version you wrote doesn't perform as you expected.
- inheritance button: Pops up a window with the methods code.
- hierarchy button: Starts a Hierarchy Browser on the class and method.
- inst vars button: Again very useful: A list of the instanceVariables in the class, which are the named dataslots of the class. When you select an instanceVariable from the list, Squeak will pop up a list of methods of the class in which the instanceVariable occurs (also possibly in a comment, by the way). The name of the instanceVariable will be highlighted, so that you see it easily. Since instanceVariables are the dataslots, it is very pleasant to know precisely where they are used in the code. And the code can here be directly edited as well.
- class vars button: A list of the classVariables in the class. This may be only - and often is only - DependentFields (belonging to Object), but in any case a selection from the list will display a list of places in the system where the ClassVariable is used, as for inst vars.
- source button: This produces a pop-up as follows:
As it happens, this menu has tooltips i.e. there will be a balloon with helptext if you put the cursor on an option long enough. Here I will add only a little on four of them:
prettyPrint: This displays the code you wrote in a hopefully neater form. See the next option.
colorPrint: As prettyPrint, but with colors. As in the previous case, the pretty printing depends on certain assumptions about how the code was written and how it should be displayed. Both cases of pretty printing may be not to your liking. And in case you like colorPrint, Steve Wessels wrote a short tool that is on Squeak Map by which you can easily alter the colors used in colorPrint (which is desirable for avoiding the faint green it standardly uses, for example).
altSyntax: There is an alternative syntax for Smalltalk. This recasts the code to that form. It is interesting, at least in principle, but seems to be little used.
tiles: Yet another syntax, as used in EToys.
Personally, I sometimes colorPrint and have a little experience with altSyntax. It should be noted that I like other colors (see above remark on Steve Wessels tool for that purpose) in colorPrint, and I noticed prettyprinting undoes some of my own preferred ways of commenting code, also when returning to source.
There are several other kinds of system Browers:
- Package Browser
- Whisker Browser
- RB Browser
- Star Browser
Except for the Package Browser these do not come with a standard system, and must be added, e.g. by downloading and installing them from Squeak Map. Here I will not consider the last two system browsers, but I will say something about the first two.
You can display a PackageBrowser by
PackageBrowser
It is quite like the system Browser, except that its first page is divided into two panes, one for the general categories in the system and one for their sub-categories. This may be helpful but I will not further consider it here.
The Whisker Browser is an add on which I think is very helpful, because it allows you to read and edit many methods in one single Browser. This is very helpful when reading code and trying to understand it and also often when writing code, since one can keep related methods in view.
Here is a picture of it to whet your appetite. It displays the same as the above System Browser plus more:
I will say something about it later on, since it is quite handy.
Now let's return to the standard system Browser and see what the menus of these five panes have to offer.
The system Browser has a lot to offer, and what it has to offer and displays may depend also on whether you have loaded extras, such as the Whisker Browser or the RB Browser. Of course it depends also on the system you use and are reading the code of in the Browser.
Here follows a survey of the pop-up menus in the system Browser. They appear with a mouse middle or right click, depending on how your system has been set.
Pop-up menus in the system category pane
1. Category pane
The main pop-up in the system category pane looks like:
apart from whatever font is used on your system and what was set in appearance. The dotted items give access to further pop-ups.
find class...(f): This pops up a small window that asks 'Class name or fragment?'. When you type a part of a class-name, Squeak produces either nothing or a list of class-names that contain the fragment you typed or moves the browser straight to the class if there is only one that conforms to the fragment. The bracketed '(f)' means that from the keyboard this can be done with Cmd-f.
recent classes...(r): This pops up a convenient list of the last 16 classes you visited with the present Browser. This is very helpful when you are working on several classes and want to quickly switch. The bracketed '(r)' means that from the keyboard this can be done with Cmd-r.
browse all: This pops up a Hierarchy Browser with all the classes in the system in an alphabetical list, that you can search from the keyboard by inital letter. Since the result is displayed in a Hierarchy Browser you can see immediately what classes are superclasses of a class, if any except Object and ProtoObject.
browse: This starts a new system Browser on the category the cursor is on.
printOut: See fileOut.
fileOut: This puts the whole text of the category in a file on disk in a format Squeak can read in again. You can read it by way of a FileList, if you want to, and edit edit it that way too, though there are handier ways.
reorganize: This write the organization of the classes in the system in the textpane in the form of arrays which you can edit if you want and know what you do. (But this will not be helpful to do unless you know.)
alphabetize: This alphabetizes the organization of the categories. I've never tried it, because it seems for a standard system handier to use the standard organization.
update:
add item: Produces a pop-up with 'Please type new category name'. Here you can add your own category, say by your own name or 'Experimental' or whatever.
rename: The same sort of pop-up with the same question as the previous option, with the difference that the category under the cursor is renamed. If this is a standard system category, such as may well be proposed by code you wish to load, renaming is unwise. If it is a category you made yourself, it matters only if the name is presupposed by code in your system.
remove: This pops up a simple pop-up that asks you whether you really want to remove the category the cursor is on together with all its classes. If this is a standard system category, such as may well be presupposed by code you wish to load, renaming is unwise. If it is a category you made yourself, it matters only if the name is presupposed by code in your system.
2. Class pane
The main pop-up for the class-pane in the system Browser looks like so:
Quite a few of these methods do similar things to similarly named options in the category pane pop-up.
browse full (b): Opens a new system Browser on the class the cursor is on. Useful if you want to look at or edit some other part of the same class, and later return to what's in the present Browser.
browse hierarchy (h): Starts a Hierarchy Browser on the class. Useful if you want to know what are the superclass of a class - which means in programming practice: additional methods you can reach from the class. See the next option.
browse protocol (p): This starts a ProtocolBrowser on the class. This displays all categories and all methods available to the class, and thus all methods in both the class (bold in this ProtocolBrowser) and in its superclasses (at least: Object and ProtoObject). This is quite helpful to see what methods you can call on in the class without getting a DNU (= Does Not Understand) walkback.
printOut: See fileOut.
fileOut: Writes the class to a file on your disk with the name of the class and the '.st' (for 'Smalltalk') extension. If there is already a file of that name Squeak pops up a window to ask whether you want to overwrite that file or want to choose another name. If you want to be sure that code you sweated on is safe, this is a way of saving it and earlier versions. The produced file on disk can be read in a FileList and also can be filed in as code by a FileList, and this gives you an option of sharing your code with others: File it out, and send it to others to file it in.
show hierarchy: This writes the superclasses and classname plus instanceVariables in the textpane of the Browser.
show definition: This displays the definition of the class in the textpane: superclass; classname; instanceVariables; classVariables; pool Dictionary; and category. This is where you start when writing a new class in Squeak. It also allows you to edit the definition, e.g. by adding an instanceVariable (i.e. a slot for data for the class). This command does the same as the instance button in the class pane.
show comment: This command does the same as the ? button in the class pane i.e. displays the comment of the class - if any - in the text pane.
Note on comments: There may be no comment, because the programmer(s) of the class didn't write it. This makes it a lot harder to understand the code for the class quickly (supposing this is not very brief and little), so if you write your own class it makes sense to indicate at least what the objects produced by the class are meant to do.
If a class has no comment, what gets displayed is:
" Main comment stating the purpose of this
class and relevant relationship to other classes.
Possible useful expressions for doIt or printIt.
Structure:
instVar1 type -- comment about the purpose of instVar1
instVar2 type -- comment about the purpose of instVar2
Any further useful comments about the general approach of this implementation. "
inst var refs...: As for inst vars button: Again very useful: A list of the instanceVariables in the class, which are the named dataslots of the class. When you select an instanceVariable from the list, Squeak will pop up a list of methods of the class in which the instanceVariable occurs (also possibly in a comment, by the way). The name of the instanceVariable will be highlighted, so that you see it easily. Since instanceVariables are the dataslots, it is very pleasant to know precisely where they are used in the code. And the code can here be directly edited as well.
inst var defs...:
class var refs...: As for class vars button: A list of the classVariables in the class. This may be only - and often is only - DependentFields (belonging to Object), but in any case a selection from the list will display a list of places in the system where the ClassVariable is used, as for inst vars.
class vars: As for
class refs (N):
rename class...: Produces a pop-up with 'Please type new class name'. Lets you rename the class.
copy class:
remove class (x): Produces a pop-up that asks whether you really want to remove the class and all its methods from the system, and acts according to your answer. Note that it needs not be lost, since it may be in earlier stored images or may be retrieved from the .changes file or may be stored on disk (by a fileOut).
find method...: Pops up a list of the methods in the class, and moves the browser to the selected method. Very useful to quickly jump around in the methods of a class, especially if you know them (more or less).
more...: