[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.

If you are new to Smalltalk/X, or even to Smalltalk, please take the 5 minutes, to read this document.

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 ...
There is also a shortcut named "stx", which works also. Of course, you can also double-click on the icon in the K-, Gnome or Windows desktop or file manager.

Windows-users will find two executables: "stx.exe" and "stx.com". The difference is described below.

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 and a Workspace window. The Launcher provides menus and buttons for the most common actions and also a Transcript view, which plays the role of a smalltalk console where relevant system information is shown (for example: info and warning messages).
Other tools which can be opened via the Launchers menu and toolbar 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 to 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''.

Console vs. Non-Console Operation (Win32)

Notice that for windows operating systems (Win-NT, Win-2K, Win-XP, Vista etc.), two executables are provided: "stx.com" and "stx.exe".

The first ("stx.com") is a console application, which shows a command-window into which trace and debug info is written. It is also used to communicate with the user in case of a hard internal error, if the graphical debugger is no longer working, or if st/x has been built without graphical debugging support.

The second ("stx.exe") is a non-console application. If it ever encounters problems, there is no way to communicate with the user, and it will finish (just like all other windows applications do).
However, it does write its diagnostic output to a log file (defaults to "smalltalk.log", unless specified by a command line argument).

Stopping Smalltalk/X

To leave the smalltalk system, select the "Exit" item in the Launchers file menu ("File"->"Exit").
The Launcher will ask you to confirm before exiting.

An attempt to close the launcher window (via the windows close-button) leads to a confirmation dialog. This gives you a chance to either stop smalltalk (and close all of its windows) or to only close the Launcher (and leave other windows open).

Snapshot Image

You can leave the system both with and without saving a so called snapshot image. If a snapshot is taken, smalltalk will save its complete 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 and meaningful names for the snapshots.

Restarting Smalltalk/X

When Smalltalk/X is restarted, it looks for a snapshot file named "st.img" (in the current directory) and, if present, loads 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, start Smalltalk/X with an image (-i) argument as in:

    smalltalk -i <nameOfImage.img>
If you want to start Smalltalk/X from scratch, ignoring any existing snapshot image, use the ignore (-I) 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.

On modern graphical operating systems, you can also simply drag the file-icon, which represents a snapshot file, over the Smalltalk/x icon on your desktop.

Command Line Arguments

The ST/X runtime system understands a number of command line arguments. Among others, these control the memory management behavior, debug message printing and startup behavior. All of these so called VM-Arguments must occur before any command line arguments for the smalltalk application (the Non-VM-Arguments).
The runtime system's command line parser stops after the last recognized VM-argument and passes the rest to the Smalltalk system.

VM-Arguments

Valid VM-Arguments are:

Non-VM-Arguments

Valid non-VM (i.e. arguments interpreted by the Smalltalk system) are:

Quickstart Command Line Option (--quick)

When started without a snapshot image, Smalltalk/x first does a recursive scan of all directories below the stx-top directory for autoloadable packages. This is done for your convenience, so that many tools, demos and other support classes are already present as autoload-stubs in the class hierarchy. Autoloaded classes are simple proxy objects which perform an on-demand lazy loading of missing code for you.

This recursive scan can be somewhat slow if many directories are present or the filesystem is slow (on a network drive). It is therefore often useful to start the system without autoloaded classes, and load missing packags either via

    Smalltalk loadPackage: <packageID>
or by opening a fileBrowser on a directory and applying the "Install Autoloaded Classes" menu function on it.

To start ST/X without autoloaded classes, use the "--quick" command line option.

Notice: Because autoloading is only possible in the IDE (where the classes source code is accessable), but not for standalone applications, a common error situation is to access or depend upon classes which were originally autoloaded, but are not binary-compiled in a classLibrary-dll. So any use of an autoloaded class will not be detected in the IDE, but on the other hand result in a runtime exception in the deployed application. Therefore, it is recommended to use the "--quick" option if you are going to test an application which is to be deployed as standAlone application later.

Leaving the Debugger

Whenever some error occurs in smalltalk, or a breakpoint is encountered, a debugger window pops 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.

You should be aware that the debugger is one of your best friends in smalltalk. In contrast to other programming languages, getting into the debugger is far from being fatal in smalltalk. In fact, many smalltalk programmers place breakpoints into as yet unimplemented branches of their source, and develop the program almost exclusively inside the debugger, by adding the missing code, as the halts are reached. This ensures, that all of the code has been reached at least once and has already been tested at least once when the coding is complete.


The debugger's actions are controlled by a set of buttons, a main menu, and a popup menu in the walkback view (for the less frequently used functions).

The most useful button actions are:

Simple closing the debugger via the button in the window-title area, has the same effect as Abort.

There are many other button and menu functions in the debugger. Read ``Using the debugger'' for more information.

Hint:
When you are new to the system, you probably should not care about all of those options; simply press Abort or the close-button in the windows title area to get out of the faulty computation.

Entering the Debugger

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

You can also type the interrupt key "Break/Pause" in any view, to force the corresponding view-process to be interrupted and to enter the debugger. Thus, to interrupt an ongoing doIt, simply press "Break/Pause" into the workspace window.
(The key used to be "Ctrl-c" in previous Unix versions, but has been changed to have a unified keyboard mapping across systems. "Ctrl-c" is now copy on all systems.)

Finally, pressing "CTRL-c" in the terminal (xterm- or console) window where smalltalk was started, forces a hard-interrupt, which interrupts any running process - even the scheduler, event dispatcher, other system process. This will usually bring you into a so called Minidebugger (see below), a very simple command line debugger. If ST/X does not even respond to "CTRL-c" in the terminal window, try quickly pressing it twice or more times.

The Minidebugger is especially useful to leave endless loops in undebugged user primitive code or if you made a mistake in changing some system code.

On some Unix systems, the interrupt key is labeled "INTR" or "DEL".
If "CTRL-c" does not work in your xterm, read the Unix manual page on the `stty' command for details.

Notice, that you can 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 terminal 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-Break".
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-Break" key handling is a functionality of the smalltalk event handler - it does not work in the terminal window.
(Notice: in previous releases, this function used to be on the "Ctrl-y" key-combination. This has been changed to conform to standard conventions. "Ctrl-y" now means "redo")

Leaving the low-level emergency Debugger

Whenever a serious error occurs within the debugger itself, or when an error occurs during startup (before the GUI has been initialized) you may find yourself in a line-by-line debugger called the MiniDebugger. This MiniDebugger allows for some limited debugging without using the graphical user interface.

The system considers errors occuring in the graphical debugger itself 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 right mouse button in the view. (Historically, it was located on the middle mouse button, and is therefore sometimes referred to as middleButtonMenu; however, this naming is historic, you can customize your mouse buttons, if you don't 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

Scrolling using Scrollbars

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

Scrolling using the Mouse-Wheel

If your mouse has a mouseWheel, the scroll amount can be adjusted via the control- and shift keys as follows:

Scrolling using Cursor-Keys

Text-windows can also be scrolled by pressing the "CTRL" key together with a cursor key.

Of course, moving the text-cursor in a textView or moving the selection in a list-view via the cursor keys also leads to a scroll operation if required.

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.

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 or keyboard shortcuts (so called keyboard accelerators). Because all text views are based on a common EditTextView class, the behavior of all of them is similar.

Most editors allow you to type in changes in a modeless fashion anywhere on the editors window area (i.e. there are no invisible and hidden tabulators or end-of-line characters embedded). Like on a piece of paper, you can position the text-cursor whereever you like, and start typing text. The editor will insert blanks or empty lines automatically, as required. This behavior can be turned off by checking the "ST80 Cursor Behavior"-flag in the ("Settings" - "Tools" - "Editor") settings dialog.

Accepting

Text is usually not stored (or installed), until "accepted". What exactly "accept" means depends on the context: in a file-browser, it means that the changed contents is written back to the file. In a class-browser, it means that the changed code is compiled and installed.

The opposite of "accept" is "cancel". This will undo you changes and revert back to the last saved ("accepted") version.

As an option, the class browser adds two buttons to its code-editor window. These allow for very quick "accept" or "cancel". Also, they give a very prominent feedback on the modification state of the text.

Keyboard Accelerators / Function Keys


Notice that the function key mapping may be different on some systems. If in doubt, open the "settings"-"keyboard-mappings" dialog in the launcher. This shows a list of the actual mapping. Also, it is controlled by two files which are consulted during startup ("keyboard.rc" and "keyboardMacros.rc"), which can be changed and reconsulted, of course. 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).

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 commands are available in views which show Smalltalk code (i.e. Browsers and Debugger):

No change in the text will have any permanent effect, unless you accept the new text. Thus, to revert back to the original code in a systemBrowser, simply reselect the method again.

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.

Changing the Font

The font used by texteditors is normally specified in a preference settings entry. As opposed to many others, we prefer a fixed-width font for code, as it makes tabular data much easier to look at. Therefore, the default is set to a Courier font. If you don't like this, please change it via the Launcher's settings dialog ("Settings" - "ViewStyle" - "Font"). This setting affects the initial font of new texteditors.

To change an individual editors font (i.e. one which is already open), open its font selection dialog via the "Other" - "Other" - "Font"-PopUp Menu Item.
The font size can be quickly changed by turning the Mouse-Wheel while keeping the "CTRL"-Key pressed.

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 don't 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 evaluates the corresponding smalltalk expressions.
To try it, open a workspace and type:

    Transcript showCR:'hello'
or:
    Transcript showCR:(100 factorial)
or:
    WorkspaceApplication open
In the workspace, select the text and evaluate it using doIt.
(If nothing is selected, the text in the current cursor line is evaluated.)

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; however, after the evaluation, 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
(the factorial operation computes the product 1*2*3*4*...*100)

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
or
    Point x:10 y:25
Each has a convenient keyboard shortcut: In addition, it is often convenient to open a browser on an expression's class (especially, if the expression consists of the global variable which names that class) For this, use the browseIt shortcut function:

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

Notice: in previous versions, interrupt used to be mapped to "CTRL-c" and abort to "CTRL-y". This has been changed for standard conformance. "CTRL-c" is now always copy and "CTRL-y" is redo.

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 $