[up]

Getting started

Contents

Introduction

This document will give you some short information, on how to start & stop the system. You will also learn how to leave the system once you entered the debugger or if the system seems not to respond anymore. Also, you will get a short introduction of how to edit text, use the scrollbars and how to evaluate smalltalk expressions.

Starting Smalltalk/X

To start Smalltalk/X, type "smalltalk" at the Unix (or MSDos) prompt:
    % smalltalk
    <some time passes>
    installing autoloaded classes ...
    installing patches ...
    starting Transcript ...
    starting main-menu ...
When started, Smalltalk/X first reads and evaluates a script-file called "smalltalk.rc", which consists of regular smalltalk expressions in fileOut-format (i.e. smalltalk expressions separated by an exclamation mark '!').
Smalltalk looks for this file FIRST in your current directory, THEN in some standard places (usually "/opt/smalltalk/lib" or "/usr/local/lib/smalltalk/" under Unix and "\Programs\smalltalk\lib" under MSDos).

After setting up various defaults (keyboard maps, function keys, view style etc.), this script finally starts up a Launcher window.
The Launcher provides menus and buttons for the most common actions and also a Transcript view.

The Transcript plays the role of a smalltalk console where relevant system information is shown. The Launcher allows startup of other useful tools which are described in more detail later.

When you are new to the system, you probably do not want (need) to modify those startup script files - the setup done there should be perfect for most users.

However, you can of course modify the startup scripts according your personal preferences and/or add your own startup tools there.
More info on these script files and startup actions is found in the documents ``installation'' and especially in ``configuration & customization''.

Stopping Smalltalk/X

To leave the smalltalk system, use the exit function in the Launchers file menu (file->exit).
The launcher will ask you to confirm before exiting.

Simply closing the launcher window does NOT exit the system. Instead, ST/X stays running and continues to serve any other open window(s).

You can leave the system both with and without saving a so called snapshot image. If a snapshot is taken, smalltalk will save the current state in a snapshot file, from which you can restart and continue your work where you left.

It is highly recommended, that you save a snapshot image in regular intervals (whenever some work has been done).
You may of course have multiple snapshot images around, either to separate projects, or to be able to quickly return to various previous states of your work.
Use different names for the snapshots.

Restarting Smalltalk/X

When Smalltalk/X is restarted, it will look for a snapshot file named "st.img" (in the current directory) and, if present, load the state found in this file.
This allows you to continue your work anytime later, right at the point where you left it (if you saved a snapshot image - of course).

If you saved your snapshot under another name, give it an image argument as in:

    smalltalk -i nameOfImage.img
If you want to start Smalltalk/X from scratch, ignoring any existing snapshot image, use the ignore flag, as in:
    smalltalk -I
Hint/trick:
On Unix systems, you can also change the permissions of the snapshot file to be executable (i.e. "chmod +x st.img") and make certain that a Smalltalk/X executable is found along the path by the name "stx".
Then, the snapshot file can be restarted simply by entering its name to the shell prompt.

You can also rename the snapshot image to whatever name you prefer (such as "myImage"), and make it executable.
This allows startup of an (application-) snapshot image simply by its name.

Leaving the Debugger

Whenever some error occurs in smalltalk, a debugger window is popped up, showing where the error occurred and how the system got there (this is called a backtrace or walkback).
Since you may sooner or later get into the debugger, it is useful to give a brief description of how to get back to your normal work.
The debuggers actions are controlled by a set of buttons, and a popup menu in the walkback view (for the less frequently used functions).

The most useful button actions are:

There are many other button and menu functions in the debugger. Read ``using the debugger'' for more information.
When you are new to the system, you probably should not care about all of those options; simply press abort to get out of the faulty computation.

Entering the Debugger

The debugger can be entered either on request (for example: by sending #halt to any object), via a breakpoint or if an error such as division by zero, array bounds check etc. occurs.

You can also type "CTRL-C" in any view, to force the corresponding view process to be interrupted and enter the debugger.
(under Windows, press the "Interrupt" key)

Finally, pressing "CTRL-C" in the terminal (xterm-) window where smalltalk was started, forces a hard-interrupt, which interrupts any running process - even the scheduler, event dispatcher or other system process.

If ST/X does not even respond to "CTRL-C" in the xterm window, try fastly pressing it twice. This should bring you either into a miniDebugger (see below) or a low-level interrupt handler which allows termination of any activity (even uninterruptable ones).
This is especially useful to leave endless loops in undebugged user primitive code.

(On some systems, the "CTRL-C" key is labeled "INTR" or "DEL".
Read the Unix manual page on the `stty' command for details.)

Notice, that you may have multiple debuggers open at the same time, operating on different processes. However, only one so called modal debugger may operate on the scheduler or event dispatcher process. Pressing the interrupt key in the xterm window will usually bring you into a modal debugger.

If you want me to open a debugger for you, press:.

or evaluate one of the following in a workspace:

    self halt:'stopped for debug'
or
    |someVariable|

    someVariable := 0.
    Transcript showCR:(5 / someVariable)

Aborting without entering the Debugger

If you simply want to abort some ongoing operation in some view (for example, a long evaluation in a workspace, or a file-load operation in a Filebrowser), you can also type "CTRL-Y".
This also interrupts the process in whatever it is doing, but aborts the operation without entering a debugger.
(for experts: the AbortSignal is raised, instead of the UserInterruptSignal)

The "CTRL-Y" key handling is a functionality of the smalltalk event handler - it does not work in the xterm.

Leaving the low-level emergency Debugger

Whenever a serious error occurs within the debugger itself, you will find yourself in a line-by-line debugger called the MiniDebugger, which allows some limited debugging without using the graphical user interface.

The system considers errors occuring in a graphical debugger as serious (for example, if you have changed the Scrollbar class which is used indirectly in the debugView, or any other error occurs while the debugView is initializing itself.)

You may also get into the MiniDebugger, if you press "CTRL-C" a few times quickly on the terminal window (this sends a userInterrupt signal to the debugger while in its startup phase - and is handled like above mentioned recursive error).

The last command (quick terminate process) terminates the current process without any cleanup procedure - this may leave dead windows on your screens which have to be manually destroyed (use the launchers tools-destroy view menu function)

If all of the above fail, you should exit smalltalk and restart from a previously saved image.

In rare cases (other smalltalk processes are running, and the scheduler suspended the debuggers process), the MiniDebugger may seem to not react to your input.
If this happens, press the interrupt key again (as described above) and try again. The interrupt should reenter the MiniDebugger in an exclusive input mode and stop any scheduling of other processes.

PopUp menus

Most views offer functions via a PopUpMenu. This menu is activated by pressing the middle (or, if you own a 2-button mouse, the right) mouse button in the view. Therefore, it is sometimes referred to as middleButtonMenu; however, this naming is historic, you can customize your mouse buttons, if you dont like this (left-handers typically prefer things to be vice versa).
Read ``configuration & customization'' on how this is done.

The menus entries depend on the type of view and often on the context or type of object/text being displayed. Typically, they offer operations on the contents or the current selection.

Some views offer an extra control-middleButtonMenu, which is activated if the "CTRL" key is pressed simultaneously with the mouse button.
These control menus provide additional functions - which are either seldom needed or perform ST/X's developers hidden private goody operations ;-).
However, they may be useful for others too - try the control menu in the browsers code view or its class list (select a class first).

Scrolling Text

The scrollbars shown beside the actual text work as usual, however, they provide the following special behavior: (see more on text positioning in the section on keyboard commands).

Selecting Text

Text is selected using the left-mouse button:
  1. press the button over the first character to be selected,
  2. while-being pressed, move the mouse-pointer to the end position
  3. release the mouse-button.
The current selection will be highlighted. Pressing the left mouse button again makes the system forget the old selection and start a new one, except when you press the "SHIFT" key while pressing the button.
In this case, the current selection will be expanded. You can expand a selection at any time, even if you leave and reenter the view containing the selection. It is therefore possible, to scroll the view (using the scrollbar) or perform any other function (page-up or page-down), required to make the desired end-position visible. A selection can be expanded in both directions, any number of times.

It is also possible to move the mouse pointer out of the view, while the mouse button is kept pressed. The view will then start to automatically scroll. The farther away you move the pointer from the views border, the faster will it scroll. This is the easiest way of selecting text: just let it scroll by and stop when the end-position arrives.

A double click selects the word under the mouse pointer, a triple click selects the whole line. Finally, a quadruple click selects the whole text.

If you keep the button pressed and start to move after a double click, it continues to select whole words; moving after a triple click continues to select whole lines.

If you double click one of a parenthesis, bracket or brace, the text up to and including the matching one is selected.

Notice, ST/X differentiates between two types of selections:

These behave different, when a key is pressed or text is pasted:
a user selection is replaced by the characters entered at the keyboard, or by pasting text from the clipboard.
In contrast, already pasted text is not again replaced; instead, new text as entered or pasted is inserted behind the selection. (allowing for multiple paste operations to be performed).
In some viewStyles, pasted selections are shown in a slightly different color, than regular selections.

There are also two convenient keyboard shortcuts (*) for selecting:

Notice:
In smalltalk, selecting has always been a separate action than copying. To copy something into a buffer, you first have to select the text then do a copy action.
In contrast to that, X-Window's xterm and toolkit views use a different style where select and copy are combined; whenever text is selected, this is automatically placed into the copy buffer.

Especially when new to the system, this may be a bit confusing.
(My personal feeling is that X's behavior is a result of a poor design, which was later made a ``feature'' - especially with the newest xterms, where you have to press "SHIFT" in addition, making things even more confusing ;-)

Editing Text

All views which show text allow you to perform the usual functions via their middleButtonMenu. For some of them, keyboard shortcuts (also called keyboard accelerators) are available (actually there are more functions available via the keyboard than there are on the menu). Currently, the following keyboard functions are available:

Keyboard Accelerators

Command key functions (**):
Notice: on some systems, these functions are assigned to the CTRL-Key modifier. Some keyboards (for example on Sun workstations) provide function keys labeled "copy", "cut", "paste" and so on. These keys should also behave as expected (this depends on your startup file).

control-key functions, these allow more cursor positioning:

other functions which affect the cursor position:

function-keys (these are configured during startup, by the 'keyboard.rc' script-file):

The following keyboard command is available in views which show code (i.e. Browsers) and the File- and ChangeBrowser: The following keyboard command is available in views which show Smalltalk code (i.e. Browsers):

Sorry:
currently there is no undo functionality. However, no change in the text will have any permanent effect, unless you accept the new text. Thus, in the systemBrowser, simply select the method again to undo any changes. In the fileBrowser, doubleClick on the file being edited.
(this is temporary workaround, of course; an undo function will be added in a later release.)

Please read ``Keyboard commands'' in ``configuration & customization'' on how to add/change function keys settings. Especially, if your window manager (motif) catches some of these keys for its own window operations, you may have to change (some of) these settings. (i.e. use "CTRL" instead of "CMD").
Finally, see the keyPress:x:y: methods in the TextView class and its subclasses. You can easily modify these to add more functions.

In addition to using (and defining keys for) those builtin functions, it is also possible to define your own text or action macros. Read ``Keyboard macros'' in ``configuration & customization'' for more info on this.

Moving the Keyboard Focus (Tabbing)

Within a complex view or a dialog, the keyboard focus can be stepped through the fields by pressing "Tab" or "SHIFT-Tab".
This works for all components, except textViews which allow "Tab" as regular text input (i.e. all codeViews).

If you dont like this behavior, define an additional pair of tabbing keys, to function as (alternative) "FocusNext" and "FocusPrevious" keys.
Using the keyboard map, these can be set to "Alt-CursorLeft" and "Alt-CursorRight", for example.
(the default mapping defines both "Alt" and "Ctrl" combinations of the cursor keys.)

A dialog can be quickly closed (cancelled) with the "Escape" key.

Focus mode (focus-follows-mouse vs. focus-on-click)

Depending on your personal preference, the keyboard focus can be configured to either follow the mouse pointer automatically ('focus-follows-mouse' mode) or to change when a widget is clicked upon ('focus-on-click' mode).
To change this, change the launchers 'settings-misc-focus-follows-mouse' checkBox setting.

Notice, that an explicit focus-assignment (via tabbing) is never changed by simple mouse movements.

Evaluating Smalltalk Expressions

Most views which show code and especially workspaces allow you to select some text and immediately evaluate this as a smalltalk expression (remember the old Basic-interpreters ? :-).
This is very useful to try out things quickly without actually creating a program for it. Your first experiments should probably be done in a workspace.

The middleButtonMenus doIt function does this; it parses the selected text (i.e. checks it for being a correct piece of smalltalk code) and silently evaluating the corresponding smalltalk expressions.
To try it, open a workspace and type:

    Transcript showCR:'hello'
or:
    Transcript showCR:(100 factorial)
or:
    Workspace open
In the workspace, select the text and evaluate it using doIt.

Unless the expression does some printing itself (as in the first two examples), the result of the evaluation is not shown anywhere.
To see the result of such an evaluation, use the middleButtonMenus printIt function.
Just like doIt, this evaluates the expression; in addition, it inserts a printed representation of the result at the current text-cursor position.
See the difference between doIt and printIt when executing:

    100 factorial

Finally, inspectIt opens an inspector window on the result, where you can have a look at the resulting object in more detail.
Try to inspect the result of:

    Array new:10
Each has a convenient keyboard shortcut:

In case you run into an endless loop, or the evaluation takes too long, the evaluation may be interrupted or aborted with:

Under Win32, the 'interrupt' key is mapped to "BREAK", since "CTRL-C" is used for the copy-selection function.

Notice that these keyboard shortcuts are defined in the startup scripts (usually in "display.rc). Read ``configuration & customization'' and have a look at the startup files.

Loading Existing Code / Using the FileBrowser

Files containing smalltalk code (in fileOut-format), binary bytecode ('.cls'-files) or compiled machineCode ('.so' or '.dll' files) can be loaded into the system either by evaluating:
    Smalltalk fileIn:filename
using doIt in a workspace, or, more comfortable, using the FileBrowser.
To load a file in the FileBrowser, select the file and perform its middleButtonMenus fileIn function in the browsers upper (file-list) panel.
As a concrete exercise, fileIn the contents of "source/TicTacToe.st. Watch the Transcript for what is going on.

Smalltalk/X understands ParcPlace's Smalltalk-80 / VisualWorks, Digitalks Smalltalk/V and Squeak source formats (limited support for IBMs VisualAge is also available).

Non-graphical classes should work (almost) unchanged even if they originated from these systems - if you find interesting code on an ftp-archive, you may also try to fileIn this.

Although ST/X was written to be protocol compatible to other smalltalk implementations (i.e. ANSI-Smalltalk), most classes were implemented differently and internals are completely different. Loaded code depending on such internals may not work as expected. For non-graphical classes, this is especially true, if classes depend on a particular superclass implementation (accessing instance variables), superclass hierarchy (accessing superclasses by name).

To see the contents of a file, double-click on its name in the fileBrowsers top list. Also directories are changed in this way.

More info on the fileBrowser is found in ``using the FileBrowser''.

Programming

To write your own code (classes) or to modify existsing code, open a SystemBrowser which is the central tool for programmers.

Start by examining existing simple demo programs (such as the ClockView, TicTacToe, PenDemo etc.
All classes also include a documentation method category, where you will find two methods called documentation and examples.
The examples can be selected in the browser and evaluated via the doIt menu function.

More info on the systemBrowser is found in ``using the SystemBrowser''.
A beginners introduction to smalltalk and programming is found in the ``Smalltalk beginners tutorial''.

Learning Smalltalk

If you are new to smalltalk, start by learning how to use the non graphical basic classes. A very quick introduction to the language and classes is found in the ``tutorial''.

For a rough overview of what is there, read ``basic classes overview'' and start excursions to the classes encountered there.
Many classes contain example methods in their documentation category. Try these, and understand what is going on there. Also, many methods (especially in the collection classes) contain a comment with some sample expressions at the end. These are meant to show short typical uses of those methods.

Getting more used to the language, try creating views. Start by reusing existing widgets and combine them into more complex ones. There are many widgets ready for reuse - you better look what is there, before hurrying to program your own ones.

Read and understand the coding examples found in the directories "doc/coding" and "clients/Demos".

Notes:

(*) keyboard shortCuts
The keyboard shortcuts as described here are not hard-coded; instead, the bindings of keys to functions is done in your startup scripts. This document describes the default bindings. See ``keyboard settings'' on how to change these.

(**) command key
The command key is labeled different on some keyboards; try "ALT", "CMD", "META" or similar.

Notice that some window managers (especially: motifs mwm and fvwm) catch some command-key combinations themselfes - NOT passing those key events to ST/X.
If this is the case with (some of) your keys, you should either disable the window managers key functions (in the wm's resource file) or change the settings (in your "private.rc") to use control-key combinations, function keys or other command-key combinations instead.

Most of the window managers key functions are hardly ever used if you have a mouse hooked to your system - so it may be preferrable to disable those, Instead of redefining ST/X's key mapping.


[stx-logo]
Copyright © Claus Gittinger Development & Consulting
Copyright © eXept Software AG

<cg@exept.de>

Doc $Revision: 1.29 $ $Date: 1999/07/07 14:09:52 $