Initially I developed this library to speed up and enhance the graphic capabilities of PocketC (www.orbworks.com) by providing functions for drawing resource bitmaps and for handling multiple screen buffers. Over time, the library has evolved to include an assortment of functions. Generally, these functions either expose more of the built-in Palm OS functionality, or they perform computationally complex tasks which would be much slower if written in PocketC.

I've come to see PocketC as a kind of "glue logic". It's not the fastest programming language for the Palm OS, but it's extremely easy to use. The beauty is that with native libraries, its possible to make very fast running functions for PocketC. In using such libraries, the role of PocketC shifts from doing all the heavy computation work, to just "gluing" the various fast native library functions together. PocketC's automatic type conversion facilities make it a particularly good glue language. Another, big plus in my mind is PocketC's support of pointers, this allows for the construction all kinds of useful data structures. The result is a rather speedy, easy to use, and powerful language. I also particularly like PocketC's ability to compile on a PC desktop or on a PDA itself (I find it quite handy being able to code on the road!).

Joseph Stadolnik

Click here to download Version 7.6.1: PToolboxLib.zip

The Pocket Toolbox web page: http://www.geocities.com/retro_01775/PToolboxLib.htm

Feature List

• Resource and dynamic forms (dialogs, 7 button types, fields, lists, labels, sliders, form bitmaps, scrollbars, & graffiti shift indicators)
• HanDBase® and Pilot-DB database interfaces.
• DateBook database access (includes alarm and repeating events support).
• Multi-buffered graphics
• Fast resource bitmaps (drawing & saving)
• 2 & 4 bit grayscale and 4, 8, & 16 bit color graphics. (PocketC built-in functions, bitmaps, and pixel drawing)
• Array sorting (alpha-numeric, natural, reverse, case-less, data structure, and 3 layer sort options) and searching capabilities
• OS5+ High Resolution support.
  
• String manipulation functions: Insert, Join, Replace, Split, Strip, Translate, and Trunc.
• A "note" function for multi-line text input and for editing/viewing database records (with a 32k field size limit)
• Fast record sorting (with alpha-numeric, natural, case-insensitive, and reverse sorting options)
• Fast record string searches
• Database record un/compression
  
• A text box drawing function with word wrapping and configurable alignment, font, color, and underline options.
• GetURL: A function for downloading content from the web (requires INet Library). Includes HTML tag stripping capability and header capture.
• Custom font importing & a font height function.
• A copy rectangle function with mode (OR,AND,XOR,etc), zooming, and rotate capabilities
• Saving and restoring the screen to and from databases
• Masked and transparent bitmaps (includes "sprite" management)
• Bitmap collision detection functions
• Triangle, ellipse, multi-line, and polar/Cartesian plotting functions
• Brush width control when drawing lines, frames, and ellipses.
• A floodfill function
• Custom fill patterns for rectangles, lines, ellipses, triangles, and floodfill.
• Scrolling graphics
• Get/set pixel functions
• A tone function with volume and blocking/non-blocking parameters.
• A multi-dimensional array and structure emulation function.
• Hardkey checking and downkey event disable functions
• Pseudo-random number generation (including a weighted random function)
• Intersection functions (do shapes A and B cross? Is this point in this polygon?)
• Full set of time/date selection and conversion functions.
• peek & poke functions for direct processor register access.
• Backlight control
• System and application preferences access
• Handera high-resolution, rotation, and graffiti area control.
• Sony high-resolution support for pre-OS5 devices (limited to bitmaps, forms, and text)
• PalmPrint® support for IR printing.
• Auto-Off timer controls
• Can get OS version, ticks per second, and battery information.
• Library can be embedded inside an application and has a plug-in scheme to reduce an embedded library's memory footprint.

I am making the iconized version of the Pocket Toolbox Library freely available to the general public. You may use it in a commercial product, but you may not sell the library.   You may freely include the library with your applications.  If you do use it in any publicly available commercial or freeware product, please give me (Joseph Stadolnik) due credit and please include a link to this web page AND the library version number in your documentation (http://www.geocities.com/retro_01775/PToolboxLib.htm ). The Pocket Toolbox Library comes with absolutely NO WARRANTY of any kind. As such, I cannot be held liable for any data loss or damage to a system resulting from the use of this library.

As for payment for my efforts for using the iconized library, I only request that you send me a complementary copy of any software that you publicly release which uses the Pocket Toolbox Library. My palm user name is "Joe Stadolnik" and my email address is jstadolnik@hotmail.com . Thanks!

Note: For a fee the library can also be embedded inside an application's .prc file, thus creating a complete stand-alone application.  Also, when the library is embedded, a developer may choose what features they want to include which usually reduces the library's memory footprint (the library is partitioned into different functional modules).  See the PRC Embedding section of this document for more details.

Installation

1. Install the PToolboxLib761.prc file on your PDA (just as you would any other PalmOS application).
   
2. If you are using the PocketC Desktop Editition (PDE) compiler copy the PToolboxLib.lib to the same directory as the pde.exe file.
3. If you are using the PocketC PDA-based compiler you may also want to copy the Fctl.h file to a memo and hotsync it.
   

Grayscale/Color Functions

int SetDepth(int depth)

Grayscale and color graphics is enabled through this function. The allowable depth values are as follows:

Be sure to call this function before any buffer related functions are called. Normally returns 1 on success and 0 on failure. If a failure occurs it means that the OS and/or hardware do not support the selected depth.

The higher the depth, the slower the graphics rendering. Thus, it is highly recommend that graphics intensive color applications take advantage of the 4 bit color mode, which is as fast as 4 bit grayscale mode. The SetPalette() function can be used to change the available 16 colors in 4 bit color mode.

The return value of mode "-1" indicates what depth modes available for a given device. If a depth mode is available, the bit corresponding to 2^(N-1), where N is the screen depth, will be set (e.g. A return value of 0x808b hex has bits 15, 7, 3, 1, and 0 set which indicates that depths 16, 8, 4, 2, & 1 are available). Note: 4 bit color requires a 4 bit depth (not a 5 bit depth).

Always call SetDepth before graph_on(). Always call graph_off before changing the depth (don't bother if graph_on has not been called yet). The one exception is when changing between modes 4 and 5, since they are both 4 bits deep no change in screen memory occurs. It is also a good idea to call FreeBuf(0) before a change of depth since any scratch buffers will then be the wrong size (don't bother if no scratch buffers have been opened, or when changing between depths 4 and 5)

For 16 bit graphics mode, the color palette is kept to 256 colors to keep heap memory usage down (a full 16 bit palette would use 262Kbytes of heap memory!). The palette will appear to be the same colors as in 8-bit mode, however the SetPalette() function can be used to change any of the colors to the various 65 thousand available.

Sets foreground color. Returns previous foreground color. Must be called after graph_on(). The permissible color ranges are as follows:

There is a useful color palette application available called McColors. This application can be used to determine the index number for a given color.

Sets background color. The color range is the same as the SetFore function. Must be called after graph_on(). When text and built-in bitmaps are drawn, this is the background color used. Returns previous background color.

Sets text color. The color range is the same as the SetFore function. This function only works in OS3.5 and up. For OS's less than 3.5, the foreground color is the text color. Must be called after graph_on(). Returns previous text color.

int PickColor()

This OS3.5+ function pops up a graphical palette interface for selecting colors and or grays. The value returned is the palette index of the color selected. This index can be used in the SetFore, SetBack, and SetTextColor functions. If the "exit" button is pressed, the return value will be -1. The current foreground color is initial selected color.

This function will work in all screen depth modes.

SetPalette(int index, int rgb_red, int rgb_green, int rgb_blue) //for color devices

For non-color devices: Sets 2 bit grayscale color palette. Acceptable values range from 0 to 7, where 0 is white and 6 & 7 are black, in between is gray. Gray0 is normally white, and Gray3 is normally black. Strangely, some hardware devices seem to have colors swapped around (e.g. the following format seems to work better on EZ processors: SetPalette(int gray0, int gray3, int gray1, int gray2)).

For color devices: Changes the color of the for the specified color index. The red, green, and blue RGB components each range from 0 to 255.

WARNING: Using this function with non-color roms on the POSE emulator causes "bus errors". However, on the real hardware no such error occurs. It's because a memory register is being written directly.

This function only works for OS3.0 and up. It also may not work on all hardware models (it definitely works on EZ processors).

Thanks to Astraware for the 2 bit gray adjustment source code.

The PToolbox library supports both resource forms and dynamic forms. Resource forms must be created beforehand using special tools and are either embedded in an applications .prc file or in a separate resource database. Dynamic forms differ in that they are created and populated with various objects by calling certain functions.

The library also provides a set of functions to easily manipulate the objects in both resource and dynamic forms. The FgetState, FsetState, FgetText, FsetText, FsetList, FresizeObj, and FmoveObj functions work on both resource and dynamic form objects. Most Fctl commands also work on both types of forms and objects.

Multiple forms are supported, as well as pop-up dialogs.

Caveats

There are a number of general rules and caveats for using working with resource and dynamic forms. Failure to follow these guidelines can result in undesirable program behavior (such emulator errors and system crashes).

1. Dynamic forms and objects are only available for OS3.0 and up. Resource forms work in all OS versions.
2. Always test your code on the POSE emulator with multiple debug ROMs (minimally OS3.1, 3.3, 3.5, and 4.0) (both can be obtained from http://www.palmos.com) In order to avoid POSE emulator warnings when running with pre-OS3.5 roms, uncheck the "UIMgr Data Access" box in the emulator "Settings->Debug Options" panel. Also, when running a ROM downloaded from a real device, uncheck the "Low Memory Access" box, there is a harmless emulator bug which causes warnings.
3. Each form and dialog must have its own UNIQUE identification (resource) number. Each object within a given form/dialog must also have its own UNIQUE identification number. It is possible for multiple forms to have objects with the same ID numbers, however the objects are not "shared" across forms and must still be installed in each form/dialog. ID numbers 0 through 255 are reserved by the PToolboxLib. ID numbers of 10000 and above are reserved by the palmOS. Forms and dialogs should have IDs of no less than 3000 so as not to interfere with reserved PocketC forms.
4. When using dynamic objects, be careful not to install an object with the same ID more than once per form. The results of doing so are unpredictable.
5. Be sure not to create (via the Form or Dialog functions) or load (via the Fctl LOAD command) more than one form/dialog with the same ID number, unless the first form is freed (Fctl(FREE,x)). Having more than one form/dialog with the same ID number active will cause serious instability problems.
6. The Form() function and the Fctl LOAD command (#10) will both internally call graph_on() if it has not been done so already. Do not call graph_on() after Form() or the LOAD command.
7. Be sure to set the color depth (via the SetDepth function) and any special screen resolution (via the Handera or Sony functions) before calling the first graph_on, Form(), or Fctl LOAD call. If these settings need to be changed first call graph_off before doing so (see also the next caveat about graph_off).
8. Calling graph_off() will delete all forms and dialogs.
9. Creating a dynamic form and installing objects does not draw them. Likewise loading a resource form does not draw it. Use the Fctl "DRAW" command (#0) to draw forms and dialogs. In the case of dynamic forms, only call the DRAW command once all the desired objects have been installed.
10. The Fevent() function must be used to capture button, list, and resource menu events. The Fevent() function will return the ID number of the button, list, or menu item selected. The built-in PocketC event functions (event, wait, waitp, getc, etc) will not capture form events correctly.
11. If you get a "Form.c, line XXX, object not in form" error, you are likely trying to use some PToolbox form function with an ID number which has no corresponding object installed for it. If this error is observed when tapping on a field, the most likely problem is that a repeat handler function has been setup (see the REPEAT Fctl command (#103) and that the handler function is calling on an object which is not in the current form. Either disable the repeat handler for that form or modify the handler function.
12. In pre-OS4.0 systems, if two forms objects overlap, the one installed first will always take precedence. In OS4.0+ systems, the object installed last will take precedence. The only way around this is to change the object installation order based on the OS version.
13. If the draw buffer is changed, always return it (see SetDrawBuf) to 0 (the display) before calling Fevent() when a form containing objects is active. Failure to do this will likely result in system errors.
14. Some built-in PocketC commands, notably the Basic I/O functions (puts, gets, setsd, getsi, setsm, alert, confirm, and clear), can "eat" button, list, and resource menu events.
15. There is no way to delete individual objects, it's a whole form/dialog or nothing. However you can "SHOW" or "HIDE" individual objects easily. See the respective Fctl() commands (#2 & #3).
16. There is a bug in the POSE emulator which effects the background restoration of forms and dialogs. When a form or dialog is exited, the emulator does not restore the background behind the form/dialog correctly. However, the background is correctly restored when running on real hardware.
17. It is possible to draw on forms/dialogs, however it is best to do this after the Fctl "DRAW" call to prevent the form objects from drawing over existing graphics. Anything drawn on a form will not be saved if the form is switched, except in the next forms save-behind memory. However, you can use scratch buffers to save and restore the screen in these cases (see the SetDrawBuf() and CopyBuf() functions for more details).
18. When calling the Fctl() "DRAW" command (#0), the state of the previous form is saved before the new one is drawn. In calling the Fctl() "FREE" command (#1), the current form is destroyed, and the saved background is restored… a potentially useful trick. Similarly, when the Fctl() "DRAW" command is used to change forms, the saved background is restored before the new form is drawn. To minimize the flashing effect of the restored background, use ClearBuf() to clear the screen before using Fctl "DRAW" to draw (non-dialog) forms.
19. The first form created cannot be a dialog. It should be at least 160 by 160 pixels in size.
20. At most one dialog should be shown at a time… in other words, a dialog should not be popped on top of another dialog, otherwise system errors will result when the dialog is exited.
21. Take care when using the FsetList() command. If the array of strings is shorter than the num_items parameter, the function will read off the end of the array and unpredictable behavior will result (usually fatal errors).
22. Stand-alone lists do not update correctly using the Fctl() "UPDATE" command (#8) in pre-OS3.5 systems. Use extra Fctl "SHOW" command (#3) to restore lists cleanly (though this may just be an emulator artifact?)
23. The Fctl "SHOW" command (#3) will not effect stand-alone lists when the Id = -1 ("show all") mode is invoked. Stand-alone list must be "shown" separately (i.e. first "show all", and then show each stand-alone list).
24. Calling the Fctl() "POPLIST" command (#200), alert(), confirm(), or any other built-in PocketC dialog will flush the undo memory (as triggered by the Fctl() "UNDO" command (#308)). This is a PalmOS "feature".
25. The Palm OS does not support dynamic menus, tables, or scrollbars, as such they are not supported by the PToolboxLib. Tables in resource forms are also not supported.
26. The standard dropdown PocketC menu with the stop option is not available for PToolbox created forms.
27. All Forms, dialogs, and form objects, whether they be resource or dynamic in origin, consume dynamic heap memory. If your application runs out of heap space the PDA may crash. The Form(), Dialog(), Button(), Field(), List(), and GSI() functions will all return 0 if they fail to allocate the necessary heap space. Similarly, the Fctl LOAD command (#10) will return 0 if the form failed to load. Destroy unneeded forms with the Fctl() "FREE" command (#1) to free memory in the heap. Also, the HeapSize() function can be used to determine the amount of available heap memory.
28. The color settings, as set with SetFore(), SetBack(), and SetTextColor(), get reset when switching to a different form (via Fctl(DRAW,id);).
29. Don't call the alert() function when a less then full screen size dialog is active.
    

Resource forms must be created with 3^rd party tools, notably PilRC (freeware) for the desktop creation of resources, and RsrcEdit ($15) for onboard PDA resource creation.

PilRC (desktop)

Here is an outline of how to use PilRC to generate resource forms.

1. The developer creates a .rcp file (with a text editor) describing what forms to create and how they should be populated. Each form and object is assigned a resource ID in the .rcp file. See the PilRC manual for information about writing .rcp files. There are also a number of desktop GUI editors, which can generate and/or edit .rcp files: PiBuilder (free), PilrcEdit (free, requires java), and PilotMag($20).
2. The developer runs PilRC on a dos/shell command line passing in the .rcp file as an argument (e.g. PilRC rcp_file_name.rcp)
3. PilRC generates one or more .bin (binary) files. These are the resources. The first four characters of the .bin file name indicate what type of resource it is (form=tFRM, menu=MBAR, string=tSTR, alert=Talt, bitmap=Tbmp, see PilRC manual for others). The next four digits of a binary files is the resource ID in hexadecimal.
4. The .bin resource files should be now embedded within either your application's .prc file or into a resource database (see the OpenRsrcDb function for more details). Use the par utility to do the embedding: "par a app_name.prc *.bin" OR "par a resource_db_name.prc *.bin". Instead of wild carding all binary files with *.bin you can also list out one or more binary files explicitly, for example "par a app_name.prc tFRM0BB8.bin MBAR0BB9.bin".
5. In your PocketC code, use the Fctl LOAD command (#10) to load a form. If the form is not the application .prc file, you must first use the OpenRsrcDb() function to open the .prc containing the form before calling the LOAD command. Use the Fctl DRAW command (#0) to draw the form. See the code sample below.

RsrcEdit (PDA)

Here is an outline of how to use RsrcEdit to generate resource forms.

1. Create an empty resource database. Open RsrcEdit. From the menu create a new database. The type should be "data". Make sure the resource database checkbox is selected.
2. Open the database. Select the new database from the selection list and push the "open" button.
3. From the menu selected "New" and then "Form". For a standard form use the following options: top=0, left=0, width=160, height=160, Frame type=no frame, modal=no (yes for dialogs), usable=yes, save behind=yes, Def Btn=0, Mbar ID=id of resource menu to use (0 if none), Help ID=id of string resource (tSTR) to use (0 if none). Add objects form the pulldown menu as needed. When done, hit ok and give the form a new ID number (of 3000 or more). This is the ID number used to load and draw the form from PocketC. See the RsrcEdit documentation for more details on creating forms and form objects with this tool.
4. Use the "PREVIEW" button in RsrcEdit to see what a created form will look like and how it will behave. The preview button is available on the form and alert resource windows.
5. Use the "ADJUST" button in RsrcEdit to move the form object around manually. Select an object with the pen and move it with the hardkeys.
6. Create Menu resources, string resources (for Help icons), and bitmaps (for form bitmaps and graphical buttons) from the main resource menu.
7. In your PocketC code, first use the OpenRsrcDb() function to open the .prc containing the form. Then use the Fctl LOAD command (#10) to load a form. Use the Fctl DRAW command (#0) to draw the form. See the code sample below.
8. When the application is completed use the par utility to embed the resource database into the application's .prc file, example: "par a app_name.prc rsrc_db_name.prc".

The supported resource types are: forms, menus, alerts (see the Fctl POPALERT command), strings (for help icons, also see the Fctl GETTSTR command), bitmaps (for form bitmaps and graphical buttons), and string tables (see the Fctl STBLSIZE, STBLPFX, & STBLGET commands). Table objects are not supported.

Re-Use

Most palm development platforms support resource forms. This means that should you ever upgrade a PocketC application to another platform (for better speed and program size) such as gcc or Codewarrior, you can use the same resource forms.

Use Prc2Pilrc (free, requires java) to translate the resources in a .prc into a .rcp file.

Also, resources can be extracted from a .prc with the par utility, and then embedded in another application. Extraction example: "par x app_name.prc". Embedding example: : "par a app_name.prc tFRM0BB8.bin MBAR0BB9.bin".

Tips

• Be sure that the minimum form ID is 3000 and the minimum menu ID is 2000 so as not to clash with the PocketC's own forms and menus.
• In Palm lingo "buttons" and "controls" are the same thing. A "graphic control" is a "graphic button".
• Graphic Buttons (controls) and sliders only work on OS3.5 and up.
• For resource forms, each popup-trigger button needs to be bound to a list with a special popup (POPUPLIST) resource, so three resources in all are needed: a POPUPTRIGGER, a LIST, and a POPUPLIST. See the sample .rcp file below for an example of this. A list without a corresponding POPUPLIST resource is a stand-alone list.
• A dialog is a form with the "modal" bit set and having a frame. If using PilRC, create a FORM and use the MODAL and FRAME keywords to turn in into a dialog.
• Help information can be bound to resource forms internally or to dynamic forms with the Fctl HELPID command. The help ID should refer to a string resource containing a help information text. See the sample .rcp file below for an example of this. The help icon will only display correctly on dialogs (forms with the "modal" bit set). See the Fctl HELPID command (#115) for some additional tips on using help icons (though you don't need to call the HELPID Fctl command if the resource form has a help ID set internally!). If using RsrcEdit, you can disable the help icon by setting the help id to zero.
• Dynamic form objects can be installed in resource forms. See the Button, GButton, Field, List, Label, Slider, FormBmp, and GSI functions.
• If using RsrcEdit, setting the menu id to zero will disable the menu. Also, setting the help id to zero will disable the help icon.
• Multi-line Labels can be created by using "\r" characters in the label text string (note: "\n" doesn't work).
  

The following dynamic objects can be installed in dynamic forms and dialogs: standard buttons, pushbuttons (radio and stand-alone), checkboxes (radio and stand-alone), select boxes, pop-triggers, repeat buttons, stand-alone lists, drop-down lists, in-place text edit fields, labels, graffiti shift indicators, bitmaps, graphical buttons, and slider controls.

A tool called Cconvert has been developed by Chris Cason which can translate CEditor (Ccontrols editor) databases into PToolbox dynamic forms. This tool makes it possible to graphically design PToolbox forms.

There are three methods of handling menus with the PToolboxLib form functions:

Menu Method 1: Create the menu with dynamic form objects. A simple menu can be emulated with dropdown list installed in the upper left corner. Pop the list using the Fctl() "POPLIST" command (#200) when a menu event is received with Fevent().

More complex menus can be constructed with pushbuttons and stand-alone lists. These objects should be hidden after installation before the Fctl() "DRAW" call is made. When a menu event is trapped with Fevent(), unhide the appropriate pushbutton and lists objects. Check for events from the objects to control further behavior. When done handling the menu, hide the buttons and lists again and use the Fctl() "UPDATE" command (#8) to re-draw all the form objects.

Menu Method 2: Resource Menus. First a resource menu must be created and embedded within a .prc file. This can be done on a desktop using PilRC (to create it) and par (to embed it)(see the menu.rcp example), or use the onboard PDA toolRsrcEdit ($15). If the later method is chosen, the menu resource must created either in the application's .prc file or in a separate resource database (see the OpenRsrcDb() function for more details). Be sure to use a menu resource ID of at least 2000 to prevent clashing with PocketC's own menu resources. After Form() is called use the Fctl() SETMENU command #104 to activate the menu. Each selectable menu item much have its own unique object ID. Upon selection, the Fevent() function will return the menu item ID number. Graffiti shortcuts assigned to these menu items will also trigger events returning the ID number of their respective menu item

Menu Method 3: Ccontrols Menus. The Ccontrols package by Mario Schlesinger can be used to handle menus. The process is outlined below. The trick is to disable the form while the Ccontrols menu handling is active, otherwise selecting menu events can trigger the dynamic form objects.

1. First trap the menu event with Fevent().
2. Save the screen with saveg().
3. Use the Fctl() "HOOKFORM" command (#110) to disable the form objects.
4. Handle the menu as you would normally with Ccontrols, except use Fevent() rather than event().
5. When done, restore the screen with restoreg(), then use "HOOKFORM" to re-enable the form objects
6. Execute the menu command.
   

Event handlers are special user defined functions which are allow users to access a number of advanced form event capabilities. The Fctl EHAND (#123) command is used to enable event handler functions. Only one event handler function can be active at any given time, and that function effects all forms. The capabilies provided by event handlers are as follows:

• Repeat event trapping from repeat buttons and slider controls.
• Field enter event trapping.
• Field change event trapping.
• Scrollbar exit event trapping.
• Scrollbar move event trapping.
• Mapping of scrollbars to fields (and fields to scrollbars).
• Command Bar open event trapping (allows users to add command bar icons via AddCmdBar).

Portable Keyboard Support

The Ptoolbox library provides portable keyboard support through the following mechanisms: 1) inter-field navigation via tabs (see the Fctl HOOKTAB command (#111)) and the up/down arrows keys (see the Fctl HOOKARROWS command (#113), and 2) carriage return completion (see the Fctl HOOKLF command (#112)).

int Fevent(int time)

Fevent() is similiar the built-in PocketC event() function with some additional features. Notably, the calculator and find silk button events can be trapped, as well as title bar pen-down events. If a form button is pushed, the ID of that button gets returned by this function (thus it is imperative that each form object has its own unique ID). Selecting an item within a stand-alone listbox will cause Fevent() to return the ID of that listbox. If a drop-down menu item (from a menu resource - see Fctl command #104) is selected, the ID of that item will be returned. If the a menu item has a Graffiti shortcut associated with it, entering the shortcut will cause Fevent() to return the ID of that menu item.

With a time value of 1, Fevent() will wait indefinitely for a user input event, otherwise Fevent will wait the specified amount of time before returning control back to PocketC. If the time value is zero, no wait will occur.

WARNING: On the first Fevent() call, PocketC's normal background event checking mechanism is disabled. This causes PocketC to run about 5% faster, but also prevents the user from exiting or even turning off their PDA if the app should get into an infinite loop which does not call the Fevent() or event() functions. If such a lock-up state is encountered, the only recourse is to perform a soft reset (which always works). An example of such a lock-up loop is: "while(1);". To avoid a lock-up problem simply code as follows: "while(1) Fevent(0);".

Repeat button events are not handled through Fevent(), instead they are trapped through a special repeat handler function (see the Fctl() command #103 "REPEAT").

When running in pre-OS3.5 systems, tapping the title bar will trigger a menu event (just as in OS3.5+). Title bar events can also be trapped by Fevent() by enabling "HOOKTITLE" mode (see Fctl() command #107)

int/string Fctl(int command, int Id)

"Form Control". This is a multi-use function used to control many aspects of forms and dialogs.

The available command are shown in the table below:

NOTE: The define macros can be found in the Fctl.h include file.

Returns either the current state of a button or the current selection for a list. If the Id value ranges from 1 to 255, the value will be treated as a button group number, and the ID of the selected button in the group will be returned. Otherwise, the Id should contain the ID number of the list or button to query.

This function can be used to change the state of a button or the selection item on a list. The Id parameter determines the button or list to modify.

For buttons, setting the state parameter to 1 will assert the button, 0 will de-assert the button. If a button is grouped with others, be sure to call FgetState first to determine if any button in the group is already selected. If a button is already selected, unselect it with FsetState(id,0). Failure to do this can result in more than one button in a group being selected.

For lists, the state parameter specifies what list item to select. A value of -1 will cause no items to be selected, a 0 will cause the first item to be selected, a 1 the second item, and so on.

With this function, the contents of a field, the text of the current selected item of a list, the text of a button, the text of a label, or the title text of a form can be returned. The Id parameter should contain the ID of the object to query.  Use an Id of zero to obtain the current form's title string.

With this function, the text in a field, button, or label can be changed. If the Id parameter specifies the ID of a field, the field contents are replaced by the text parameter.  Also, the title text of a form can be changed with this function.

If the Id parameter specifies the ID of a button, the button's texts is replaced by the text parameter. If the button is a select box, the frame of the button will be re-sized to accommodate the new text. By default, the other button types do not auto-resize when FsetText is called. Use the Fctl() AUTOSIZE command (#400) to enable or disable auto-resizing for the other button types.

If the Id parameter specifies the ID of a label, the label's text is replaced by the text parameter.  The length of the new text is truncated if it has more characters than the old label text.

To change the text of the current form's title, use an Id of zero.  For example: FsetText(0,"New Title");

Moves the form object specified by Id to location (x, y).

Resizes the form object specified by Id.

If a list object is resized to have a height which is not aligned with to a text row boundary, strange ghosting effects will occur in the misaligned gap. For example, suppose the font for a list has a height of 14 pixels and the list has 3 rows (for a hieght of 42 pixels). Resizing the list height to 49 will result in 7 pixels of height being unused. This 7 pixel gap will be subject to bizarre ghosting effects.

int Form(int Id, string title)

Creates a screen sized dynamic form with the specified title.

Each form, dialog, and form object MUST have its own unique ID number. Duplicates will result in system error and/or unpredictable behavior will result. The minimum form ID number is 3000.

Creating a form does not make it draw. After a form is created, form objects should be installed into it via the Button, List, Field, Label, and GSI commands. Once all the desired objects are installed, the Fctl() "DRAW" command (#0) should be used to draw the form and all its objects.

Multiple forms can be created simply by calling Form() multiple times (e.g. call Form(),install objects, call Form(), install objects, etc.). Use the Fctl() "DRAW" command (#0) to switch between forms.

Unneeded forms can be removed with the Fctl() "FREE" command (#1).

Form() will internally call graph_on() if it has not been done so already. As such, do not call graph_on() after Form() since it will have already been called.

This function will return 0 upon failure to create the form, and 1 if successful.

By default, forms do not have a menu associated with them. See the Fctl SETMENU (#104) command for more details.

int Dialog(int Id, int x, int y, int width, int height, string title)

Creates a dynamic dialog form with the specified title. The upper-left hand corner of the dialog will be at location (x,y).

All objects installed in the dialog are positioned relative to the upper left hand corner of the dialog, NOT the screen!

Each form, dialog, and form object MUST have its own unique ID number. Duplicate ID numbers will result in system error and/or unpredictable behavior will result. The minimum form ID number is 3000.

The PocketC graphics window must be activated with the graph_on() command before the first form/dialog is created.

Creating a dialog form does not make it draw. After a dialog is created, form objects should be installed into it via the Button, List, Field, Label, and GSI commands. Once all the desired objects are installed, the Fctl() "DRAW" command (#0) should be used to draw the dialog and all its objects.

Multiple forms and dialogs can be created simply by calling Form() and/or Dialog() multiple times (e.g. call Form(),install objects, call Dialog(), install objects, etc.). Use the Fctl() "DRAW" command to switch between forms/dialogs.

The background graphics behind dialogs is saved when the Fctl() "DRAW" command (#0) is issued. The background is restored when either the dialog is deleted with the Fctl() "FREE" command or when the active form is changed via the Fctl() "DRAW" command (#0). There is POSE emulator bug which can cause the background to not be restored properly, the problem does not appear on real hardware.

Dialogs are a type of form. Any Fctl() command which works on forms will also work on dialogs.

This function will return 0 upon failure to create the dialog, and 1 if successful.

This function will install a dynamic button in the current active form at position (x,y) with the label specified in the text parameter. If the width field is set to 0, the button width will be automatically resized to fit the text. If the height field is set to 0, the button height will be automatically resized to fit the text. WARNING: Button auto-sizing doesn't work the same for pre-OS3.5 systems, as it does for OS3.5+ systems.

Each form, dialog, and form object MUST have its own unique ID number. Duplicate ID numbers will result in system error and/or unpredictable behavior will result. The minimum button ID number is 256.

There are 6 button types as specified by the mode field.

Pop-trigger buttons need to be bound to a list (see the List() call). When selected, the list will pop-ip. If an item in the list is tapped, the label of the pop-trigger button will be updated.

Select box buttons are surrounded by a dotted frame. If the text of the button is changed with the SetButton() function, the frame will be resized. The alignment of the resize can be specified with bit 16 of the mode parameter.

Repeat button events are not handled through the Fevent() call. Instead, repeat button events are handled through a special user defined function. The function is bound with the Fctl() "REPEAT" command #103. See this Fctl() command for more details.

Push buttons and checkboxes can be made to behave in a "radio button" fashion. This is accomplished by giving a set of buttons the same group number (mode bits 15:8). If the group number is zero, the buttons will not be grouped.

The font of the button label can be set by calling textattr() with the desired font (including custom fonts. See OpenFontDb) before installation.

This function will return 0 upon failure to install the button, and the rightmost "x position" of the button if successful. This "x position" return value feature is useful for laying out adjacent pushbuttons. Simply use the return value as the X-position of the next pushbutton. Alternatively, if a BINDX variable is set (see Fctl command #100), the variable will be set to the rightmost button boundary value. If the BINDY variable is set (see Fctl command #101), the variable will be set to the bottom button boundary value.

Also, if the Fctl BINDX and/or BINDY commands have been used to setup position variables, these variables will be updated when a pen event occurs within a button boundary. This can be used to determine where in a button the pen tap occurred.

Installs a dynamic, in-place edit text field at position (x,y) with the specified width and height. The maximum number of characters in the field is specified by the max_chars parameter. The field will be preloaded with the contents of the text parameter.

Each form, dialog, and form object MUST have its own unique ID number. Duplicate ID numbers will result in system error and/or unpredictable behavior will result. The minimum button ID number is 256.

The initial font of the field can be set by calling textattr() with the desired font (including custom fonts. See OpenFontDb) before installation. The font can also be changed on the fly with the Fctl() "SETFONT" command #303.

If the height parameter is set to zero, the field height will be automatically set the current font height (the field will be a single text line high).

The last field installed will have the focus (cursor).

The mode definition is as follows:

This function will return 0 upon failure to install the field, and 1 if successful.

If a BINDX variable is set (see Fctl command #100), the variable will be set to the rightmost field boundary value. If the BINDY variable is set (see Fctl command #101), the variable will be set to the bottom field boundary value.

Int GButton(int Id, int mode, int x, int y, int width, int height, int bmpId, int selectedBmpId)

Installs a dynamic graphical button in the current form with the specified Id. Graphical buttons are similar to regular buttons except that they have bitmaps instead of text. Two bitmaps need to be provided, one for the "normal" state and one for the "selected" state. The bitmaps must be specified by resource ID and must be located in the application's .prc file, in a bitmap resource database (see the OpenBmpDb() function), or in a separate resource database (see the OpenRsrcDb() function for more details on this).

Graphical buttons are only available in OS3.5 and beyond. They can be easily faked out in earlier OS versions by drawing a FormBmp() object on top of a Button() object which has no text.

The mode format is identical to that of the Button() function with the one exception being that checkbox graphical buttons are not supported.

The function returns a 1 upon successful installation and 0 upon failure.

Installs a dynamic list at position (x,y) with the specified width. The max_items field determines the maximum number of items to show. If a list has more items than the max_items parameter value, scroll arrows will appear in the list.

Set the trigger value to 0 to create a stand-alone list. Set the trigger value to a pop-trigger button Id to create a pop-triggered list. Set the trigger_Id to an used ID (such as 9999) to create a dropdown list (use the Fctl() "POPLIST" command #200 to pop the dropdown list).

The minimum Id value is 256.

The font of the button label can be set by calling textattr() with the desired font (including custom fonts. See OpenFontDb) before installation.

Use FsetList() to define item values for a list object.

If a BINDX variable is set (see Fctl command #100), the variable will be set to the rightmost list boundary value. If the BINDY variable is set (see Fctl command #101), the variable will be set to the bottom list boundary value.

int FormBmp(int Id, int x, int y)

Installs a dynamic bitmap object in the current form at position (x,y). The Id parameter specifies the resource ID of a bitmap located in the application's .prc, in a bitmap resource database (see the OpenBmpDb() function), or in a separate resource database (see the OpenRsrcDb() for more details on this). The resource Id is also the ID which should be used for hiding and showing the bitmap (see the Fctl SHOW and HIDE commands), and for moving it with the FmoveObj() function.

The function returns a 1 on success and a 0 upon failure.

FaddList(int Id, int num_items, pointer array)

This function appends the contents of an array to a list form object. The Id is the ID of the list object. The num_items parameter determines the number of items to add. The array parameter is the pointer to a list of strings.

Use the FdelList() command with index=-1 to clear out the list of all items. Use the FrevList() command to sort and/or draw a list when complete.

See the list_demo.c file for an example using this function.

To add a single element to a list use the following function: FaddItem(int Id, string item) { FaddList(Id,1,&item); }

FdelList(int Id, int index)

This function deletes either one or all items from a list form object. The Id is the ID of the list object. The index is the list element to delete (e.g. the first element is 0, the second 1, third 2, etc). If an index of -1 is specified, all items in the list are deleted.

Calling this function does not redraw the list. Call the FrevList() to redraw the list.

See the list_demo.c file for an example using this function.

FgetList(int Id, pointer stringArray);
Copies the contents of the list with the specified Id to an array of strings pointed to by stringArray.  The string array must be large enough to contain all the list elements.  Use the Fctl LISTLEN command (#207) to determine the number of elements in the list if uncertain of its size.

FrevList(int Id, int mode)

"Revise List". This function will redraw the a list object if the form it is within is visible. Optionally, the forwared and reverse sort options are available. The The Id is the ID of the list object.

FsetList(int Id, int selection, int num_items, pointer string_array)

Assigns item data to the list specified by Id. The string_array should point to an array of strings. Each element in the array will be a item in the list. The num_items field determines the number of items in the array. The selection parameter specifies the initial selected item. If the selection is -1, no item will be initially selected.

Also, setting the selection field to -2 will prevent the current selection from being changed.

Note: The function is now somewhat depreciated. See the newer FaddList(), FdelList(), and FrevList() functions. The FsetState() function can also be used to set the selection.

int GSI(int x, int y)

Installs a dynamic Graffiti Shift Indicator at the (x,y) position. The function only works for OS3.5+. For earlier OS versions the function simply exits.

Installs a dynamic text label of the given Id at position (x,y).

The minimum Id value is 256.

The font of the label can be set by calling textattr() with the desired font (including custom fonts. See OpenFontDb) before installation.

Tip: Multi-line labels can be created by using "\r" characters in the text string (note: "\n" doesn't work).  Example: Label(3001, 80,80,"Line1\rLine2\rLine3");

int OpenRsrcDb(string dbName)

Opens a resource database so that various form functions can access the resources within. If no such database exists, it will be created and opened. If the database is created it will be of type "data" and will have a creator ID of "PktC". The database will also have its backup bit set.

This function is handy during the development phase when working with resource forms, menus, strings (for dialog help icons), bitmaps (for FormBmp() and Gbutton()), and alerts (see the Fctl POPALERT command (#117)). These resources can be created with a desktop tool such as PilRC (and placed within the .prc with par), or created on the PDA itself with RsrcEdit. See the "Resource Forms" sub-section in the "Form Function" section of this document for more details.

Once a project is complete, the resource database can be embedded in the final application .prc with par (e.g. "par a app.prc resource.prc"). After being embedded, the resource database is not needed by the application. Note: If you create an application .prc file with the BuildPRC tool from Orbworks, your application will need to do an OpenRsrcDb() on itself in order to access any resources you embed within it. For example, if your application name is myapp.prc, it will need to internally do a OpenRsrcDb("myapp").

The function returns 0 upon failure, 1 if the database was opened, and 2 if the database was created.

int Slider(int Id, int style, int x, int y, int width, int height, int min, int max, int page, int initial)

This function installs a dynamic horizontal slider object in the current form. This object type is only available for OS 3.5 and higher. There are two slider styles: 0=normal slider, 1=feedback slider. A feedback slider differs from a normal slider in that it will send repeat events if the pen is dragged across the slider. Use the Fctl REPEAT command (#103) to set up a repeat handler function when using feedback sliders.

The min and max parameters define the value boundaries of the slider. The page parameter determines how much to move the slider when the user clicks to the right or left of the thumb. The initial parameter set the initial value of the slider. Use the FgetState() and FsetState() functions to change the state of the slider programmatically.

Use the Fctl SCROLLMODE command in conjunction with the FsetState() function to change the position, minimum, maximum, and page size values.

int CmdBarAdd(int object_id, int position, int bitmap_id, string text)

When called from within an event handler function (see the EHAND Fctl command #123) in response to a command bar open event, this function can be used to add custom icons to the command bar. The object_id indicates the id that Fevent() will return if the icon is selected. (See also the Event Handler Functions section.) The position parameter determines where to place the new icon with respect to the other (0=left, 1=right). Note: The standard field icons will always appear on the right. The bitmap_id refers the resource id of the bitmap to use for the icon. The bitmap must have a width of 16 pixels and a hieght of 13 pixels. The bitmap can be placed in a a bitmap database (see OpenBmpDb), a resource database (see OpenRsrcDb), or in an application .prc file itself. The text field determines what text to display if the icon is selected. If text is left null (i.e. "") and the object_id matches an item in the pulldown menu, the text for the pulldown menu item is used.

This function returns a 0 upon failure and a 1 upon success.

If the event handler function should return -1, the command bar will not be displayed. If a 1 is returned, any field related icons will be supressed. Return a 0 to keep any field icons in the command bar.

This function is only works for OS3.5 and greater and will do nothing in earlier OS versions.

FsetMany(int starting_id, int step_size, int block_size, int offset, int num_blocks, pointer array)

This function rapidly loads the contents of an array of data structures into a set of fields and/or buttons. This is useful for loading tables (matrices) of fields and/or buttons quickly.

The starting_id parameter contains the id of field or button to start with. The step_size parameter determines the amount to increment the starting_id on consecutive object writes (e.g. if the starting_id is 4000 and the step_size is 10, the following objects will be updated: 4000, 4010, 4020, 4030, etc). The block_size determines the size of blocks (elements per data structure) in the data array (e.g. a simple array has a block_size of 1). The offset parameter determines where to look in each each block for the data (e.g. if offset is 1, the second element in the block is used). For simple arrays, an offset of 0 should be used. The num_blocks parameter determines the number of form objects to load (it's also the number of blocks in the array used). The array parameter points to an array of blocks. For fields, values of any type can be used (int, float, string, or char), for standard, pop trigger, and selectbox buttons a string must be used, and for all other types of buttons integer or string types can be used. Type conversion automatically occurs as neccessary.

In cases where no data structure emulation is occuring, the block_size should be 1, the offset should be set to 0, and num_block should be the size of the array.

See also the Sort() and Query() functions for examples using this block_size,offset, and num_blocks concept.

See also the FgetMany() function.

FgetMany(int starting_id, int step_size, int block_size, int offset, int num_blocks, pointer array)

This function rapidly stores the contents of a set of fields and/or buttons to an array of data structures. This is useful for reading tables (matrices) of fields and/or buttons quickly.

The parameter list is identical to the FsetMany() function.

This function controls the color settings for the various form objects. It only works for OS3.5. For earlier OS versions the function simply exits.

The style parameter determines the what type of color change.

Database Functions

This family of functions allows the PocketC to interface directly with two 3^rd party database formats: HanDBase® (commercial) and Pilot-DB (freeware). The advantage of using these database formats is that they both have desktop tools for accessing the contents of these databases. Both also have powerful PDA based support applications for sorting, filtering, searching, and beaming their respective databases.

The PToolboxLib provides unified data access to HanDBase® and Pilot-DB databases, in other words the same functions and data types are used for both database formats. This allows applications to seamless switch between the two types.

HanDBase® (a product of DDH Software) is a Palm® and PocketPC® database industry leader. It has a powerful desktop companion for data entry and viewing. The desktop tool also has a number of add-on features, notably a conduit (for PDA-desktop data synchronization), a MS-Access® interface, and a ODBC interface. Another advantage of the HanDBase® standard is that it supports Palm® and PocketPC® cross-compatibility. I highly recommend the HanDBase® Plus product, it includes the desktop companion and the conduit.

Pilot-DB is the freeware Palm® database standard. It supports a variety of fields (though not as many as HanDBase®). There are a set of tools for converting Pilot-DB databases to and from CSV (comma-separated-value) text files. See the DB-Tools area (see link off main Pilot-DB web page). There is also a free MS-Access conduit available (see the "links" section off the main Pilot-DB web page).

int DBcreate(string dbname, int type, int numFields, pointer fieldArray)

Creates and opens a database of the given name. If the type parameter, 0=HanDBase® and 1=Pilot-DB. The numFields parameter specified the number of fields per record. HanDBase® databases have a maximum number of 30 fields per record, while there is not field limit on Pilot-DB databases. The fieldArray pointer should point to the first item of an array which has two elements per field (e.g. for a 30 field database, the array size must be 60)(e.g. the pointer will generally look like: &array[0][0]). Furthermore, each array element pair must consist of first an integer (for the field code) and second a string (for the field name). For example, to allocate memory for an array to handle 20 elements do a: ptr = malloct(20,"is"), or alternatively: ptr = Array("is,20,2");. See the database_demo.c file for a complete code example.

The available database field types are listed in the table below. Provided that one limits oneself to using the: string, integer, float, date, time, boolean, and note fields, the data records can be written seamlessly as either HanDBase® or Pilot-DB records (since they both have these field types).

For HanDBase® databases DBcreate() returns -1 if HanDBase® PDA application not available, 0 for success, and 1 or higher for failure. For Pilot-DB databases, DBcreate() returns 0 on success and 1 upon failure.

Returns information about the currently opened database.

Returns -1 if no database is currently open.

This function opens the specified Handbase® or Pilot-DB database. If another such database is already open, it is closed before the new one is opened.

Returns 0 upon success, and 1 upon failure.

int DBsetrec(int recordNum, pointer arrayPtr)

Loads the record specified by recordNum with the contents of arrayPtr. The array must consist entirely of strings. The length of the string should be at least equal to the number of fields per record in the database (the DBinfo() function can be used to get the number of fields). The first record is at postition 0.

If the recordNum parameter is set to -1, a new record is created and appended to the database.

For HanDBase® databases returns -1 if HanDBase® PDA application not available, 0 for success, and 1 or higher for failure. For Pilot-DB databases, returns 0 on success and 1 upon failure.

Reads the record specified by recordNum and writes the contents to the array pointed to by arrayPtr. The array must consist entirely of strings and have at least as many elements as the there are fields in the database. The first record is at postition 0.

For HanDBase® databases returns -1 if HanDBase® PDA application not available, 0 for success, and 1 or higher for failure. For Pilot-DB databases, returns 0 on success and 1 upon failure.

string DBgetfield(int record, int field)

Returns the contents of the field of the specified record. Returns "" upon failure.

Deletes the specified record. If the recordNum parameter is set to -1, the database is deleted.

Returns 0 on success and 1 on failure.

int DBmoverec(int fromRecord, int toRecord)

Inserts the "from" record at the "to" record position.

This "to" value may be one greater than the index of the last record in the database. In cases where "to" is greater than "from", the new index of the record becomes "to"-1 after the move is complete.

Returns 0 on success and 1 on failure.

Bitmap Functions

Bitmap resource databases can be created with various tools:

First, I highly recommend artBMP, a free, palm based bitmap editor created by Dian Suharto Iskandar. It can be found here: Artosoft.

Other notable products are : MADPaint (freeware) by MAD Ant Design and RsrcEdit ($15) from Quartus. MADPaint is similiar to artBMP, and offers some interesting features. RsrcEdit allows one to draw bitmaps on a PDA or emulator (though it's not quite as powerful as artBMP or MADPaint).

Advanced users can use PilRC (freeware) to compile bitmaps into raw binaries and a tool like par (freeware) to put these binaries into a .prc file. With these two tools users can put many bitmaps into a .prc file at once (e.g. par a applet.prc *.bin).

Empty resource database files can be created with the OpenBmpDb() function. The empty database can then be populated with bitmaps using the SaveBmp() function.

It is possible to merge a bitmap database into a program's .prc file, thus eliminating the separate bitmap database. Use par in append mode to do this (e.g. "par a applet.prc bitmap.prc"), and use your applet name (as specified with #dbname) in the OpenBmpDb call (though leave out the .prc extension).

int OpenBmpDb(string database)

Opens a database by the given name. Only one such database can be open at a time. Calling this function again will close the current database before opening the new one. When the application exits the database is closed automatically. This function will return a 0 on failure to open/create the specified database, and 1 upon success.

The bitmap database can either be a .prc or a .pdb file.

If the database does not exist, a new one is created with the given name. The new database will be of type "data". If the application is a stand-alone type, the creator ID of the database will be the same as the application, otherwise the creator ID will be 'PktC'. The backup bit will also be automatically set for this new database. Thus, this function can be used to create empty resource database (.prc) files for inserting bitmaps into.

There are two modes in which a bitmap database can be opened: "load&lock" mode (the default), and "load-on-demand" mode. In "load&lock" mode, all the bitmaps in the database are immediately loaded into memory and locked down. This process can take some time, especially if there are many bitmaps in the database. The benefit is that the bitmaps draw very quickly. In "load-on-demand" mode, a bitmap is loaded and locked only when it is drawn. After being drawn the bitmap image is immediately unlocked and freed. Bitmaps in "load-on-demand" mode draw slower than those under "load&lock" mode, however there is no up-front database load delay. "Load-on-demand" mode is also more suitable in cases where there are many, very large bitmaps. To open a database in "load-on-demand" mode, simply prefix the database name with a "#" character. For example, if a database name is "bitmaps", use OpenBmpDb("#bitmap") to open the file in "load-on-demand" mode, and OpenBmpDb("bitmap") to open the file in "lock&load" mode.

Bitmap databases (.prc's only) can be merged into an applet's .prc file, thus eliminating the separate bitmap database. Use par in append mode to do this (e.g. "par a applet.prc bitmap.prc"), and use your applet name (as specified with @dbname) in the OpenBmpDb call (though leave out the .prc extension).

Returns the number of bitmaps in a database opened with OpenBmpDb.

"Fast Bitmap". Displays the specified bitmap at the selected position.

Depending on how the bitmap database was opened, in either "lock&load" or "load-on-demand" mode, the bitmaps can either be addressed by bitmap index or by resource ID number. See the OpenBmpDb function description for more information on these modes.

If the database was opened in "lock&load" mode, the index field always refers to the bitmap index of the bitmap. The first bitmap in the database is at index 0, the second at 1, the third at 2, and so on. Returns 1 on success, 0 on failure (could not find record).

If the bitmap database was opened in "load-on-demand" mode AND the index field value is less than 1000 (decimal), the bitmap is also addressed by the bitmap index. If the index field value is 1000 or larger, the value is treated as a bitmap resource ID (thus only bitmaps with resource number of 1000 or higher can be accessed via this method).

Bitmaps draw faster in "lock&load" mode than in "load-on-demand" mode. However, the OpenBmpDb execution time is shorter in "load-on-demand" mode.

If no bitmap database is opened, then the application .prc is file itself is searched for bitmaps. In this case the mode is "load-on-demand".

Bitmaps with a depth of 1 will always draw in the current foreground and background colors regardless of the current screen depth (e.g. A 1 bit deep bitmap drawn on a 4 bit deep screen will appear in the current foreground and background colors).

Note: Drawing bitmaps at 8 bit boundaries seems to be faster than at other boundaries. Also the bitmap size is a multiple of 8 bits, that helps too. For example, drawing a 16x16 bitmap at location x=80,y=80 is faster than drawing a 17x17 bitmap at location x=161,y=160.

"Transparent Bitmap". This function allows the user to mask out a "hole" in the screen and then overlay a bitmap into that "hole". The mask is simply another bitmap resource with all black which defines the "hole". The overlay_index refers to the index of the bitmap to fill in the "hole". The mask_index refers to the index of the bitmap which defines the "hole". See FastBmp() functional description for how indexing with bitmap resource databases works.

If the mask_index is set to -1, no mask will laid down and the overlay bitmap will be placed on top any existing pixels, possibly altering the bitmaps appearance.

If running OS3.5+ and the bitmap specified with the overlay_index has its transparency bit set (see the SaveBmp & BmpInfo functions for more details), the mask will not be used, and the bitmap will draw in transparent mode. Setting the transparency bit on the mask bitmap can result in system errors ('Blitter.c, Line:XXXX,Transparency only supported in scrCopy mode').

Returns 1 on success, 0 on failure. This functions fails if the specified bitmap cannot be found.

TransBmp() is approximately 3 times slower than FastBmp().

Note: TransBmp only works in "lock&load" bitmap mode (see OpenBmpDb for more details on this mode).

This function saves part of the current draw buffer to a resource database (.prc file) opened with OpenBmpDb. Each bitmap resource should have it's own unique ID (typically they start at 1000). For OS3.5 and above, the transparency parameter defines what color will be made transparent. Set it to -1 for no transparency. Bitmaps made transparent will be drawn as non-transparent by OS3.3 and earlier. The function will return the index of the resource bitmap as needed by the FastBmp and TransBmp functions.

With compression, a bitmap can be made to take up less memory, however the bitmap will draw slower. There are three compression modes available: 0=none, 1=scan line, and 2=RLE. RLE compression can be much better than scan line, but it also may be much worse, even increasing the size the bitmap almost two-fold (it depends on the image). Also, RLE bitmaps will not draw correctly in pre OS3.5 systems. Scan line compressed bitmaps should draw correctly in all OS versions. Bitmaps can only be compressed in OS3.5+ systems (pre-OS3.5 systems default to mode 0).  Note: Compression does not work on OS5, all bitmaps created on an OS5 device will uncompressed.

A bitmap can either be transparent or compressed, but not both.

The Palm OS will not compress small bitmaps because compressing them offers little benefit.

Bitmaps larger than 160 by 160 may not save because Palm bitmap resources are limited to maximum size of 65k bytes. Compressing such large bitmaps often allows them to fit under this 65k byte ceiling.

This function can be used to save bitmaps to .prc application file.

Note: SaveBmp only works if the bitmap database is a .prc file. The function does nothing if the database is a .pdb file.

Given the index to a bitmap, the width, height, depth, transparency color, compression type, and ID are returned. The bitmap resource ID as the return value of the function. A zero is returned if the bitmap does not exist. The width, height, depth, transparency, and compression values are passed back through pointers.

A transparency value of -1 indicates that the bitmap has no transparency color set. There are three possible compression values: 0=none, 1=scan-line, and 2=RLE (see SaveBmp for more details about transparency and compression).

Warning: Some bitmaps (e.g. those created with RsrsEdit) don't set the depth parameter correctly on bitmaps they generate. Thus you can't always trust the return depth value. The SaveBmp function will set the depth correctly.

A zero can be passed in for the width_ptr, height_ptr, depth_ptr, tranparency_ptr, and compression_ptr parameters if their return values are not needed.

Note: This function only works if the bitmap database is a .prc file. It does not work on .pdb files.

This function will delete a bitmap from a resource database. If an index of -1 is specified all the bitmaps in the database will be removed. Furthermore, if an index -2 is specified the resource database is closed and deleted. A return value of 1 indicates success, 0 indicates failure.

Note: This function only works if the bitmap database is a .prc file. It does not work on .pdb files.

Roughly, this function combines the capabilities of TransBmp() and CopyRect() to manage a number of bitmaps and respective backgrounds with one function. With each call of this function, the previous background of every "sprite" bitmap is restored, and each sprite is then redrawn in its new position.

Alternatively, the save-behind feature can be disabled for a sprite by setting its save buffer (array[5]) to -1. This is useful when using a full screen multi-buffered approach where it is not desirable to save and restore the background behind each sprite.

Each sprite can be assigned its own user defined handler function which is executed internally each time Sprite() is called (unless the sprite is "off"). The handler function must be of the following format: func(int sprite_number, pointer array). The sprite_number indicates what sprite is being called (0=first one, 1=second one, etc), while the array pointer points the array structure for the given sprite. A good use of a sprite handler function is to check a sprite's position to ensure that it has not crosses any boundaries (e.g. the edge of the screen, etc.). The use of these handler functions can significantly reduce code complexity. See the sprite.c code sample for an example of how to use sprite handler functions.

X and Y movement vectors can also be specified for each sprite. The vectors are automatically added to the sprites current

The function has two inputs: the num_sprites parameter indicates the number of bitmaps ("sprites") to manage, the data_array parameter points an array of integers containing information on each of the "sprites". The array needs to be 12 times the number of sprites in size (e.g. for 5 sprites: array = malloct(5*12,'i');).

The array format is as follows:

Note: The array values repeat for subsequent sprites. (e.g. The New X position for the second sprite is at array[12], the third starts at array[24], etc.).

When the Sprite() function is called the following sequence of events occurs:

1. Restore the previous background behind all active sprites. *
2. Save the new background behind all active sprites (for new the positions). *
3. Re-draw all active sprites in their new positions
4. Update the position of all sprites with their movement vectors.
5. Call the handler function of each active sprite (usually to check if the new position is valid).

* Stage skipped for sprites with buffer (array[5]) set to -1.

Using the sprite save-behind feature can be faster than double or triple screen buffering, especially when using screen depths of 4, 8, or 16, however, the graphic rendering may not be as smooth.

The SpriteRecColl() function can be used for rapidly checking for collisions between sprites.

See the sprite.c program for an example using the sprite() function.

This function only works in "lock&load" mode. See the OpenBmpDb function for more information about this mode.

WARNING: Full-screen scratch buffers can use up a considerable amount of heap space (3.2k for 1 bit screen depths, 6.4k for 2 bit depths, 12.8k for 4 bit depths, and 25.6k for 8 bit depths). So if you are using a number of buffers don't be too surprised if you run out of memory… then again you may not (e.g. OS3.0 to 3.3 gives the user ~36k of heap). The HeapSize() function can be used to determine the amount of available heap memory. The CustomBuf() function can be used create smaller (or larger) buffer sizes and the FreeBuf function can be used to free the memory used by a buffer. Another trick is to use the SaveBuf and RestoreBuf functions to cut down on the number of active buffers (buffers saved to a database do not use heap space!).

SetDrawBuf(int buffer)

Sets the draw buffer. All graphics from then on will be directed to the specified buffer. Buffer 0 is the display buffer. Buffers 1 to 32 are scratch buffers (there is a maximum limit of 32 scratch buffers). Thus the allowed buffer number are 0 through 32.

Memory for the scratch buffers is automatically allocated as needed, and is freed when the application closes. Buffer memory allocated through this function is sized for the full screen (160 by 160 pixels). If the memory for a buffer has already been allocated, calling SetDrawBuf does not allocate new memory for that buffer. Thus if you call SetDrawBuf(1), SetDrawBuf(4), SetDrawBuf(1), and SetDrawBuf(5), you've actually allocated memory for 3 full-screen scratch buffers.

Smaller or larger than full screen sized buffers can be created with the CustomBuf function. The memory for a buffer can also be freed using the FreeBuf function.

Copies the entire contents of one buffer to another. (e.g. CopyBuf(0,1) copies the contents of scratch buffer 1 to the display buffer)

CopyRect(int src_buf, int dest_x, int dest_y, int src_x, int src_y, int width, int height, int mode, int zoom, int rotation)

Normally copies a rectangle from the source buffer to the current draw buffer. Alternatively, if the rotation field is -1, then the rectangle is copied to the destination buffer specified in the zoom field.

A number of copy modes are available:

*Erase and Swap modes work only in OS3.5 and up.

**When using CopyRect() with a screen depth of 8 (color) and in Mask mode (=2), the foreground color should be set to 255 and the background to 0, otherwise the masking will modulate the colors in the image.

The value in the zoom field determines how large or small to draw the copied rectangle. Values of 0, 1, and -1 perform no enlargement; a value of 2 performs a X2 enlargment; 3 yields a X3 enlargement, etc. A value of -2 shrinks the image in half, a value of 3 to a third, and so on. When therotationfield is -1, the zoom field determines the destination buffer (otherwise the destination buffer is the current screen buffer).

The following rotation values are available:

WARNING: This function tends to fail if the source buffer is also the draw buffer and the rectangles are in close proximity of each other. This is a problem with the operating system.

Clears the current draw buffer. Unlike the built-in clear_g function, ClearBuf removes the title bar

Allocates memory for a custom sized scratch buffer. The x and y parameters defines the buffer size in pixels. The buffer can be made to be smaller or larger than the full screen (160 by 160 pixels). The buffer number corresponds to one of the 32 buffer slots as described in the SetDrawBuf() section. The buffers created with CustomBuf() use the same buffer slots as those created with SetDrawBuf(). The only difference being that those created with SetDrawBuf() are automatically the full screen size, while the size of the buffers created with CustomBuf() is user defined.

This function normally doesn't need to be used unless you find yourself running out of memory due to too many full-screen buffers. (You will get a "Failed to create draw buffer" system error if this is the case.)

Frees the memory associated with the specified scratch buffer. Calling buffer 0, frees the memory for all scratch buffers.

This function does not normally need to be called because the all memory will be freed when the application exits. However, if you find yourself running out memory due to too many large buffers, this function may help.

This function opens a "buffer database" for use with the SaveBuf and RestoreBuf functions. If not such database exists then one is created and opened. . The new database will be of type "data". If the application is a stand-alone type, the creator ID of the database will be the same as the application, otherwise the creator ID will be 'PktC'.

Only one "buffer database" can be open at any given time. If a "buffer database" is already open, it is closed, and the new one is opened. The library will automatically close an open "buffer database" when the application exits. The CloseBufDb function can also be used to close a database if the user wants to modify it with the standard Pocket database functions. This function will return a 0 upon failure to open/create the specified database, and 1 upon success.

The modes are as follows: 0 = open database, 1 = open database and set backup bit, 2 = open database and automatically delete it when closed. Note that with mode 2, the buffer database will be automatically closed and thus removed when the application exits. Mode 2 is useful for applications which use the buffer database a temporary screen buffer storage (this can be used to get around the screen buffer quantity limitation).

CloseBufDb()

Closes the "buffer database" if it is open. Once a buffer database is closed, it can then be edited with the built-in PocketC database functions. For example, if one wants to set the backup bit on a buffer database the following operations should be applied: CloseBufDb(); dbopen("database_name"); dbbackup(1); dbclose();

int SaveBuf(int record)

Saves the contents of the current draw buffer to the a database at the corresponding record number. The database must have been opened with the OpenBufDb function. If a the record number is higher than the number of existing records in the database, the buffer will be written into the next available record slot. (So the record number specified may not be the one which gets written.) This function returns a 0 if the record cannot be saved, and a 1 upon success.

The database created is accessible via the standard PocketC database routines (provided that the database has been closed first).

Writes the contents of a database record to the draw buffer. The database must have been opened with the OpenBufDb function. If the buffer saved was of a custom size (see CustomBuf function), the screen size needs to be the same size and depth as to when the corresponding SaveBuf call was made, else you will get a garbled image. This function will return a 0 if the restore failed (usually means the record doesn't exists), and 1 upon success.

Arc(int x, int y, int x_radius, int y_radius, float start_phase, float end_phase, int sides)

Draw an arc with center at coordinates (x,y) with the horizontal extent x_radius, and vertical extent y_radius. The sides parameter determines the number of lines to construct the arc with, set it to -1 to draw a smooth curve. Use The phases are specified in radians. (e.g. arc(80,80,60,40,3*3.14159/2, 5*3.14159/2,-1); //draws an elliptical backwards C arc)

To draw a circular arc set x_radius and y_radius to the same value.

This function requires the Mathlib to run.

ellipse(int mode, int x, int y, int a, int b)

Draws an ellipse. The center of the ellipse is defined parameters "x" and "y". The width is specified by radius "a", while the height is specified by radius "b". If "a" and "b" are equal a circle is drawn. There are a number of modes available:

Example: ellipse(0x050a0002,80,80,30,40); //draws an ellipse of width 10 using a round brush (width=10, radius=5) using the custom fill pattern.

Given a array of (x,y) coordinates this function draws lines between the points specified. The pointer should point to an array of int's. The array_depth should be equal to the number of points times two (e.g. four coordinates require a depth of 8). A number of modes are available:

When OFFSET mode is enabled, the first (X,Y) coordinate pair in the array serves as an offset for all other points in the array. In other words, the first X parameter will get added to all the other X coordinates in the array, and the first Y parameter will get added to all the other Y coordinates in the array. This offset feature allows for the arbitrary repositioning of a polygon. The array_depth parameter must include both the initial offsets and all the points to be drawn (e.g. Drawing a polygon with 3 points in OFFSET mode requires an 8 deep array). The contents of the array is not modified by this function.

Warning: Be careful not to specify a pointer and/or depth value which will exceed the length of the array. This will cause the program to crash.

This function allows the plotting of points specified in either polar or Cartesian formats. Optionally lines can be drawn between the points. The (x,y) coordinate always specifies the origin. The radius and phase fields determine the position of the point to draw relative the origin position. If the radius is set to zero, the origin becomes the drawn point. Internally this function keeps track of the previous point drawn, this allows lines to be drawn connecting the current and the previous point. The following modes are available:

If the radius parameter is non-zero, the Mathlib is required.

int tri(int mode, int x1, int y1, int x2, int y2, int x3, int y3)

Given the 3 point coordinates a triangle is drawn. The following modes are available:

Returns the pixel value at the specified position from the draw buffer. If in grayscale mode the value returned is 2 bits.

SetPixel(int x, int y)

Sets the pixel at the specified position in the draw buffer using the current foreground color.

This function scrolls the contents of a given rectangle in the draw buffer. The direction field format is described in the table below. The distance is specified in pixels.

When scrolling, the graphics in the "evacuated area" will remain untouched.

This functions sets the custom fill pattern. The pattern is 8 by 8 bits and takes on the format of a traditional bitmap string with the two beginning size characters stripped off. Thus all pattern strings must have exactly 16 characters in them. The fill pattern can be drawn with the FillRect, FillLine, ellipse, plot, FloodFill, and tri functions.

The pattern is drawn with the current foreground and background colors (see SetFore & SetBack functions).

Example: SetPattern("fafafafafafafafa"); //sets a grid pattern

NOTE: Custom patterns do not draw correctly for OS3.3 when in 4 bit grayscale mode. This is an OS problem.

Line(int mode, int x1, int y1, int x2, int y2)

This function replaces the built-in "line" function. This function also allows for correct drawing in larger than 160 by 160 custom draw buffers.

Rect(int mode, int x1, int y1, int x2, int y2, int radius)

This function is a replacement the built-in "rect" function. The modes are as follows: 0=erase, 1=draw, 2=gray(checkerboard), 3=XOR,4=custom fill (as set with SetPattern)).

If bit 4 of the mode field is set, the x2 and y2 parameters are treated as the width and height for the rectangle. Thus Rect(0x11,10,20,30,50,0) will draw a 30 by 50 pixel rectangle at location (10,20).

Frame(int mode, int x1, int y1, int x2, int y2, int radius, int width)

This function is a replacement for the built-in "frame2" function. It offers custom fill drawing (mode=4), shadow effects, a 3D effect (removes corner pixels), and variable brush width (1 to 255). When the brush width is greater than 3 or the mode is set to 4, the radius capability only effects the brush corner radius. Widths greater than 3 are only available to modes 1 (solid fill) and 4 (custom fill). This function will allow for frame drawing in any sized custom buffer (the built-in frame2 does not). The shadow effects are always strait even when the radius is larger than zero.

If bit 4 of the mode field is set, the x2 and y2 parameters are treated as the width and height for the frame. Thus Frame(0x11,10,20,30,50,0) will draw a 30 by 50 pixel frame at location (10,20).

There is also no equivalent frame() function in the toolbox library because the same functionality can be obtained from Frame().

FloodFill(int mode, int x, int y)

Performs a floodfill at the specified point using the current foreground color. The fill is bounded by pixels having the foreground color. If the color of the point (x,y) is already the foreground color, no fill is performed. A number of fill modes are available:

When filling extremely complex graphics, the FloodFill algorithm may run out of steam and the fill may be incomplete. This can happen because the algorithm used was given a fixed amount of memory to operate with. Currently the function allocates 8k of heap memory to perform the fill, thus if you are already tight on memory due to the use of scratch buffers, using this function may cause a memory fault.

With this function a font database (.pdb or .prc) file can be opened. The function returns the number of fonts in the database. Once a font database is open, a font can be set using the textattr() built-in function. The font numbers for fonts in the database start at 129 and increment from there. So the first font is accessed with textattr(129,1,0), while the second with textattr(130,1,0), the third with textattr(131,1,0), etc..

If this function is called while a font database is already open, the first gets closed before the second is opened. When the application closed, the font database is automatically closed.

Fonts can placed inside an applet .prc file via the following method: First select a font database .pdb file containing the desired font. Use par to extract the fonts in the .pdb file into separate files (e.g. par x fontdb.pdb). Each font in the .pdb will now have its own unique .pdr file. The first number in the .pdr file name indicates its original index in the .pdb file. Rename the desired .pdr file(s) using the following format: pFNTxxxx.bin, where xxxx corresponds to a user defined 4 digit hex number (e.g. rename 001.0.0.pdr pFNT0001.bin). Each font .bin file should have its own unique hex number. Finally, append the new .bin file(s) to the applet .prc file using par (e.g. par a applet.prc pFNT0001.bin pFNT0002.bin). In the OpenFontDb() call, use the applet .prc name as the font database name (the one specified with @dbname).

Note: If using PilRC to generate a font resource, be sure to terminate the font with a "GLYPH -1" character.  See the PilRC manual for more details.

Here are some links to free fonts: Misc Fonts, Alphafonts,Cool Fonts, New Fonts.

There are also a number of font editing tools available, here are some: xFont (Freeware), NDM Pilot Font Tool ($12), Pilot Font Editor ($18), and Handy Pilot Font Editor ($22.95).

Returns the height in pixels of the current font. See the textattr() PocketC built-in function and the OpenFontDb() PToolbox function for more information about using fonts.

int textbox(int x, int y, int width, int height, int starting_line, string text)

This function clears out a rectangular area and fills it with the specified text. The starting_line field indication what line in the string to start drawing. If starting_line is -1, the total number of lines in the string is returned and the box is not drawn. Otherwise, the number of lines drawn is returned.

The text alignment, color, font, and underline mode can be changed via special escape character sequences. All of the escape sequences begin with the backtick ("`") character. Below is a table showing all the escape codes:

Int SpriteRectColl(int index, int num_sprites, pointer array)

This function allows for the rapid detection of sprite collisions. The index value determines what sprite to check against all the others in the sprite array. The num_spritesparameter determines the number of sprites to check in the sprite array. See the Sprite() function for more details on how the sprite array is structured.

The collision detection works by checking the rectangle boundaries of the sprites in question. If the rectangles overlap a collision is flagged and the index of the intercepted sprite is immediately returned. The collision detection process begins with the first sprite in the array. If no collision is detected with the indexed sprite, the next sprite in the array is then checked. This process continues until either a collision is detected or the last sprite in the array has been checked. If no collision is found, a -1 is returned.

If a sprite is in the "off" command mode, no collision check will occur between it and the indexed sprite.

Additionally, each sprite has a collision mask array element. This collision mask undergoes a bitwise AND with the collision mask of the indexed sprite, if the bitwise AND results in a zero no collision check will occur. For example, suppose the indexed sprite has a collision mask of 0x1002 (has bits 1 and 12 set), only other sprites which have either bits 1 or 12 set in their collision mask can collide with the indexed sprite (e.g.0x1000, 0x1001, and 0x0002 would all collide, but 0x2000 would not). The collision mask is an integer type and thus has 32 bits. Essentially, the collision mask provides a simple mechanism for determining what sprites can collide with each other.

See the sprite.c sample code for an example using SpriteCollRect().

Determines if the non-zero pixels in a resource bitmap will collide with non-zero pixels in the current draw buffer. Returns 1 for a collision and 0 otherwise. The mask_index refers to a mask bitmap (see TransBmp() function) in the current bitmap database (see OpenBmpDb()). Unlike TransBmp(), the mask bitmap must have the same depth of the draw buffer.

This function requires the bitmap database to be opened in load&lock mode with OpenBmpDb().

This function is approximately twice as slow as FastBmp().

int BmpBmpColl(int x1, int y1, int mask_index1, int x2, int y2, int mask_index2)

Determines if the non-zero pixels in two resource bitmaps will collide. Returns 1 for a collision and 0 otherwise. Returns 1 for a collision and 0 otherwise. The mask indexes refer to a mask bitmaps (see TransBmp() function) in the current bitmap database (see OpenBmpDb()). The mask bitmaps must have the same depth.

This function requires the bitmap database to be opened in load&lock mode with OpenBmpDb().

This function is approximately 2.5 times as slow as FastBmp(). Use BmpRectColl() whenever possible to improve a programs speed.

Determines if the rectangle spaces of two resource bitmaps will collide. This function does not check any pixels, and is thus quite fast. The mask indexes refer to a mask bitmaps (see TransBmp() function) in the current bitmap database (see OpenBmpDb()). The depths of the bitmaps does not matter.

This function requires the bitmap database to be opened in load&lock mode with OpenBmpDb().

Given an array of (X,Y) cordinates (same as in lines() function - mode 3) defining a polygon, and an point (x,y), the function returns a 1 if the point is inside the polygon, and 0 otherwise0. Points on the polygon boarders will either be reported as being inside or outside. In these cases the actual value cannot be determined beforehand, but it will at least be consistent.

There are two modes available, 0 = normal mode, and 1= OFFSET mode. See the lines() function for more information on how OFFSET mode works.

Given two rectangles, this function determines if they intersect, returning a 1 if true.

int LineCross(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4)

Given two lines (x1,y1,x2,y2) and (x3,y3,x4,y4), this function determines if they intersect, returning 1 if true. Thanks to BigFoot for this algorithm.

int CircleCross(int x1, int y1, int radius1, int x2, int y2, int radius2)

Given two circles, this function determines if they intersect, returning a 1 if true.

With these functions a reproducible sequence of random numbers can be generated.

Sets pseudo-random seed. Additionally, the function returns first random value (16 bit number) for the given seed. If the seed is set to zero, the seed is not updated, but the next number in the pseudo-random sequence is returned. This calls the SysRandom Palm OS function.

int prand(int range)

Returns a pseudo random integer between 0 and range-1. Range should not be more than 0xffff. The pseed() function sets the random seed for prand().

This is a random weighted number generation function. Given a string containing a list of weight values, a weighted random number is returned. The weight string should contain a list of numbers of zero or greater, each separated by a comma. The weight base is the sum of all these numbers. The return value of the function is the index of the weight randomly selected. The first number in the weight string is at index 0, the next at index 1, the third at index 2, and so forth. The chance that a given index value will be returned is equal to the that weight value divided by the weight base.

For example, given the weight string "4,1,3,2", the weight base is 10. There is a 4-in-10 chance of that in index of 0 will be returned, a 1-in-10 chance that 1 will be returned, a 3-in-10 chance that a 2 will be returned, and finally a 2-in-10 chance that a 3 will be returned.

If the weight string is "1,1,1,2,1,1", the return value will range from 0 to 5, but a 3 will returned twice as often as the other numbers.

Whitespace in the weight string is ignored. The weight string can contain up to 32 weight values. The pseed() function sets the random seed for wrand().

This function generates a random maze in memory. (It does not display the maze.) The contents of the maze can be accessed via the GetMaze and SetMaze functions. The memory for the maze is handled by the library. 8 bits of storage is allotted for each maze element (this allows for huge mazes). Only one maze is permitted at given time. Calling MakeMaze destroys any existed maze before it creates a new one. MakeMaze uses the pseudo-random number utilities in the library, allowing mazes to be reproduced by setting a random seed via "pseed" before calling MakeMaze.

A second maze algorithm can be enabled by setting the walls parameter to zero. This second algorithm is far more chaotic in that it corridors tend to be on average shorter and maze itself more intricate. The wallmin and wallmax parameters have not effect for alg #2.

This implementation is approximately 40 times faster than equivalent pocketC code.

Thanks to Rich Allen for the initial maze algorithm.

int GetMaze(int x, int y)

Returns an element from the maze. The value will have only 8 bits of information.

Sets an element in the maze. The value should be at most be 8 bits (between 0 and 255).

Date & Time Functions

This function converts the specified date into another format. See the below table for all the various format modes.

* As set in the "Formats" preferences panel.

int PickDate(int mode, int starting_date, string title)

This function pops a the palm date select form. There are three modes available: 0=select day, 1=select week, 2=select month. The initial date selected is specified by the starting_date field, which has a YYYYMMDD format. The title of the pop-up is specified with title.

If a day is selected the function returns that day in a YYYYMMDD format. If the cancel button is pressed, a -1 is returned instead.

int PickTime(int start_time, string title)

This function pops a time input dialog where a single time is entered and returned. The initial start time and the dialog title must be specified. The format for the start_time parameter and the return value is HHMM (where HH=hours and MM=minutes). If the "cancel" button is selected the function returns a -1.

int PickTime2(pointer start_time, pointer end_time, int start_of_day, int end_of_day, int start_hour, string title)

This function pops a time input dialog where two times, a start and end time are entered. The selected start and end times are passed back through pointers. Initial start and end call also be passed to the function through the same pointers. If the values passed in through the start and end pointers are both -1, an no initial time will be shown. Otherwise the start and end times should be of the format HHMM (where HH=hours and MM=minutes).

The start_of_day and end_of_day are both time values of format HHMM, which indicate the start and end of the days schedule. The start_hour parameter is only available for OS3.5 and above.

If the "cancel" button is selected the function returns a 0, if "no time" is selected a 2 is returned, otherwise a 1 is returned indicating that the start_time and end_time variables hold valid data.

Converts a time value in a HHMM format into a string. A number of formatting options are available.

* As set in the "Formats" preferences panel.

int AppPrefBytes(int byteCount, string CreatorID, int index, pointer version, int saved, pointer charArray)
This function provides byte level read/write access application preferences. It is particularly useful for modifying the preference settings of other applications (e.g. games, etc).

The byteCount parameter determines the number of bytes to write to the preference. If the value is -1, a read operation will be performed instead.

The CreatorID should be a string of four characters. The index refers to what preference "record" to access with the specified CreatorID. The preference record version is passed through a pointer. Specify a pointer to an integer if you want the preference version number back, or just a 0 if no version desired. If the saved parameter is a 1, the "Saved Preferences" database is checked for the preference, if 0, the "Unsaved Preferences" database is checked.

The charArray should be the pointer to an array of char types. In write mode (byteCount >= 0), the contents of the array is written to the preference. In read mode, the contents of the preference is copied to the array. If in read mode and the charArray field is set to zero/null, no read occurs but instead the function will return the number of bytes in the preference.

The function returns -1 if the CreatorID was malformed, and -2 if the preference could not be found (read mode only).

This function has been depreciated. Use the GetSysPref() function instead (modes 8,9,10, 31,32, & 33).

This function currently returns volume preferences. The following preference numbers are available:

* The return values are: Off=0, Low=8, Medium=32, High=64. These values can be used in conjunction with the vtone function to respect the users volume preferences.

int GetSysPref(int type)

This function returns the specified system preference value. This function directly calls the PalmOS PrefGetPrefrence API. See the PalmOS reference manual for more detailed information about this API function and how the various types work.

Note: First use type 0 call to determine the preference level available on the device. The preference version varies on OS version (2=OS2.0, 3=OS3.0, 4=OS3.1, 5=OS3.2, 6=OS3.3, 8=OS3.5, 9=OS4.0). Not all preference types are available for all OS versions.

With this function, any the system preference settings can be changes. Take care with this function because some of the settings cannot be easily changed back by the user (there is not panel access to some of them).

This function directly calls the PalmOS PrefSetPrefrence API. See the PalmOS reference manual for more detailed information about this API function and how the various types work.

See the table in the GetSysPref() for a complete list of preference types.

Array Functions

Copy(pointer src_array, int src_block_size, int src_starting_index,  pointer dest_array, int dest_block_size, int dest_starting_index, int num_blocks_to_copy, int copy_block_size, int mode)

A mass array/data structure copying function, supporting three different copy modes: many-to-many, one-to-many, and swap.  In many-to-many mode, many blocks of data are copied from one array to another.  In one-to-many mode, one block of data is copied from a source array to many blocks in a destination array.  In swap mode, blocks from two arrays are swapped.

The src_block_size and dest_block_size parameters should reflect the actual size of the data structures in the source and destination arrays respectively.  Arrays with no data structure formating have blocks sizes of 1.  The copy_block_size parameter refers to the number of elements from each source block to be copied to each destination block.  The src_starting_index refers to what element to begin copying in each source block (0=first element, 1=second, etc).  The dest_starting_index refers to what element to start copying data into for each destination block.  The num_blocks_to_copy parameter determines the number of blocks to copy.  The modes are as follows: 0=many-to-many, 1=one-to-many, and 2=swap.

pointe Array(string format)

This function allows for multi-dimensional array and data structure emulation. The format string must contain at least two arguments. All arguments should be separated by commas (e.g."i, 10,10" creates a 10 by 10 array of integers). The first argument defines the type of the data (i=int, c=char, f=float, s=string, p=pointer). The remaining arguments determine the sizes and number of dimensions. Each additional argument defines adds an extra dimension of the specified size (e.g. "s,3,4,5" creates a 3 by 4 by 5 multi-dimensional array of strings).

Data in an array is accessed in the same way as in ANSI C (e.g. data = Array("i,6,5,10"); data[4][6][3] = 9; element = data[4][6][3];).

The "type" field can also contain more than one type character. This allows for data structure emulation. For example: data=Array("iscf, 8, 4") creates an 8 deep array of structures. Each structure here is an integer-string-char-float. Thus data[1][0] is an integer, data[1][1] is a string, data[1][2] is a char, and data[1][3] is a float. The number of characters in the type format string must be equal to or less than the size of the last array dimension. For example, if your type string is "iiisc" than the last array dimension should be 5. If the number of type characters is less than the last array dimension size than the type characters will be repeated. For instance, "sif,4,9" will generate an array of 4 structures each with the following format "sifsifsif". Similarly, "i,5,20" will generate an array contains 5 stuctures of 20 integers each.

Numbers can prefix to type characters to signify a repeat count. For example: "5i2s3f" will produce a data structure of "iiiiissff".

The function returns a pointer to the created array/data structure. The memory of the array/data structure should be freed (with the "free" function) when it is no longer needed (e.g. free(data);).

Normally, integer, char, and float elements created by Array() are defaulted to zero. If however, a numerical (integer) value is placed as the LAST type format argument, that value is used as the default (this works for int types only). (e.g. Array("i34,7,8,9") - all data values are defaulted to 34!). Strings are always defaulted to "".

The maximum number of dimensions is 8.

The initial algorithm behind this function was derived from code provided by Wolfgang of BFSoft.

int Size(pointer array)

Warning: Only use this function on arrays created with the Array() function.

The Size() function returns the size of an array created with the Array() function. More precisely, the function returns the number of elements to the last array element. So if an array has 20 elements, Size(array) would return 20, while Size(&array[12]) would return 8.

Note that multidimensional arrays created with Array() will be larger than you may think. For example Array("i,3,4") will return an array of size 15 (12 for the data, plus 3 for internal pointers to the data).

To get the true total number of data elements in a multi-dimensional array, specify the pointer the first data element. In the 3 by 4 array case above, Size(&array[0][0]) would return 12.

The Size function can also be used to determine when you have reached the end of an array. If Size() returns 1, the current array index is the last element. (e.g. if(Size(array[x]==1) puts("Last index at "+x+"\n"); )

Sort(int mode, int blockSize, int offset, int numBlocks, pointer arrayPtr)

This function sorts an array of data. All four data types: integer, strings, floats, and chars are supported. Two different sort algorithms are available: quick sort, which is suitable for randomized arrays, and insertion sort, which is more efficient on arrays which are already mostly sorted. There are also a number of sorting options: strait ASCII or natural sorting, case-less or case sensitive sorting, forward or reverse sorting, and flat or pointer based sorting.

The array elements can be grouped into blocks (e.g. 3 elements per block), and these blocks can be sorted rather than the individual array elements. This is useful for sorting data structures emulated with an array. The size of the blocks is determined by the blockSize parameter. The minimum block size is 1 (i.e. one element per block). The offset parameter determines what element in a block to sort on. The first element in a block corresponds to offset 0, the next offset to 1, and so on. The numBlocks parameter defines the number of blocks in the array to sort. The arrayPtr parameter should point to the block where the sort is to begin (not necessarily the first block in the array, but usually). It should point to the first element of this block.

Up to three levels of sorting is supported. What this means is that if two blocks have a matching offset elements, then another offset value can be used to resolve how the blocks are ordered. If the values match again, then a third offset can be used to resolve the ordering. For example, suppose one is sorting a array containing the names of people. The names are to be ordered alphabetically according to last names. The block size is two. The first element in a block is a person's last name, the second element is a person's first name. Doing a two layer sort ensures that if any blocks have the same last name, the first name will be used to resolve the sort order.

If the "Pointer Sort" bit is enabled, the function will sort a set of data structures referenced by pointers. The arrayPtr field must be the pointer to an array of pointers. Each pointer in the array then points to a data structure. The pointers in the array are reordered such that the data structures they reference are sorted. If any of these pointers are zeroed, they will get moved to the end of the array (to the front if reverse sort is enabled for level 1)... useful for compacting an array which has had elements deleted.

Examples:

Given the following array of strings: 12jim, car, 20bill,1.2jack, bag, 4.0greg, 2bob, ape.

A forward ASCII sort yields: 1.2jack,12jim, 20bill, 2bob, 4.0greg, ape, bag, car.

A forward natural sort yields: 1.2jack, 2bob, 4.0greg, 12jim, 20bill, ape, bag, car (Note: the number are ascending!)

Int Query(int mode, int blockSize, int offset, int numBlocks, pointer arrayPtr, pointer matchPtr, pointer countPtr)

Fast array search. Given a value specified through the matchPtr parameter, this function will search through an array for a matching element. It works in a manner similar to the Sort() function with regards to the blockSize, offset, numBlocks, and arrayPtr parameters. The command modes also are similar. Two search modes are available: a binary search and a linear search. Binary searches are in general faster, especially for large arrays, but they require the array to be sorted (use the Sort() function for this). Linear searching simply starts at the beginning of the array and searches upwards either until a match is found, or the end of the array is reached. Like the Sort() function, the contents of the array can be divided into segments of size blockSize. The minimumblockSize value is 1. The offset parameter specified what element in each block to try to match (0=first element, 1=second element, etc.).

The matchPtr parameter is a pointer to the value to match. The value can be of any type, but it must of the same type as the array elements searched. The countPtr parameter should be a pointer to a integer variable. If a match occurs the number of consecutive blocks with the matched will be returned though this pointer. If countPtr is zero, no value will be passed back. The countPtr feature is useful for determining if more than one block matched. In these cases, the Query() function can be called again to resolve the search by using a different offset value. The array should be sorted if the countPtr feature is used. Additionally, if a Query() call is doing a binary search and no match is found, the countPtr variable will return the closest match position (depending on the Return Mode settings, either a block index or a block pointer will be returned as the closest match position).

If a binary search is used, the array must first be sorted. Use the same reverse, case-sensitivity, and natural sort settings with the Query() function as were used with the Sort() function.

If a match is found, either the block number or a pointer to the block number is returned, depending on how the mode parameter was configured. See the Return Mode bit in the Query Mode table below.

Pre 4.0 OS roms suffer from a bug in the binary search API which limits the maximum array size to 5460 elements, beyond this number, the algorithm may yield unpredictable results.

String Functions

Given a pointer to a string, this function can cut out a selection of it and/or insert new text at that point. The stringPtr parameter is the pointer the string to operate upon. The insertStr parameter is the text to insert. The position parameter specified the byte offset in the operation string to insert and/or cut text. Zero is the position if the first byte. The cutLength parameter specifies the number of character to remove, starting at the point marked by position.

If insertStr is empty (i.e. ""), no text will be inserted. If cutLength is zero, no text will be cut. If cutLength is greater than zero, this function will return the cut text.

string Join(int arraySize, pointer array, string separator)

Given an array of values (of any type: string, int, float, or char), this function will convert all the values into strings and join them together with separator string. The resultant string is returned.

This function is particularly useful for turning an array into a CSV (comma separated value) string. Example: result=Join(10,array,",");. The Split() function can be used to reverse the process.

The speed of this function is about twice that of equivalent PocketC code.

Replace(pointer stringPtr, string searchString, string replaceString, int mode, int offset)
This function will perform a "search & replace" operation on the string specified via the stringPtr parameter (it's a pointer to a string).  The searchString field contains the string to search for.  The replaceString field contains the string to replace the found string with.  There are two modes: 0=replace first occurance then exit, and 1=replace all occurances.  The offset parameter specifies the character position in the string to start the search & replace operation.

This function will take a string and segments it into smaller pieces based on a set of delimiter characters. Each segment is then written to the specified array.

The stringPtr parameter is a pointer to the string to split. The count parameter determines the number of values to split and place in the array. The array pointer parameter refers to the array to fill. The delimiters strings contains one or more characters which define the segment boundaries. If for example the delimiters string is ",\n" either the a comma or line-feed encountered will serve as a segment boundary character. The delimiters characters are not included in the segments placed in the array. If the delimiters string is empty (e.g. ""), all white-space characters will be used for the split (equivalent to " \n\r\t").

If the first character in the delimiter string is a "@", the delimiters will be "grouped", meaning that if consecutive delimiter characters are found, they are treated as just one with regards to segmenting the input string. The "@" as the first character will not be treated as a delimiter character. For example, given a string "this,is,,a,,,test". A delimiter string of "," will return 7 segments (3 of them empty), while a delimiter string of "@," will return 4 (the four words). The "group" mode is useful for extracting the words in a string, while the "ungrouped" mode is better for handling CSV (comma separated value) data.

If the count value is zero, the splitting does not occur, but the function will return to total number of split segments found. This can be used to determine the size of the array needed to fill. It can also be used to rapidly count the number of words in a string. If the count is -1, then all the segments are written to the array.

WARNING: If the array is not large enough to hold the all the split segments, a system error will result. Either call Split initially with a count of zero to first determine the number of segments, or set a count value which is equal to or less than the array size.

If a non-zero count value is used, the number of segments split and placed in the array is returned.

The array can be of any type (string, int, float, or char), or even of mixed type. The Split function will automatically perform a type conversion on each segment so that it matches the corresponding array element type.

int AutoOff(int seconds)

Sets the auto-off timer value. A time of zero seconds turns off the timer. The previous setting is returned.

This function returns information about the current battery state.

Swap(pointer A, pointer B)

Given a pointer to two variables, this function simply swaps the data. This function is approximately 60% faster at swapping non-strings than equivalent PocketC code, and 6 times faster at swapping strings!

int/string Note(int command, string database, string str, int index, string title, int start_pos, int select_length, int max_length)

Note is multi-use text input/viewing function. It also has fast record sorting and searching capabilities.

The text to be edited can either be a string passed to the function or a record in a database. In either case, the maximum string or record size is 32k bytes (this breaks the 4k memo pad size limit!). PocketC is also capable of compiling memos larger than 4k.

When editing text, the screen takes on a form similar to that of the Memo Pad application. The edit form features include a scrollbar, a grafitti shift indicator, up/down hardkey paging, copy/cut/paste/undo/select all (via menu and shortcut keys), the pop-up keyboard, grafitti help, and a "byte count" menu option.

The title field specifies the text to be used as the title of the edit form. The start_pos field specifies the position in the field to place the cursor. The select_length fields specifies the length of text to initially highlight, starting at the start_pos location. The max_length field specifies the maximum allowable size of the edited text in bytes (the highest possible value is 32768 bytes).

The graph_on() command should be called before using Note(), otherwise a system error will result.

Be sure that any records read in by Note() are null terminated (they must end in a zero char), else system crashes will likely occur.

The font of the edit field can be changed by calling textattr() before Note() (custom fonts work too!).

The natural sort differs from the alpha-numeric sort in how it handles numbers. See below:

Alpha-numeric sort: 100a -> 10a -> 1a -> b

Natural sort: 1a -> 10a -> 100a -> b

For more details on the natural sort algorithm go here.

int GetURL(string url, string database, int record_index, int mode, int max_bytes, int timeout)

This function allows users to download content from the internet and place it into a database record. Once a block of data has been downloaded to a record, the user can then do whatever they would like with it. This function requires the INet Library to work (the Net Library will not do). The INet Library comes pre-installed in all Palm VII devices, it also comes with the Palm Mobile Internet Kit and with some modems.

The max_byte field determines the maximum number of bytes to download. The timeout field determines the amount of time in ticks (usually 100 per second) to wait for data (a -1 means "wait forever").

You can test your programs with the POSE emulator using a Palm VII rom by: 1) setting the iMessenger proxy in the Preferences->Wireless window to 209.247.202.106, and 2) by checking the "redirect Net Lib calls to Host TCP/IP" box in the emulator Settings->Properties window.

Here is matrix of all the available modes:

Here is a matrix of all the possible return codes:

int Handera(int mode, int state)

This function provides access to a number of hi-resolution drawing and screen manipulation capabilities of Handera ™ devices. The grid below shows the available features.

See also the Fevent() function for Handera jog dial support.

This function returns the number of bytes of the largest contiguous block in the heap. Also, the total number of free bytes remaining in the heap is returned through the freebytes pointer. If freebytes is zero, no "bytes free" value will be returned (e.g. x=HeapSize(0);).

This function is particularly useful for debugging when working with many screen buffers and/or with large multi-dimensional arrays (see Array()). The sizes used the full screens (160 by 160 pixels) is as follows:

int Sony(int mode, int state)

This function provides control over the high-resolution display available on certain Sony devices. The grid below shows the available options.

Note: When mode 2 is enabled (special hi-res drawing), the FastBmp() function will draw in a 320x320 resolution, otherwise it will draw with a 160x160 mode (the pixels are doubled so at to appear as if the screen were 160x160). The textbox() function also has additional font capabilities in this "special" drawing mode, notably 8 additional fonts become available: the standard fonts (0-7)(which display small) and their equivalent Sony hi-res fonts (8-15)(these are larger). When the special hi-res mode is disabled, textbox will by default use the sharper Sony hi-res fonts. The line() function will also draw in high resolution (thin lines) when in high-res drawing mode, however line thickness control is not supported. Also, when the special hi-res drawing mode is enabled, both the FastBmp(), textbox(), and line() functions need to use coordinates in a 320x320 space rather than 160x160.

While in high-resolution mode (320x320), all text drawing functions and forms will use the Sony hi-resolution fonts (though textbox() has additional font options enabled through Mode 2).

WARNING: A number of PToolbox drawing features will behave strangely in pre-OS5 Sony high resolution mode (320x320), though many will draw as if in 160x160 mode. The functions which behave oddly or badly in high-resolution mode are:

• All the screen buffer functions, with the exception of ClearBuf(). Full sized scratch buffers actually work in low screen depths, but any graphics drawn in them using the standard drawing functions will use a 320x320 coordinate scheme. Higher screen depths will likely cause the heap to overflow, especially when more than one buffer is in play.
• GetPixel()
• FloodFill()
• SaveBmp()
• Likely others (if you find others, please let me know so I can add it to the list)

This function is similar to the built-in tone PocketC function except is has two additional parameters. There are three modes: 0=blocking, 1=non-blocking; 2=stop sound. In blocking mode, the function exits after the tone finishes playing. In non-blocking mode, the function exits before the tone is finished playing. Calling this function while a non-blocking sound is already playing will interrupt the old sound and immediately play the new one with no silence gap! The "stop sound" mode will terminate a playing non-blocking sound.

The acceptable range of volumes is 0(no sound) to 64(max value). A volume value of 1 is much quieter than 64, however it is not exactly near-inaudible.

See the GetPref function for determining volume preferences.

int Backlight(int mode)

This function can be used to turn the backlight on and off, or get the backlight's current state. The modes are as follows: 0=off, 1=on, 2=return state (0=off, 1=on). If the backlight doesn't exist on the device (like IIIc machines) a -1 will be returned.

int Feature(int mode, string creatorID, int index, pointer value/valuePtr)

This function provides access to PalmOS feature resources.  Features are 32 bit storage elements which are tied to specific creator IDs.  They are useful for storing small amounts of data, and are simplier to use than databases.  There are three mode values: 0=read, 1=write/create, and 2=delete.  The creatorID is a 4 character string which specfies the creator ID to use (note: all creator IDs should be registered here).  The index refers to a slot to access (similiar to a database record number).   A given creatorID may have feature data stored at many indexes (32 bits storage per index).  The value/valuePtr functionality varies depending on the mode.  In read mode (=0), valuePtr should be pointer to an integer (e.g. &variable).  In write/create mode (=1), value refers to the integer which is written to the feature.  The value/valuePtr field is not used on delete operations (=2). 

All features are deleted upon a soft reset.  Also, if an application with the same creator ID is deleted, the feature will also be deleted.

This function returns 1 upon success and 0 if the operation fails.  If valuePtr is 0 on a read operation, no value will be passed back.  This is useful for testing if a feature exists without having to declare a variable to hold a return value.

Given a hardkey number, the function returns 1 if the key is currently being pressed, 0 if not. The hardkey numbers are as follows: 1=calender key, 2=phone key, 3=todo key, 4=note key, 5=page up key, 6=page down key.

This function has no internal sleep delays, as such it is best to call sleep() after you do a round of these, otherwise the battery drain is much faster.

Thanks to Vilmos for this very handy function (he provided the source code).

A value of 1 disables all hardkey keydown events. A value of 0 re-enables hardkey downkey events. The CheckKey function can still be used to check the status of the hardkeys.

Since using this function disables downkey hardkey events, pressing the keys will not reset the auto-off timer. The application should periodically call the resetaot built-in PocketC function (when keys are found to be pressed) to prevent the PDA from nodding off.

As a side effect, this function disables the tick system sound normally produced when the page up and down keys are pressed.

This function returns the contents of the processor register at the specified address. See the appropriate processor manual for a description of available registers. WARNING: This function also cannot be used with the emulator, it will yield "bus errors".

This function writes the contents of the processor register at the specified address. See the appropriate processor manual for a description of available registers. WARNING: The use of this function can be dangerous (possibly causing soft or hard resets), so make sure you know what you're doing before you use it. This function also cannot be used with the emulator, it will yield "bus errors".

This function invokes either PalmPrint or SCS Server software (which must be installed on the Palm device) to perform IR printing. Both products are from Stevens Creek Software. Note: SCS Server is a streamlined version of PalmPrint. There are a number of commands available, see the SDK section at the PalmPrint Developers page for a full list of commands.

This function returns a 0 upon success and a 1 if the PalmPrint or SCS Server is not installed. Other values indicate a failure in the IR printing software.

For the expanded formating commands (#32800 and higher), the data value should be an integer when appropriate.

int GetTicksPerSec()

Returns the number of ticks per second for the device. This function calls the SysTicksPerSecond OS system function and returns the result.

Returns a 3 digit hex value corresponding to the OS version being used. (e.g. OS3.3 returns 0x330, OS3.5 returns 0x350).

Returns a 3 digit hex value corresponding to the PocketToolbox version being used. (e.g. version 3.00 returns 0x300).

int Vibrate(int count, int rate, int pattern)

This function activates the vibration hardware available on some devices. The count value indicates the number of vibration intervals to perform. The rate indicates how long each interval should be (100 = ~1 sec). While the pattern determines the vibrate pattern. All 32 bits are used for the pattern. Bit 31 (i.e. 0x80000000 or 1<<31) is the starting bit while bit 0 (i.e. 0x00000001 or 1<<0) is the ending bit.

If the count value is a 0, the function will return a 1 if vibration hardware is available and a 0 if not. This function does nothing if no vibration hardware is present.

WARNING: This function uses undocumented PalmOS API (I actually had to do debugger crawl to figure out how it worked). Given that there is no Palm OS documentation supporting this API, there is the possibility that using this feature may do harm your device (e.g. using very small rates like 10 with choppy patterns like 0x55555555?). Then again maybe not, I'm just guessing. As such, use this function at your own risk.

To replicate the standard three vibration alarm do the following: Vibrate(3,78,0x000000FC);

PRC Embedding

It is possible to embed the PToolbox library inside an application's .prc file. With the library embedded, the host application does not require the external version of the library. Furthermore, the library has been divided into a set of plug-ins, where each plug-in contains a set of related functions (Forms, Database, DateBook, String, etc). A user need only include the plug-ins required for the application, it is thus possible to significantly reduce the memory footprint of an embedded library.

An unlock code is required for an embedded library work on a real device (the correct code is not required when using the emulator). Each application with a unique name and creator ID will require its own unlock code. There will be a fee of $30 USD for each unlock code. Payment options are given later in this document. Note: The standalone version of the library having the icon will always remain freeware.

It is possible for other applications to use the embedded library contained in an application. The caveats are that the host .prc must be a PocketC application created with the PocketC Desktop Edition (PDE), and the host application must be installed on the device. See the Satellite Applications section for more details.

The following table list each plug-in and what functions they contain.

Embedding Process

1. Get PDE (PocketC Desktop Edition) & install it.
2. Download par (http://www.djw.org/product/palm/par/) & put it in the directory where PDE is installed.
3. Move the PToolbox Plugin directory to reside in the directory where PDE is installed.
   
4. Make a copy of the PToolboxLib.lib file and rename it to <your_app_name>.lib (same name as  used for @dbname).  Place this new .lib file in the directory where PDE is installed.
5. Setup the program header. See Program Header section below.
   
6. Compile the program on PDE.
   
7. Test app on PalmOS Emulator & Simulator (unlock code is not required to do this). Verify that that there are no missing plugins and that the application yields no unexpected errors/warnings (see Debug Information section for more details).

• The Note() function currently does not have a plug-in. The Note() function can be emulated with a resource form containing a field, scrollbar, GSI, and necessary buttons.
• Currently (as of v7.5.2) the SaveBmp() and Frame() functions do not officially work for palm OS5.
• The DateBook interface functions will currently not work for OS6 (yes 6, this is not a typo). The library will need to be updated when the OS6 SDK and simulator is released.
• When using PToolbox forms on the PalmOS Simulator, button objects will yield the following warning "i:\banzai\arm\core\emul68k\src\control68k.c, Line:1305, Not a graphic control" when the application exits or a form is freed.  This warning is harmless and should be ignored.  It is generated by a flaw in the simulator.
  

1. That the application Creator ID has been registered with PalmSource (http://dev.palmos.com/creatorid)
2. Choose an application name that you really want.  Changing the application's name (or creator ID) will require an new unlock code and an additional $30.
3. Validate that the application (containing the embedded libarary) runs without warning messages or errors on both the PalmOS Emulator and Simulator (http://www.palmos.com/dev/tools/).