PCL - The Pilot Class Library
(beta 0.2.0)
[get the latest release]
.
[release history]
The Pilot Class Library (PCL) is designed to easily create
UI applications on the PalmPilot using G++ (the GNU C++).
I Found out that the combination GNU C++ 2.7.2.2 / prc-tools.0.5.0 is
surprisingly suitable for creating C++ applications. The only real
problems I encountered, is the construction of global objects (see
below for details) and of course, executable
size. You have to add about 12k in size for an average PCL application
compared to the native PalmOS version.
Starting with beta 0.2.0, I removed the global objects, so PCL should
work without 'collect2', but global
constructors for your own objects won't be called.
If anybody is still interested, this is the documentation for the
preview release of the library.
Four control classes are implemented (
PList,
PField,
PScrollbar and
PButton) which represent almost all of
the pilot's controls.
I've added a very basic support for tables in this release, but
it will surely change and isn't yet documented.
The library is growing and the full release should be out soon. If anybody
want's to help implementing PControl classes,
feel free to do so. I'd be happy if you'd
send me your results so I could include
them in future versions.
Please see the installation instructions
for details on how to use the class library.
So, a good point to start reading is at PApplication. If you want your application to do
something useful, read PFormHandler.
Look at the included samples and
have your PalmOS API documention ready. Please bear
with me, this is the first release of the documentation. For any
hints and suggestions email me.
BTW: The library is definitely only usable on PalmPilots
(PalmOS 2) devices, as I use the new controls and floating point
routines. But the main reason are the new string utility routines
(StrPrintF, StrVPrintF, StrNCompare, ...), which make life a lot easier
and code a lot smaller.
There are two versions of the library: libPilotCL.a
and
libPilotCLE.a
. The second one enables you to use exception
handling with g++. To use the second one add -fhandle-exceptions
to your compiler switches and #define HANDLE_EXCEPTIONS
before including any PCL headers. But be warned!
Exception handling will triple the size of your executable, making
almost any program unlinkable. For exactly this reason it is hardly
tested!.
Note: The beta version of the library does not
contain the exception version. But, as I said, it is hardly usable
anyway.
Some restrictions:
- The resource ids 9900 - 9999 are reserved for PCL use.
- If you want to use scrollbars, you have to use a resource compiler,
that supports them (see PScrollbar).
Wes Cherry has released pilrc 1.8, which supports scrollbars, so check
his
PilRC page (Note:pilrc 1.7 contains a bug, which prevents
scrollbars from working) .
- When throwing exceptions, only a few types are passed through the
main event loop (see PExc for details).
- When using exception handling, every class that has instances in
a function that throws an exception must have a
destructor defined. Otherwise the compiler will fail. This is a g++
bug.
There are only a few conventions:
- The resource ids 9900 - 9999 are reserved for PCL use.
- All Library class name start with '
P
'
- Member functions begin with a lower case letter.
- Manipulation functions return a reference to the instance. This way
constructs like
listObj.add("Hello World").refresh();
are possible.
Global objects: 'collect2'
There is one major drawback:
If you wan't to use global constructors, the compiler must be
built with the USE_COLLECT2 option. I.e., you have to change the configure
script in the 'm68k-palmos-coff*)' section, add 'use_collect2=yes'
(under Linux also add 'gnu_ld=no') and
reconfigure/rebuild the compiler. This is needed because there are
several global objects that have to be initialized using the global
constructors. These only get called if 'collect2' prepares the code for
linking.
As I configured/built the GNU toolchain under OS/2 myself, this is no
problem for me, nor should it be a problem for all the Linux people
out there. I do not know the Win NT/95 distribution, so I don't know
if it uses 'collect2'.