Contents > Library Reference

Library Reference

Strings Functions for basic string manipulation.
Math Trigonometric and other mathematical functions.
Sound Functions for generating sounds.
System Functions for retrieving and manipulating system status, dynamic memory, dates, and the clipboard.
Database Objects for creating and manipulating databases and memos.
VFS Objects for accessing the virtual file system on expansion cards.
Networking Objects for IP networking.
Printing Printing support using PalmPrint.
Data structures General purpose objects such as a dictionary and a string list.
User Interface Objects and functions representing the application's user interface.
Type Strings How type strings work.
High Density Graphics How to use OS 5 high density graphics.

Contents > Library Reference > Type Strings

Type Strings

A type string is a way of describing the structure of data. Several API functions use type strings to control how data is read and written, such as Preferences.get. The easiest way to generate a type string is to use the typeof() operator, which generates a correct type string for any object/data type. However, sometimes it is necessary to create type strings by hand in order to interoperate with the data formats of other applications.

A type string consists of a list of characters representing primitive types, with optional modifier to specify repetition. The types are as follows:
SpecifierPrimitive Type
iint
w2-byte int
b1-byte int
cchar
ffloat
sstring
lfixed-length string
oobject type id
Note: When using a fixed-length string, the 'l' specifier must be followed with the length of the string followed by a dot '.'.

A specifier may be preceded by a number representing the number of repeated values of the type in a row.

For example:

struct X {
  int x, y;
  string name;
  float f[4];
};
The type string for X could be encoded as "iisffff" or "2is4f".

If name were required to be stored as a 32 character array:

struct X {
  int x, y;
  string name; // stored as a 32 character array
  float f[4];
};
The type string for X could be encoded as "iil32.ffff" or "2il32.4f".

The object type id is a location in memory at the start of an object that lets the runtime know what type of object is stored there. This value is skipped by the methods that take type strings (because writing out an object id is not possible). So, if the struct above was declared as an object:

object X {
  int x, y;
  string name;
  float f[4];
};
The type string for X could be encoded as "oiisffff" or "o2is4f".

Contents > Library Reference > High Density Graphics

High Density Graphics

Beginning with version 5, the Palm OS supports screen resolutions higher than 160 by 160. OrbC provides support for these higher resolutions as described below.

Coordinates versus Pixels

To maintain compatibility with older applications, the OS treats forms and controls based on a 160 by 160 "coordinates". The OS stretches them to fit the actual resolution of the device - on a 320 by 320 device, one coordinate represents a 2 by 2 block of pixels.

When creating forms and controls in OrbC, or when accessing their x,y,w,h properties at runtime, 160 by 160 coordinates are used. Also, when an older application draws to the screen, 160 by 160 coordinates are used and stretched by the OS to match the resolution of the device.

Bitmaps and Icons

The easiest way to make an app look better on high-density devices is to provide high-density versions of the app bitmaps and icons. To use these high-density images, no application changes are required - the OS will automatically display the high-density image on a supported device (older devices will use the standard image instead).

To define a high-density bitmap or icon, create an additional .bmp file that is exactly twice as wide and twice as tall as the standard image. Select the bitmap or icon in the IDE and add the new .bmp file in the property inspector.

Drawing

When using the Draw object, the parameters passed to e.g. line() are interpreted as 160 by 160 coordinates. This allows older applications (and applications that don't care about the high density screen) to work without modification.

To allow easy drawing on both high-density and standard devices (including pre OS 5 devices), OrbC supports drawing at "native" resolution. Native resolution will be 160 by 160 on older devices and may be higher (e.g. 320 by 320) on newer high density devices. To draw in native resolution, an application should call Draw.nbegin() rather than Draw.begin() and then use the graphics functions as usual. Once Draw.nbegin() has been called, the native width and height of the drawing surface can be retrieved using the Draw object's nw and nh properties. For example, a gadget may draw like this:

object MyGadget {
  UIGadget gadget;
  void onopen();
  void ondraw();
  Draw draw;
}
void MyGadget.onopen() {
  draw.attachGadget(gadget);
}
void MyGadget.ondraw() {
  // draw an X
  draw.nbegin();
  draw.line(clrFG, 0, 0, draw.nw, draw.nh);
  draw.line(clrFG, 0, draw.nh, draw.nw, 0);
  draw.end();
}

Pen Input

To determine the location of a pen event in native pixels rather than coordinates, two new properties have been added to the Event structure: nx (native x) and ny (native y).

Pre OS 5 Devices

Although other Palm OS based devices added high resolution support before OS 5 (such as the Sony Clie and Handera), the API was not standardized. All future versions of these devices will use the new standardized API. OrbC does not currently support the non-standard APIs.