Getting Started

An Introduction to Pocket Smalltalk

(Note: This archive must be extracted with a program which supports long filenames, such as WinZip.)

Introduction

This is an initial prerelease beta version of Pocket Smalltalk, a Smalltalk system for the 3com PalmPilot handheld computer. For more information, see the Pocket Smalltalk WWW site at:

http://www.pocketsmalltalk.com

Using the IDE

Upon starting Pocket Smalltalk you will be presented with a small "launcher" window. From here you can launch development tools and perform some other operations. To exit Pocket Smalltalk, close the launcher window or select the System/Exit menu option.

Upon starting, your Smalltalk "image" consists only of a few fundamental classes which the virtual machine requires to operate. Initially, no methods are installed on these clasess. To get a base development image with the usual Smalltalk class library and methods, you must "file-in" the Smalltalk source file named base.st. Do this by using the System/File in... menu option from the launcher.

After the progress indicator has completed, you will have a full development image with which to create your program. You can browse the classes and methods in the base image by opening a class browser (Tools/Class browser from the launcher).

Using the class browser

The class browser gives a hierarchical view of the classes in the image in the upper-left pane. By clicking on the box next to a class name you can expand or contract the display of the subclasses of that class.

The upper-right pane displays a list of method categories. By expanding a method category you can see the methods in that category. The special category named (all) can be used to see all the methods in a class regardless of their category. The Instance/Class tab above the method list allows you to switch which "side" of the class you are looking at (i.e., the metaclass or its instance).

By right-clicking in any pane you can obtain a menu of context-sensitive operations.

The bottom pane presents one of four types of text readout, depending on the setting of the selector in the middle of the class browser:

In any of these views except for Disassembly, you may edit the material and then submit it by right-clicking and selecting Accept.

Adding and modifying classes

The preferred way to add a new class to the image is as follows:

The subclass is created with no instance or class variables, and of the same "type" as its superclass ("type" refers to whether it is a subclass, a variableSubclass, or a variableByteSubclass).

Adding (or removing) class or instance variables, changing the type of the subclass, changing the superclass and renaming the class can all be accomplished by editing the class definition and then selecting Accept. As noted above, the class definition can be obtained by selecting the "Class" tab from the middle of the class browser.

Note that most changes to a class require all the methods in that class and its subclasses to be recompiled. The system may therefore seem to "lock up" for a few seconds during this recompilation. This is normal behavior.

To delete a class, select the class to delete, then use the right-click menu in the upper-left class pane to select Delete class....

Method categories

Pocket Smalltalk method categories, as in all Smalltalk systems, are for documentation purposes only. By default, new methods are placed into the 'uncategorized' category (or the selected category, if there is one). You can recategorize individual methods in one of two ways:

  1. select the method, right-click, and use the Categorize... menu option. This prompts you to type in a category name.
  2. use the Quick categorize... menu option. This presents you with a list of common category names. If the method in question is implemented in a superclass, the name of the category it appears in there will be first on the list.

Note that it is not possible to have an empty method category---categories are automatically removed when there are no methods left in them.

Occasionally you will need to recategorize entire groups of methods. There are two ways to do this, analogous to the two ways described above for categorizing individual methods. By selecting the category name instead of the method name, the above menu options will have the following effects:

Saving your work

Pocket Smalltalk projects can be described completely by their file-out file (.st file). Therefore, saving your project is the same as filing it out. Select System/File out system... from the launcher and be sure to specify a filename different from the base-image .st file. Your project will be written out to the file in the usual Smalltalk fileout format. When you start Pocket Smalltalk again, you can file in this file to continue where you left off.

The forms you have created with the Form Editor are appended to the end of the fileout file encoded in a special binary format. They are loaded automatically when filing in the project.

How to write an application

A Pocket Smalltalk program begins by sending the selector #start to the class named Smalltalk. This works like the "main" routine in C and other languages. Therefore, you should replace the default #start method on the class side of Smalltalk with code to start your application.

Your program will terminate when you return from the #start method. Alternatively, you may send #exit to Smalltalk to end your program early. In fact, Pocket Smalltalk in reality begins by sending #basicStart to Smalltalk, which first calls your #start method, followed by #exit.

The first action of an application which uses the GUI features of the PalmPilot will usually be to launch one of the predefined forms. See the section on forms below for details.

Running your program

In order to run your program you must "compile" it to a .PRC file which can be transferred to your PalmPilot (or to an emulator). Do this by selecting the System/Make PRC... option from the launcher window. After supplying a filename, the compiled file will be created (this takes only a second or two on a modern PC).

After HotSync'ing this file to a PalmPilot, your application will appear in the launcher as usual. If you are using a real PalmPilot and not an emulator, I recommend writing a simple batch file to call INSTAPP (the application install program that comes with your HotSync package) on the generated .PRC file. This will speed the compile-run turnaround cycle.

Note to users of the Debug ROMs

If you are using a PalmPilot emulator with a debug ROM supplied by 3com you will probably get error messages about "Null forms" and so on. These errors are harmless and will be removed in the next verison. For now, the workaround is to use a ROM from a real PalmPilot.

About the Executable Size

This prerelease version of Pocket Smalltalk creates rather large "executable" .PRC files. The supplied class library plus the sample application compile to an approx. 44k .PRC file. This is much larger than necessary and is because of the following reasons:

  1. By default, "debugging" support is turned on. The debugging information allows the MiniDebugger to operate and accounts for approximately 7k of the 44k .PRC file. This debugging information consists of symbol and class names and can be disabled via a launcher menu item. Supporting C code in the virtual machine accounts for another 2k.

  2. The class library has not been trimmed. In a typical application you will not need many of the classes and methods present in the base image. In the future you will be able to "strip" an image before deployment, discarding unused classes and methods. This will decrease .PRC size by another approx. 5k (depending on what you use).

  3. The PalmOS GUI interface classes and virtual machine primitives take a significant amount of space (about 8k total).

  4. The virtual machine is currently written in C. Plans to rewrite the virtual machine in 68k assembly language should greatly decrease the size of the virtual machine (from 20k to approx. 12k).

In summary, future versions will allow you to create truly small executables starting at around 25k for a graphical application (remember, you are getting a full Smalltalk system for 25k). One very great advantage of Pocket Smalltalk over C is that executable size is practically unlimited---with C, you are limited to just 32k of code. (To avoid fragmentation on older (pre-PalmIII) devices, the executable file is segmented into 5-6k segments.) In addition, the ratio of compiled code size to source code size is *much* smaller for Smalltalk than for C. In other words, you can fit much more "logic" into a given executable size with Smalltalk than you can with C once you are past the 25k "break-even" point.

Using the MiniDebugger

When something goes wrong in your Smalltalk program you will be presented with a MiniDebugger window (provided the problem is not too severe). This is similar to a usual Smalltalk debugger but lacks single-step and other features. It is very useful, however, for pinpointing the source of a problem so that you can fix it on the PC.

The top half of the screen contains a list of methods that were called leading up to the error. The most recent method appears at the top of the list. You can scroll down using the small arrows to see more methods.

Below the list of method contexts is a list of local variables for each context. By selecting a context in the upper section, you can see the values of local variables in those contexts. Because some structural information is lost during the compilation process, you will not be able to see the names of local variables, but you can cross-reference them with the development environment to get their names. Note that no distinction is made between arguments and temporary variables in the debugger---arguments start at local_0 and temporaries come after the arguments. So if a particular method has 3 arguments, the first temporary variable would be named local_3.

When you are finished looking around, press the Finished button to terminate the program and return to the application launcher.

Miscellaneous error messages

Sometimes if you do something wrong you will get a strange "fatal error" message. This usually has to do with running out of memory or stack space. Currently these conditions are not handled cleanly, hence the error messages. The errors are harmless, though---just reboot the PalmPilot, fix the problem, and try again.

This prerelease version is compiled with relatively small memory limits---just 1600 objects and a 8k heap. This is still plenty of room to experiment, since classes, methods, literals and other statically defined objects do not subtract from heap memory.

For safety, this version does not write directly into database records to manage its heap. It uses the (small) dynamic memory area; therefore, even otherwise "fatal" bugs will not damage any other databases on your PalmPilot (also, you cannot save the image at runtime). Direct database record usage will follow in a later version when I am sure that everything is working correctly. You will then be able to use very large memory heaps (up to the total free memory size of your PalmPilot).

Using the Form Editor

The Form Editor lets you create graphical user interfaces for the PalmPilot. At the time of this writing, the Form Editor is not yet completed, but it is usable, and provides enough functionality to try out the user-interface features of Pocket Smalltalk.

The Form Editor framework is similar to that used in VisualWorks Smalltalk. You "draw" a user interface in a graphical window. When you save your work, the form is saved in a repository and some code is generated to represent the structure of the form.

Each form is associated with a particular method. When saving a form, this method is automatically generated. It consists of a literal array describing what kinds of elements you have placed on the form, along with the PalmOS resource ID for each element and some extra information. Typically, the methods are part of a subclass of class Application. The methods are always on the "class side" (not the "instance side").

At runtime, you can display a form by sending the message #show: to the appropriate Application subclass. The argument to #show: is a selector specifying which form layout to use. For example:

	MyApplication show: #myForm
will show the #myForm form of MyApplication, assuming you have created the appropriate form with the Form Editor.

When #show: is sent to a subclass of Application, several things happen. First, a new Form instance is created and populated with FormObject subclass instances according to the literal array specified by the form layout selector. Next, a new instance of the Application subclass is created and sent #initialize. Then, the new Form asks the new Application for various "aspects" (see below) to control the values of the user interface objects on the form. Finally, the form is displayed on the PalmPilot's screen and user interface events are handled until the user exits the application or switches to a new form.

Each user interface object on a form can be associated with an "aspect". An aspect is a model which controls the information displayed by the user interface object. For example, a text field object would have an aspect model which is a ValueHolder containing a string. When the aspect model changes, the user interface object updates graphically; conversely, when the user modifies a user interface object, the corresponding aspect model updates. By registering interest in the dependency events generated by aspect models you can create arbitrary connections between user interface objects.

When building a form using the Form Editor, you may set the aspect of any user interface object to a symbol. This symbol will be sent as a selector to the Application instance at runtime upon starting the form by sending #show: to the Application subclass. The aspect method must return an appropriately initialized aspect model, as described above.

Using the Alert dialogs

At this point (until the complete PalmOS user interface system is completed), the recommended way to test your Pocket Smalltalk programs is to use the Alert class to display messages. Four methods on the class side of Alert provide ways to pop up simple dialog boxes:

	Alert confirm: 'Do you want to delete all your files?'
	Alert warning: 'All your files will be deleted!'
	Alert notify: 'Your files have been deleted.'
	Alert error: 'Could not delete your files!'
These methods accept only strings, so to print arbitrary objects you must send #printString to the objects:

	Alert notify: (List with: 123 with: #() with: 'hello') printString
Alert confirm: can be used to ask a yes-no question. If the user selects "OK", the message answers true. If "Cancel" is selected, false is answered.

What are all those weird files?

The archive for Pocket Smalltalk contains a number of files with extensions of .bin and .grc. These are required for the "Make PRC..." option and become part of the "compiled" .PRC file. These files contain various PalmOS resources, including the compiled form of the virtual machine. The Pocket Smalltalk compiler supplies the remaining resources (compiled classes, etc.) to complete the finished .PRC file. You must not rename or remove the .bin and .grc files---the IDE is currently hardwired to use a fixed set of filenames (this will be changed in the future).

Getting Help

Since this is a prerelease beta version, there are bound to be some problems. If you find a bug, or need to ask a question, e-mail me at: ajb@tiac.net. For updates and information about Pocket Smalltalk refer to the Pocket Smalltalk WWW site at:

http://www.pocketsmalltalk.com

PLEASE NOTE: I reserve the right to publish any e-mail sent to me concerning Pocket Smalltalk (along with any responses) on the WWW site in order to help other users. If you do not want your mail publicized, please indicate that in your message.

Thanks for your interest in Pocket Smalltalk!


Andrew Brault (ajb@tiac.net)