Introduction

Pocket Toolbox: A PocketC Palm native library 7.6.1

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

Download

Click here to download Version 7.6.1: PToolboxLib.zip

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)
OS5+ High Resolution support.
Array sorting (alpha-numeric, natural, reverse, case-less, data structure, and 3 layer sort options) and searching capabilities
String manipulation functions: Insert, Join, Replace, Split, Strip, Translate, and Trunc. and insert.
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
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, polygon, arc, 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 & Vibration control
System and application preferences access
Handera high-resolution, rotation, and graffiti area control.
Sony high-resolution support (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 now be fully embedded inside an application.

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.

History

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.

Files

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

Functions

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

Be sure to test your application with the Palm Emulator using a number of "Debugger" ROMs. Both the emulator and the ROMs are available at www.palmos.com. Applications should be considered unstable until they run without errors on debugger ROMs. If you don't do this, your application runs the risk of crashing and/or corrupting a users PDA. Good ROMs to test on are OS2.0, OS3.1, OS3.3, OS3.5, and OS4.0. Handspring, Handera, and Sony ROMs may also be useful.
An application should check the PToolboxLib and PocketC versions (see GetPTVersion). If the minimum version requirements are not met, the application should call an alert() and then exit. For example, the PToolboxLib form functions are only available in v7.00 and above. An app which uses the form functions should warn the user and then exit if an earlier version of the library is installed.
Databases which have the same creator ID as an application and are of type "data" will automatically delete when the application is deleted.
Bitmap databases (opened via OpenBmpDb) 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 (at specified with @dbname) in the OpenBmpDb call (though leave out the .prc extension).
Fonts, like bitmaps, can be embedded within an application. See the OpenFontDb() function description for information on how to do this.
Resource bitmaps of a lower depth can still be displayed if the display is of a higher depth. Bitmaps with a depth of 1 will always draw in the current foreground and background colors regardless of the current screen depth.
Use 1 bit depth mask bitmaps for TransBmp. This saves memory. (The TransBmp() function will always draw a 1 bit deep mask bitmap in black & white regardless of the current color settings.)
A buffer database (OpenBufDb) can be used to extend the number of screen buffers. Set mode 2 when calling OpenBufDb to automatically remove the buffer database upon program exit.
Try using 4 bit color mode, SetDepth(5), rather than 8 or 16 bit color mode. This not only increases the speed of graphics drawing, but also reduces the size of color bitmap resources by half.
It is not necessary to close bitmap, buffer, resource, or font databases, the library will close them automatically upon exit.
Larger than 160 by 160 resource bitmaps can be drawn in custom sized screen buffers. Use BmpInfo() to determine the size of the bitmap. Next create the appropriately sized custom buffer with CustomBuf(). CopyRect() can then used to copy portions of a large bitmaps to the screen. If you need to re-use the custom buffer with a different size, call FreeBuf() to remove it first.

Limitations

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