If you are new to Smalltalk/X, or even to Smalltalk, please take the 5 minutes, to read this document.
"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''.
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).
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).
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.
"st.img"
(in the current directory)
and, if present, loads the state found in this file.
If you saved your snapshot under another name, start Smalltalk/X with an image (-i) argument
as in:
If you want to start Smalltalk/X from scratch,
ignoring any existing snapshot image,
use the ignore (-I) flag, as in:
smalltalk -i <nameOfImage.img>
Hint/trick:
smalltalk -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 simply drag the file-icon, which represents a snapshot file, over the Smalltalk/x icon on your desktop.
-i <snapshotFileName>
-I
--help
--noLog
--logFile <fileName>
--noBanner <fileName>
-Tinit
--quick
--eval "<st-expression>
"
--scripting <portNr>
[--allowHost <host>
]
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
or by opening a fileBrowser on a directory and applying the "Install Autoloaded Classes" menu function
on it.
Smalltalk loadPackage: <packageID>
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.
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:
AbortSignal
is raised,
for which an exception handler exists in the windows main event loop.)
The terminate function is disabled, if the affected process is the scheduler or the event dispatcher process (since if those were terminated, proper operation of the system would no longer be possible).
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.
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.
or evaluate one of the following in a workspace:
or
self halt:'stopped for debug'
|someVariable|
someVariable := 0.
Transcript showCR:(5 / someVariable)
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")
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).
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.
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).
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.
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:
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 ;-)
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.
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.
If you press the "Shift" key in addition (i.e. "CMD-SHIFT-V"), a list of previously copied text fragments is shown, from which you can choose the text that should be pasted).
Cursor positioning:
Function-keys (these are configured during startup, by the "keyboard.rc" script-file):
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.
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.
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.
Notice, that an explicit focus-assignment (via tabbing) is never changed by simple mouse movements.
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:
or:
Transcript showCR:'hello'
or:
Transcript showCR:(100 factorial)
In the workspace, select the text and evaluate it using doIt.
WorkspaceApplication open
(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:
(the factorial operation computes the product 1*2*3*4*...*100)
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:
or
Array new:10
Each has a convenient keyboard shortcut:
Point x:10 y:25
In case you run into an endless loop, or the evaluation takes too long, the evaluation may be interrupted or aborted with:
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.
Smalltalk fileIn:filename
using doIt in a workspace,
or, more comfortable, using the FileBrowser.
"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''.
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''.
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"
.
(**) 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.
Copyright © Claus Gittinger Development & Consulting
Copyright © eXept Software AG
<cg@exept.de>