Getting started



This document will give you some short information, on how to start & stop the Smalltalk/X development system (IDE) and how to use ST/X for scripting. 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 new to Smalltalk, please take a few minutes, to read this document.

Starting and Stopping Smalltalk/X

Starting Smalltalk/X

To start Smalltalk/X, type "smalltalk" (or "stx") at the Unix (or Windows) prompt.

If you downloaded the developer's package, and did not install ST/X in a standard place, you will have to change the directory first:

    % cd projects/smalltalk
    % ./stx
    <some info messages>
    reading 'private.rc'...
    starting Launcher...
On most Unix systems, the current directory is not in the PATH, and you have to type "./smalltalk" or "./stx".

For historic reasons, the IDE is found in the "projects/smalltalk" subdirectory. One reason was that there are multiple pre-compiled Smalltalk applications found under this folder. Beside the actual IDE, there is a stand alone webserver (which serves the eXept web site), a tinytalk, which is a smalltalk without UI classes, and other helloWorld-like demo programs. You can ignore all those others and only care for "projects/smalltalk".

The "smalltalk" command found there is actually a little shell script, which sets up the LD_LIBRARY path (so the class libraries, which are the libxxx.so files, are found) and calls the real executable "stx".

If your path and ld-library path settings are correct, you can call "stx" directly (if not, try "export LD_LIBRARY_PATH=." before). On most systems today, the LD_LIBRARY_PATH already includes the current directory, and "stx" command works out of the box.

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.
Mac OSX users will almost certainly get a message like "stx not found". This is because the current directory "." is not included in the shell's PATH variable. Please try "./stx" then.

Startup Actions

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 a folder named ".smalltalk" under your home folder, 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 Launcher's 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, Win7/8/10 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 suppressed by a command line argument).

Stopping Smalltalk/X

To leave the Smalltalk system, select the "Exit" item in the Launcher's 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).

You can also type "CTRL-C" at the command propt, where "stx" was started (if it was actually started via the command line). Then, you will get into a mini debugger, which is described below.

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 recommended, that you save a snapshot image in regular intervals (whenever some work has been done). However, it is non-fatal if you do not, because ST/X logs all your programming work in a so called "changes file", which can be replayed (loaded). So even if you do not have a snapshot, it is quite easy to get to the state before, without loosing any of your work.

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.

Please notice, that ST/X does not need an image!

It can (and usually is) started without a snapshot image. All classes and objects (i.e. views,tools etc.) are created and initialized during a normal (non-snapshot) start by sending the "initialize" message to every loaded class, followed by the UI startup, which is actually controlled by a script file.

Restarting Smalltalk/X

When Smalltalk/X is restarted, it looks for a snapshot file named "st.img" (in the current directory or your workspace directory under "~/.smalltalk") and, if present, loads the state found in this file. If not, a normal "clean start" is performed.
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:

    stx -i <nameOfImage.img>
If you want to start Smalltalk/X from scratch, ignoring any existing snapshot image, use the ignore (-I) flag, as in:
    stx -I
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 drag the icon, which represents a snapshot file, on your desktop over the Smalltalk/x icon, or double-click on a snapshot image icon.

Command Line Arguments

Both the ST/X runtime system (VM) and the Smalltalk application / IDE understand a number of command line arguments. Among others, the VM options control the memory management behavior, debug message printing and startup behavior.

All of the "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 or when it encounters a "--" argument (two dashes) and passes the rest to the Smalltalk system (or a Smalltalk application), where it is available as "Smalltalk » commandLineArguments". (also use "--" to pass an argument which conflicts with a VM-option's name to your program)

When ST/X itself is started (i.e. the IDE), the startup method which gets the initial control and which does command line argument parsing is "Smalltalk » start".

When a standalone application is compiled and linked (eg. using the ProjectBuilder), the application's startup-class as specified in the project definition is responsible for this (see the "StandaloneStartup" class for an example).

VM Arguments

Some VM-arguments are specific to the architecture, operating system or ST/X version. To get a full list, type "stx --help".
Some useful VM-arguments are:

Non-VM Arguments

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

Scripting Command Line Options (--eval and --script)

The following command line options allow for Smalltalk scripts to be executed without a graphical user interface and without an IDE (and of course also without a snapshot image).

For scripting, it is recommended to install ST/X at a standard place ("/usr/local/bin", "/opt/smalltalk" under Linux/Unix/OSX, or "c:\Programs\SmalltalkX" under Windows), and to make sure that the ST/X executable's folder is in the path. Then scripts can be executed on the shell level with "stx" or the script's name (as described below).

The scripting options imply a "--silent" option behavior; this means that no diagnostic output is generated (unless you reenable it via an option and of course except output which is generated explicitly by the script).

The individual scripting options are:

Smalltalk/X behaves slightly different when in any of those scripting modes:

Script's Stdin, Stdout and Possible Pitfalls

Scripts usually do not open a UI (although it is perfectly legal, to do so), but communicate with files, sockets or stdin/stdout.

Unless they open up a UI and a Transcript window, the global "Transcript" is bound to "Stderr", so the normal "Transcript show:" and "foo transcribe" constructs will send the output there, and pipes to stdout still work without being polluted by debug messages.

One possible pitfall is the encoding of output: by default, ST/X will expect input and output to be UTF8 encoded, which may or may not be the case in a Windows command window. We may add an automatic mechanism for that in later versions, but for now its best to explicitly state the encoding, by adding two lines such as:

Stdout := EncodedStream stream:Stdout encoder:(CharacterEncoder encoderFor:#'cp850').
Stderr := EncodedStream stream:Stderr encoder:(CharacterEncoder encoderFor:#'cp850').
possibly wrapped into an if (i.e. OperatingSystem isMSWindowsLike ifTrue:[...].
Sorry for the inconvenience, but we were not aware of this problem before (and you won't, unless you use scripts outside the US ;-)

A possibly better solution is to leave the script as is, and instead add a batch file, which changes the encoding of the terminal in the command executes (although, that may lead to trouble with other commands running there - sigh)

Package Run Example

An example for a package-run is found in the Jupyter-kernel setup:
Jupyter is configured to execute "stx --run stx:goodies/communication/jupyterTalk", which contains the kernel, and a main method in its project definition class (stx_goodies_communication_jupyterTalk)
Read more in the Jupyter interface documentation.

Scripting Examples

Command Line Scripting Examples:

stx -E "Delay waitForSeconds:1"
- same as "sleep 1"

stx -P "Smalltalk versionString"
- prints the ST/X version string"

stx -P "4567 * 8975"
- compute and print result

stx -P "a:=4567. a*a*8975"
- compute and print result (the variable "a" is automatically defined)

stx -P "100 factorial"
- compute and print result

stx -F "line asLowercase"
- converts its input to lowercase output (up to an EOF)

stx -F "count := 1" "count := count+1" "count printCR"
- counts the number of lines of its input (up to an EOF). I.e. this is the same as the "wc -l" command under Unix.

stx -E "Workspace open"
- opens a Workspace window

stx -E "WorkspaceApplication open"
- opens a full blown Workspace application

stx -E "Smalltalk loadPackage:'myPack'. MyApp open"
- loads a user package (typically from a binary compiled class library) and runs it

stx --load "myPack" --run "MyApp"
- does the same as above, but is less cryptic

Scripting Hello World Example:

File "hello.stx":
  #!/usr/bin/env stx --script
  'hello, word' printCR.
Execute with:
  > stx --script hello.stx
or even better with:
  > chmod +x hello.stx
  > ./hello.stx

File Scripting Example2:

File "script1.stx":
  #!/usr/bin/env stx --script
  1 to:10 do:[:i |
     'the factorial of %d is %d\n' printf:{ i . i factorial }
Execute with:
  > stx --script script1.stx
or even better with:
  > chmod +x script1.stx
  > ./script1.stx

File Scripting Example3:

File "script2.stx":
  #!/usr/bin/env stx --script
  Workspace open.
Execute with:
  > chmod +x script1.stx
  > ./script2.stx

File Scripting Example4:

Notice the use of the command line argument:
File "script4.stx":
  #!/usr/bin/env stx --script
  1 to: (_$1 asInteger) do:[:i |
     'the factorial of %d is %d\n' printf:{ i . i factorial }
Execute with:
  > chmod +x script4.stx
  > ./script4.stx 25

User Input Requests

If the script executes any of the Dialog requests (i.e. Dialog request:), the usual dialog window appears. To interact via the terminal, use one of the following simple requests:
  Stdin request:prompt.
  Stdin confirm:prompt.

Error Handling in Scripting Mode

In case of an error in script mode without debug option, ST/X print an error message and exits. To enable debugging (with a MiniDebugger), add the "--debug" option (before any -P/-E option). To get a walkback, add a "--debugPrint" or "--verbose" option.

The following examples demonstrate the error behavior (in this case, a division by zero error):

stx -P "1 / 0" prints an error message

stx --debugPrint -P "1 / 0" prints an error message plus walkback

stx --verbose -P "1 / 0" the same

stx --debug -P "1 / 0" opens a mini debugger

stx --silent -P "1 / 0" just returns an error-exit code

REPL (Read-Eval-Print-Loop) Mode Option (--repl)

The "--repl" (or "-R" for short) command line argument starts a read-eval-print-loop, in which expressions can be evaluated in an interactive line-by-line mode. Long evaluations or endless loops can be stopped by presing CTRL-C, which gets you into a MiniDebugger, and the evaluation can be aborted with the 'a(bort)' command.

The repl will auto-declare undefined variables as workspace variables, and their values will be retained between evaluations (like in a Workspace, with the "auto-define-as-Workspace-variables" option enabled). The previous expression's value is available as "_0".

The input can be either in traditional chunk file format or in a special repl-format, where chunks are separated by either an empty line, or a line ending in a "." character (if you want to enter more text, add a space character after the period).

By default, the repl is in non-chunk mode.

While reading, lines beginning in a "#"-character are treated as directives:

If an error is encountered during the evaluation, a line-oriented debugger is invoked (MiniDebugger). By default, you'll be asked if you want to debug, but this can be turned off ("#set debugconfirm false"). You can also completely disable the debugger ("#set nodebug"); if disabled, the cause of the error is printed, and the REPL continues reading the next command/expression.

By default, the REPL shows a hello message, and both command prompts and answer prompts. Give a "--silent" (or "-q") option to disable the hello message and answer prompts (ST/X will behave similar to GNU Smalltalk then). The answer prompt can also be changed by "#clear answerprompt".
Type "#show flags" to see more options.

Example Session (user input in bold):

  > stx -R
  STX> #clear answerprompt
  STX> 10 factorial.
  STX> #set timing
  STX> 100 factorial.
  STX> #clear timing
  STX> x := 10 factorial.
  STX> x + x.
  STX> #show variables
  _0 -> 7257600
  _1 -> 3628800
  _2 -> 9332621544394415268169923885
  _3 -> 3628800
  x -> 3628800...
  STX> 'hello'
  STX> 'hello' asUppercaseFirst.
  STX> 'hello' foo.
  Error encountered: String does not understand: #foo
  Debug (y/n): y
    MiniDebugger> a
    Evaluation aborted.
  STX> #set nodebug
  STX> 'hello' foo.
  Evaluation aborted: String does not understand: #foo
  STX> #clear nodebug
  STX> #read MyApplication.st
  STX> MyApplication start
  STX> ^D
(CTRL-D is the EOF-character on Unix; type CTRL-Z on Windows)

Defaulting Command Line Options via Shell Variables

Two shell environment variables may be defined to provide additional ST/X command line options: These two options may be useful to enforce the old autoload/quickstart behavior on systems with many ST-scripts written for a previous release, or to generally enable/disable certain features, based on the programmer's private environment.

Quickstart Command Line Option (--quick)

this behavior is now the default. So the option is no longer needed. To get the old behavior, use the "--autoload" option. The following chapter describes the old behavior.

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 packages either via the launcher's file menu, pr programatically with

    Smalltalk loadPackage: <packageID>
or by opening a fileBrowser on a directory and applying the "Install Autoloaded Classes" menu function on it. Also, the system workspace includes a page with useful package-loading expressions.

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

Motivation for no longer making this a default behavior:
Because autoloading is only possible in the IDE (where the classes source code is accessible), but not for standalone applications, a common error situation is to access or depend upon classes which were originally autoloaded, but not binary-compiled into a classLibrary-dll. So during development in the IDE, these classes were present and everything worked fine. On the other hand, it lead to a runtime exception in the deployed application. Therefore, it was recommended to always use the "--quick" option during development, so the programmer got informed about any missing class.
We thought, that it is better to avoid such mistakes right away.

Autoload Command Line Option (--autoload)

This option forces the old behavior, where the whole directory tree is scanned for autoloadable classes. This used to be done automatically, but turned out to become both unreasonably slow and dangerous. Please compile any of your classes into packages and load packages. This is both much faster, and also less error prone (read the argument above). If you need the old (scanning) behavior, use the "--autoload" command line argument.

The Debugger

Leaving the Debugger

Whenever some error occurs in Smalltalk, or a breakpoint is encountered, a debugger window pops up (or a MiniDebugger, if scripting), which shows 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 the Smalltalk IDE. 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:

A close of the debugger-window via the button in the window-title area, or the window manager has the same effect as "Abort".

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 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 due to an unhandled error (such as division by zero, or array bounds check etc.) or by an explicit request such as sending a halt-message to an object or a code breakpoint.

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. If your keyboard does not provide such a key, try "CTRL-." which is provided as an alternative (and is also compatible to other Smalltalk system's interrupt key).
(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, this 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'

    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. I.e. this is equivalent to interrupting the program, followed by the debugger's "abort".
(for experts: an AbortOperationRequest exception is raised, instead of UserInterrupt)

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 (Mini-)Debugger

Whenever a serious error occurs within the graphical debugger itself, or when an error occurs during startup (before the GUI has been initialized), or if an error is encountered in a deployed non-GUI standalone application, or in scripting mode, 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 also used in the debugView, or if any other error occurs while the debugView is initializing itself.

You may also get into the MiniDebugger, if you press "CTRL-C" in the terminal window.

The "Q"-command (quick terminate process) terminates the current process without any cleanup actions being performed - this may leave dead windows on your screens which have to be manually destroyed (use the Launcher's tools-destroy view menu function). Be aware, that this may also leave files open and semaphores locked. So this should be used wth great care.

If all of the above fail, you should exit Smalltalk, restart from a previously saved image and reapply any changes using the ChangesBrowser. The MiniDebugger also offers two commands for emergency saving: "S" to save a crash-image, and "C" to save your session changes into a separate changes file.

The crash image can be browsed later with the snapshot image browser, or you can try to restart it (although that will likely fail).

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 menu's entries depend on the type of view and often on the context or type of object/text being displayed. Typically, it offers 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 browser's 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.

Mini Scrollers

Some views which are considered to be less likely to be scrolled often, show a mini scroller. These are thin scrollers, without buttons. They are typically shown in selection lists and require less valuable screen space. Otherwise, they behave like regular scrollbars.

Selecting Text

Text is selected by multiclicks or by moving the left-mouse button while keeping it pressed:
  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.

There are two ways to extend the selection with "SHIFT":

*) note: in previous ST/X versions, the SHIFT-click behaved like the SHIFT-CTRL click behaves now. This was inconvenient, when eg. selecting a literal array or similar parenthized text in the code piece of code and then need to extend that to include the hash-charcter before the left parenthesis. (this might sound strange, but is quite common when editing Smalltalk code).

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. This rule also applies when extending previous word or line selection with a SHIFT click.

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:

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 (also 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.

Special Characters

Special characters, such as math, greek, arrows and other characters which are not found on the keyboard, can be entered via a special-character window, which is opened via the popup menu ("Other" -> "Special Characters"). This window behaves like a keyboard: click on a character to get it inserted into the text. Notice, that most fonts do not contain glyphs for all characters. Such characters will be displayed as a fallback (default) character, which is typically a rectangular empty box. However, even if not drawn correctly, the text will contain the corresponding character, and will be displayed correctly, if a proper font is chosen.


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

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 system browser, 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 default font used by text editors is specified in a preference settings entry. This setting affects the initial font of new text editors. Any individual editor's font can be later changed via its popup menu, and the font size alternatively via keyboard shortcuts or the mouse wheel.

As opposed to many other (Smalltalk-) IDEs, we prefer a fixed-width font for code, as it makes tabular data much easier to look at and leads to a more consistent indentation. Therefore, the default is set to a fixed width "Courier" font. If you don't like this, please change it via the Launcher's settings dialog ("Settings" - "ViewStyle" - "Font").

To change an individual editor's 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, or with the "CTRL-+" (ctrl-plus) and "CTRL--" (ctrl-minus) keys.

In addition, "SHIFT-CTRL-+" and "SHIFT-CTRL--" will change the font sizes of ALL text views.

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 text views which allow "Tab" as regular text input (i.e. all code views).

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 Launcher's "Settings"-"Viewstyle"-"Focus Follows Mouse" checkBox setting.

Notice, that an explicit focus-assignment (eg. 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 middle button menu's 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 (or copy-paste from this example):

    Transcript showCR:'hello'
    Transcript showCR:(100 factorial)
    WorkspaceApplication open
In the workspace, select the text and evaluate it using doIt (if nothing is selected, the whole text of 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 middle button menu's 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
    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.

Also notice that all keyboard shortcuts are defined in the startup scripts (usually in "display.rc"). Read ``Configuration & Customization'' and have a look at the startup files.

Variables and Scope in a doIt Evaluation

Doits are evaluated in a variable scope, which depends on the situation and tool in which it is performed. Especially the visibility of local variables and the meaning of the "self" pseudo variable varies:
In a Workspace
"self" refers to nil. Global variables (Smalltalk bindings) are visible. In addition, special Workspace- and Doit-Variables are optionally visible (see the description in Workspace).
In an Inspector
"self" refers to the inspected object. Direct and inherited instance variables and class variables are visible.
In a Debugger
"self" refers to the receiver of the currently selected context. Like in the code, method local variables, direct and inherited instance variables and class variables are visible.
In a Browser
"self" refers to the selected class. Class variables and private classes are visible.

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
in a workspace (with doIt), or - more convenient - by using the FileBrowser.
To load a file in the FileBrowser, select the file and execute its "fileIn" function from tje middle button menu in the browser's upper (file-list) panel.
As a concrete exercise, fileIn the contents of "stx/clients/Clock/Clock.st. Watch the Transcript for what is going on.

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

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

Importing Code from Other Smalltalk Dialects

Smalltalk/X understands ParcPlace's Smalltalk-80 / VisualWorks, Digitalks Smalltalk/V and Squeak source formats (limited support for IBM's 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.

In practice, most non-graphical classes work unchanged; however, if a loaded class depend on a particular superclass implementation (accessing instance variables), or superclass hierarchy (accessing superclasses by name), this may not be true. In this case, you should open a Changes Browser on the source file, and apply individual changes one-by-one, to see where problems arise.

Packages from Squeak/Pharo can also be imported in their native Monticello package format; for this, use a "Monticello Browser".


To write your own code (classes) or to modify existsing code, open a System Browser 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 System Browser is found in ``Using the SystemBrowser''.
An 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 a little graphical application or a web service.

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


(*) 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 as set in the "keyboard.rc" script. 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 catch some command-key combinations themselfes - NOT passing those key events to ST/X (this is especially true for motif's mwm and fvwm, and for MacOSX, where some CTRL-key combinations might be used for desktop operations) .

If this is the case with (some of) your keys, you may either disable the window manager's key functions (in the wm's resource file) or change the settings (in your "private.rc") to use different control- or command key combinations instead.

Most of the window manager's 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.

Copyright © Claus Gittinger Development & Consulting
Copyright © eXept Software AG

<cg at exept.de>

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