4. Interfacing with the PalmOS

Pocket Smalltalk provides full support for accessing PalmOS functionality from within Smalltalk programs. Your programs can use PalmOS GUI resources (forms, alerts, menus, etc.) and you have access to the over 800 PalmOS API functions. This chapter describes how to use this functionality.

Using PalmOS Resources

You can instruct Pocket Smalltalk to "link" one or more PalmOS resource databases into the finished "executable" .PRC file. The compiler will combine the resources in each database you specify, along with new resources for the compiled Smalltalk methods and objects, into the final .PRC file. Therefore, you can refer to resources in your Smalltalk program by their resource ID, just as you would when writing in C or another language.

The mechanism for including resource databases in your project will be explained in a later chapter. Briefly, you must use the Constants Browser to create one or more named constants containing the filenames of the resource databases to use.

Calling PalmOS API Functions

PalmOS provides you with a rich library of functions. You can call any PalmOS API function using a special message-send syntax. The receiver must be the word SYSTRAP and the selector is the name of the routine. For example, to get the height of the current font in pixels, you could write:

fontHeight := SYSTRAP FntCharHeight.

If an API function takes arguments, you write the SYSTRAP line as a keyword message-send. The first keyword is taken to be the function name and the other keywords can be anything you want. For example, to draw a line from the top-left corner of the screen to the bottom-right:

SYSTRAP WinDrawLine: 0 y: 0 x: 160 y: 160.

Note that the most common SYSTRAP calls are already encapsulated in appropriate methods in the standard Smalltalk class library, so you will only rarely have to deal with SYSTRAP calls directly.

CPointer

Since many PalmOS API functions return pointers or take pointers as arguments, there is a Smalltalk class called CPointer which is the equivalent of a C void pointer. Normally you do not need to know what a CPointer is pointing to, and you can simply pass instances around as "magic cookies". There are some methods in CPointer for dereferencing the pointer which are useful for reading and writing to C structures. You can also allocate and free PalmOS dynamic memory using methods in CPointer.

You must be careful to pass the correct types of arguments to PalmOS API functions. Arguments must either be Smalltalk Integers or CPointers. In particular, boolean arguments must be either 0 or 1, not true or false. If you pass incorrect argument types to an API function the receiver of the method that made the incorrect call is sent #badAPICall, which by default signals an error. You can see what parameters an API call expects by using the SYSTRAP Browser.

Some PalmOS API calls expect a pointer to a string, along with a separate length parameter. You can convert a Smalltalk String to a pointer to a C string by sending the String #copyToHeap. You must be sure to free the pointer after use by sending #free to the CPointer object. As a special feature, you can simply pass a byte-indexable object (such as a Smalltalk String) as the pointer to a string, instead of converting the String to a C-readable string. You still need to pass the length argument. This technique cannot be used with functions that expect 0-terminated strings, as Pocket Smalltalk Strings are not 0-terminated.

Next: Floating-Point Support

Palm Powered is a trademark of Palm Inc. Pocket Smalltalk is trademark of Pocket Smalltalk Group. Copyright (c) 1998 - 2001 Pocket Smalltalk Group.