Configuring and Using the Alltalk Browser

Introduction

The browser window is the primary programming interface for Alltalk. 
Using the browser, you can select and modify the source code for Alltalk
classes, usually while your application is running.

Starting Alltalk

The directory that contains the Alltalk executable also has a sample
"startup.alt" file. Microsoft Windows users can launch Alltalk with the
browser and and standard user interface classes by dropping the startup.alt
file on top of the executable (Alltalk.exe on Windows systems.)
Unix users must configure the X-Windows window manager to get this behavior.
Alternatively, Alltalk can started from the command line under Windows
or Unix by running Alltalk with the startup.alt file as a command line
parameter.

Editing the startup file

The startup.alt file contains strings that are parts of file path
names on your system. All the path names used in the startup file
are relative, so you can put your Alltalk directory anywhere.
The path name components contains punctuation that depends on your
operating system. For example, Windows expects the backslash "\" to
separate path components while Unix systems want a forward slash "/".
You must edit your startup.alt file to reflect the syntax used on your
operating system.

Startup file sections

A typical startup.alt file will compile the foundation classes using
a number of INCLUDE directives. It will then create an instance
of the Browser and optionally, a Workspace. Finally, the browser
must be configured to know the locations of your classes. This 
is done with a number of #search expressions that give the path
names to all the directories that contain classes.

The Browser window

The browser has three window panes. The upper left pane displays a
list of all the classes compiled into the system. When you click on
a class, the source code is loaded into the lower source window pane.
The upper right pane will then display all the method selectors for
the selected class. By clicking on a selector, the source pane will
scroll to the method that implements the selector and the first line
of the method will be selected for editing.

Finding classes

When you selected a class, the browser uses an internal list of directories
to find the source file for the class. These directories are specified 
by the #search expressions in your startup.alt file. The list of directories
is search in the order they were specified. 

Using an 'extras' file

It is possible to add methods to classes by putting the method definitions
in other files. This is often done by programmers who want to avoid modifying 
the files that come with the distribution.  One file may contain additional
methods for several different classes.

The browser cannot find and display these methods automatically. All method
selectors for the context class are displayed in the method pane. If you
select a method and it does not scroll into view in the source pane, the
source code for the method is probably in another file. It is conventional to
have a single file in every project called extras.alt.  This file is used
to override or add to methods defined in the standard Views classes.  By
using this file, there is only one other place to look for methods that
are not found automatically by the browser.

Creating a new class

To create a new class, clear the source pane by selecting 'new' from the
'File' menu. Enter the source code for the class and save the file in one
of the directories known to the browser. Under the 'Compile' menu, select
'Class'. The class will be compiled and if there are now errors, the new
class name will appear in the class pane.

Changing or adding methods

You can edit or add new methods to the source file. To compile the method,
move the blinking cursor by clicking anywhere inside the method source.
Under the 'Compile' menu, select 'Method'. The new code is now part of
the system.

Changing the class definition

If you need to add or modify the instance variables in the CLASS section
of the source file, you must create a new class. The new class will have
the same name as the old class. You will need to create new instance objects
to test your changes. Any existing objects that were instances of the old
class will remain unchanged and will continue to have the old protocol.

Duplicate class and method names

Each time you recompile a class definition or a method definition, a duplicate
entry will appear in the class selector pane or method selector pane.  Choosing
any one of the duplicate entries always picks the most recent definition.  They
are displayed to remind you that a previous definition has been compiled. This
is especially helpful when an 'extras.alt' file has been used to update a method
in one of the standard classes. The duplicate entries will disappear the next
time you restart Alltalk and compile your classes from scratch.

Getting lost

If you compile a class source file and it contains syntax errors, the compiler will
not reach the end of the file.  By convention, each source file ends with the compiler
directive "WITH Object" which returns the compiler context to the top level.
After a syntax error, the context class will not be class Object, but rather the class that
contained the error.  This happens because the class definition structure changes the context
class to the newly defined class. When you create new class variables while debugging,
you may unexpectedly add them to the context class where a syntax error last occurred. 
Later, when a file is compiled that contains a "WITH Object" directive, your new variables
will seem to disappear.  They are, of course, still visible in the context of the class
where they were defined.  When in doubt about the compiler context, execute the "WITH Object"
expression in your workspace or listener window.

Evaluating files and expressions

The Compile menu has a selection named All. This selection causes the browser to compile
the currently loaded file.  This operation is used when compiling a file that contains
other INCLUDE directives or global variable assignments used to build an application.
It will also compile a file that contains a class definition, but it will not automatically
rebuild the list of classes in the class selector pane. For this reason, programmers
sometimes use Compile All rather than Compile Class after a class has been previously
compiled and added to the class list. This saves the time required to rebuild the list.

When a group of lines are drag-selected, the Compile Selection menu item will compile
only the selected lines.  The command key combination <COMMAND> R will compile the line
that contain the blinking cursor without needing to select the line.  The entire expression
must fit on one line in this case.

The Workspace window

The last few lines of the startup.alt file contains expressions for creating a Workspace
window.  This window works exactly like the browser, but it has no class or method selection
panes. It is used to conserve space on the desktop and to keep an editable record of
expressions evaluated. (Unlike the listener window, which doesn't allow editing.)

The Compile menu for a workspace contains only the All and Expression selections
discussed above.  The <commmand> R key will also compile single lines.

