Pocket Toolbox: A PocketC Palm native library 7.6.1

Copyright © July 2000-2003 by Joseph H. Stadolnik III, All rights reserved.

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

Feature List

Legal Statement

​​​​​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 [email protected] . 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 the zipped documentation for more details.



v7.6.1 6/29/2003
Fixed bug in GetPTVersion(), it was returning 0x754 for version 7.6.0.
v7.6.0 6/23/2003
Added Copy(), an array copying function (has many-to-many, one-to-many, and swap copy modes). Added Replace(), Strip(), and Translate() string manipulation functions. Added FgetList() for getting all elements of a list. Added Run() for launching apps and PocketC applets by name. Added Feature() function for PalmOS feature access. FsetText() & FgetText() now works on labels and titlebars (use id=0). List draw handler can now draw horizontal spacers (see Fctl LISTHAND command). Fctl BENABLE & BDISABLE both now accept an id of -1 argument which enables/disables all buttons. Fevent() now traps FrmUpdateEvent, 5-Way navigator, and Sony Jog dial events. New Fctl LISTLEN command for getting number of elements in a list. New Fctl JOGMASK for disabling Sony Jog assist. New Fctl FIVEWAY command to enabling the 8 compass directions on 5-way navigator. New plot() offset mode. DBinfo() field count mode now returns a count based on the last non-none field position. CopyBuf() speed up (now a hair faster then PocketC's bucopy() function). Fixed HanDBase access error occuring on DBgetfield() if field was of of type none. Fixed thick line drawing for points far off screen. Fixed BmpInfo() pointer bug. Fixed OS5 FrevList() bug. Fixes Sony OS5 font anomolies.
v7.5.3 1/15/2003
Fixed bug effecting NR70 devices when using Sony(1,1). Fctl HIDE/SHOW now works on scrollbars for pre-OS3.5 systems.
v7.5.2 1/14/2003
New SetScale() function for high-resolution graphics control on OS5 devices. New Trunc() function. Improved form ID checking on Fctl LOAD, Form(), and Dialog(). Fixed a nasty memory leak bug effecting FsetMany() on pre-OS3.5 systems. Fixed GetDate/AddDate PDA based compile bug. Fixed small font problem on Sony OS5 devices. Handbase3 support is now fully functional (DBcreate now works for it). Fixed two embedding library bugs.
v7.5.1 12/19/2002
Library can now be embedded in an application .prc file. New improved Arc() function. New SETGSI Fctl command for setting GSI state. Sped up tri() function. Fixed bug in SaveBmp. Support for PocketC v5.x.x (apps larger than 64k).
v7.5.0 11/22/2002
DelDate(). EHAND and REPEAT Fctl commands now return previous handler functions. New Vibrate() command for controlling the vibration engine on some devices. FsetMany/FgetMany now works on standard form buttons. Fevent() can now trap "button exit" events. New Fctl commands: BENABLE (button enable), BDISABLE (button disable), and BEXITID (for button exit event capture). Renamed line() to Line(), rect() to Rect(), and frame2() to Frame(). New (x,y,width,hieght) mode for Rect() and Frame() functions. Fixed empty resource list bug. Many OS5.0 compatability updates. Removed: SetAppPref(), GetAppPref(), serIR(), arc(), and polygon(), and tbitmap() functions. Added PTLreg() function for embeded library activation (undocumented).
v7.4.4 8/20/2002
Fixed bug in OpenFontDb() occuring on app exit when the database contained no fonts.
v7.4.3 8/8/2002
Added AppPrefBytes() function. Fixed bug in GetPref() call. Fixed Size() bug for PDA compiled code. Fixed Note() bug occuring in mode 1 when field emptied.
v7.4.2 7/20/2002
Added Size() function for getting array size (Array() created only). If Field() height param is zero, automatically resizes it the current font height. Enhanced Array(): i) no more limitations on data structure size, ii) numerical prefixes to types now signify repeat count for that type (e.g. "3i4f2s"), iii) optional default integer value now must immediately follow type strings (e.g for a default of 4 do "i4"), and iv) if type string is less than data structure size, the types automatically repeat (e.g. "si,4" will produce "sisi"). Fixed bug in arc() function.
v7.4.1 7/4/2002
Fixed bug in BmpInfo().
v7.4.0 7/1/2002
Resource scrollbar support with field binding capability (see new EHAND Fctl command). New FgetMany() & FsetMany() functions for quickly moving array contents to/from matrices (tables) of fields and buttons. Added FaddList(), FdelList(), and FrevList() functions for better control of list objects. New Compress() function for de/compressing database records. New CmdBarAdd() function for adding icons to the command bar. Sort() can sort data structures referenced by pointers. Three new Fctl commands: EHAND (new event handler, supercedes REPEAT), SCROLLMODE (for scrollbar & slider control), and POPMENU. Zoom out mode capability added to CopyRect(). If no bitmap database is opened and FastBmp() is called, the application .prc is searched for the bitmap (using load-on-demand mode). Faster form cleanup. Added duplicate Id and post DRAW installation checking for dynamic form objects. Fixed offset bug in Query() function. Fixed empty resource list bug. Fixed field draw for FsetText when form is not visible. Fixed graph_on issue effecting hi-res mode on Handera devices. Plugged memory leak occuring with DBgetrec() calls on a HanDBase databases with zero records. Fixed OpenRsrcDb() re-entrancy bug. Fixed CopyBuf() bug occuring when forms are deleted. Partially fixed graffiti hide issue on Handera devices. Removed natural sort capability from Note() function.
v7.3.6 4/28/2002
Fixed bug in FsetText() effecting fields.

v7.3.5 4/25/2002

Added TRIGTIME, OBJTYPE, STBLSIZE, STBLPFX, and STBLGET Fctl commands. Line() now draws in hi-res when Sony hi-res drawing is enabled (mode 2). SetDepth(-3) returns current color depth. Fixed string reference count bug effecting Split() & DBgetrec() functions. Fixed a memory leak associated with resource forms which don't have titlebars.

v7.3.3 4/2/2002

Fixed form drawing problem on Handera devices.

v7.3.2 4/2/2002

Fixed form drawing problem on Sony hi-res devices.

v7.3.1 3/30/2002

Fixed Dbopen() bug effecting HanDBase databases. Fixed HanDBase date formatting bug. Fixed string handle bug in Insert() function. Fctl SETACTIVE and SETFORM commands now return ID of the current form.

v7.3.0 3/24/2002

HanDBase® and Pilot-DB database interface functions: DBcreate(), DBopen(), DBinfo(), DBsetrec(), DBgetrec(), DBgetfield(), DBrm(), and DBmoverec(). The Query() function will now returns the closest match on search misses through the countPtr pointer. Fixed resource form display issues with no-save-behind resource forms on pre-OS3.5 systems. Plugged memory leak with pop-trigger buttons on OS3.1. Fixed a bug in how silk buttons worked via HOOKSILK and HOOKMENU when a list was popped. PToolboxLib should now work if installed on a handspring springboard rom.

v7.2.3 3/9/2002

Added Sony() function for Sony high-res screen control. Force initial screen size to 160 by 160 on Sony high-resolution devices. Corrected x & y coordinate swap on FormBmp() function. Now if Fctl SETFOCUS command Id is zero, the focus is released. Slider objects in resource forms will always be hidden in pre-OS3.5 systems. FsetList() updated: new selection=-2 and num_items=-1 options. PocketC background event checking is now disabled upon first the Fevent() call when using PocketC v4.3.0+, this fixes the event loss problem previous encountered with Fevent().

v7.2.2 2/28/2002

Added Swap() function. Added new delimiters option for the Split() function.

v7.2.1 2/22/2002

Fixed PDA based compile problem with some new v7.2.0 functions. FormBmp() objects will now SHOW/HIDE in pre-OS3.3 systems.

v7.2.0 2/21/2002

Resource Form support (everything but scrollbars and tables). An function called OpenRsrcDb() for managing temporary resource databases. Three new dynamic form object functions: FormBmp(), GButton(), and Slider(). Five new Fctl() commands: POPHELP, POPALERT, POPDIALOG, GETTSTR, and SETFORM. Added Sort(), a general purpose array sorting function. Added Query(), a general purpose array searching function. Added three new string manipulation functions: Split(), Join(), and Insert(). Added Handera() function for managing features on Handera devices: hi-resolution display, grafitti area, screen rotation, form expansion, bitmap expansion, and font translation. The PalmPrint() function from the IRPrintLib is now included. OpenFontDb() now handles both pFNT and NFNT resource types in .prc files. HeapSize() function no longer compacts the heap. String allocation in Array() function is now x20 faster. General speedup: native library overhead reduced for all functions, resulting in a 5% to 40% speedup, depending on the function. Note() edit-index and edit-name modes now return the cursor position on exit. Added new copy-to-clipboard command bit to Note(). Fixed Note() crash bug with OS3.1. Grafitti stroke for Copy item in Note() pull-down fixed. Fctl/Fevent BINDX, BINDY, and BINDKEY crash bugs fixed.

For complete history see PToolboxLib docs in .zip file.


PtoolboxLib761.prc - the library (current version)

PtoolboxLib753.prc - previous version of the library

PToolboxLib.htm - this document

PToolboxLib.lib - PocketC desktop edition file (put in PocketC desktop directory)

map_demo.c - a "drag about" map demo

toolbox_demo.c - a demo of many features

vtone_demo.c - a demo of the vtone function

test_bitmap.prc - a test bitmap resource database

multiform_demo.c - a demo showing how to use multiple forms

field_demo.c - a demo showing how to use forms & a simple menu

button_demo.c - a demo showing buttons and lists

database_demo.c - a demo showing how use the PToolbox database functions

fevent_demo.c - a demo showing how to trap pen & key events with Fevent().

list_demo.c - a demo showing how to use the FaddList, FdelList, & FrevList calls.

sprite.c - an example using the sprite() function to manage bitmaps.

graphics.c - Shows 3 different graphics techniques.

menu.rcp - A PilRC file for creating a resource menu (includes instructions)

speedopt.c - A collection of non-PToolbox speed optimizations for PocketC


Due the large size of this section, the on-line function documentation has been pulled (at least temporarily) from this web page. The full documentation is contained within the main PToolboxLib.zip file.

Tips & Tricks


Dynamic forms are supported only on OS3.0+. The GSI(), Slider(), and Gbutton() functions are only supported on OS3.5+.

The following features do not work for OS2.0: dynamic form objects, grayscale graphics, font importing, and non-blocking sound with vtone.

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

CopyRect() function modes 1 (Erase) and 6 (Swap) work only for OS3.5 and up. This is an OS problem.

Under OS3.3 there is an intermittent emulator warning which appears when PocketC exists and the Math library is present.

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.

Contact Information

Please direct any bugs, suggestions, or feedback to [email protected] There is also a PToolboxLib forum, click here to go there. If you have a question, suggestion, or trick which you think others might find useful please post it to the PToolboxLib forum.

If you think you've found a bug, first make sure that you are using the latest versions of the Toolbox library and PocketC. Also, be sure that you are running with the most current Palm OS patch for your operating system. If the problem persist, please include the following information in an email: OS version, PocketC version, screen depth being used, a description of what is happening, and any relevant source code (small, complete test cases are a big help). Thanks.

Hosted by www.Geocities.ws