TealMaster PalmOS 5 Developer Guidelines
(c)2002 TealPoint Software
All Rights Reserved

This document is meant to help developers create or modify hacks
which run under PalmOS 5 / ARM devices using the emulation
features in TealMaster 2.0 or higher.

BACKGROUND

In the original Hackmaster and pre-5 versions of PalmOS, hacks patch themselves
into PalmOS via system functions SysSetTrapAddress() and SysGetTrapAddress().
Hacks are hooked into any system function as a chain of programs, each with
the responsibility of calling the next one in the chain.  The last app in
each chain was always the original system function, which might or might not
get called depending on the functionality of the hacks preceding it.

PALMOS 5

In PalmOS 5, PalmOS engineers could not figure out how to implement the
old-style trap functionality properly, so they replaced it with a new
notification mechanism where apps registered themselves with the OS
directly to be called upon certain user or system events.  While by no
means as flexible or powerful as the old mechanism (which allowed any
system function to be patched), the new system provides equivalent
functionality needed by many existing hacks.

TEALMASTER 2

In TealMaster version 2, we added a new hack "emulation" feature which
uses the new notification mechanism to emulate the old style chain of 
linked system traps for system functions for which there is an
equivalent notification.  Many commonly used functions are supported,
but many are simply not yet possible under PalmOS 5.  In general, most
hacks which used the old mechanism mainly to detect user taps, strokes,
and other interaction can work under emulation.

This guide describes the functions emulated along with differences in
behavior between real and emulated behavior.  Note that in order to
work, hacks must of course be otherwise PalmOS-5 friendly, including
no references to private system structures and support for new high-
resolution hardware.


FUNCTIONS LIST
-----------------------------------------------------------------------

EvtGetEvent()
SysHandleEvent()

These two event-handling functions are hooked up to the PalmOS 5
sysNotifyEventDequeuedEvent notification.  When an event is
dequeued, TealMaster does necessary endian swaps on the incoming data and
passes it down the hack chain.  Afterwards, the structure is un-swapped
in case events were modified by any hacks in the chain.  For
SysHandleEvent() traps, a stub function is hooked up to the end of the
chain.  If the stub is not called at the end, TealMaster returns an error
from the notification to cancel the incoming event to simulate the broken
event chain.

As both functions are hooked up to the same notification, hacks patching 
SysHandleEvent() will receive notifications for some events 
(like hardware button presses) which would might normally be
filtered out by application pre-system event-handling code.

-----------------------------------------------------------------------

Find()

The Find() emulation is simple, and only meant to handle hacks like
TealMagnify, which trap this event to detect a tap on the "find"
silkscreen button.  The sysNotifyEventDequeuedEvent notification is 
used.  When a virtual key down event occurs corresponding to a press
of the find button, the hack chain is called.  A stub function detects
if the original find function is called at the end of the chain, and
cancels the notification if the stub does not called.

-----------------------------------------------------------------------

SysUIAppSwitch()

Hacks patching this function are called when the notification
sysNotifyAppLaunchingEvent is called.  The notification always
succeeds, so app-switching cannot be cancelled by traping this
function under emulation.

-----------------------------------------------------------------------

EvtProcessSoftKeyStroke()

Hacks patching this function are called when the notification
sysNotifyProcessPenStrokeEvent is called.  Zero is returned up
the hack chain from an end stub function if the start and end
of the stroke are in the same silkscreen button.

-----------------------------------------------------------------------

SysKeyboardDialog()
 
Hacks patching this function are called when the notification
sysNotifyKeyboardDialogEvent is called.  A stub function detects
if the original find function is called at the end of the chain, and
cancels the notification if the end of the chain is never reached.

-----------------------------------------------------------------------

SysSleep()

This function does not have an exact equivalent under PalmOS 5.  While
the old mechanism allows hacks to place code both before sleeping and
after waking in the same hack, the new mechanism provides separate
notifications (sysNotifySleepNotifyEvent and sysNotifyLateWakeupEvent)
for each event.

Thus, the user must choose to map SysSleep calls to one notification
or the other, depending on whether the hack is primarily interested
in running before the unit sleeps, or after it wakes up.  For both
types of hacks, it will appear to sleep for no time at all, as actual
sleeping will occur either before the hack has been called, or after
it as returned.  Thus, hacks which detect the elapsed sleep time will
not accurately be able to detect the sleep time under emulation.

-----------------------------------------------------------------------

###