Post version 1.0, you can:
Note that the Contacts app is written in bold, meaning there are some preferences
set for that app.
The labels at the left are buttons to enable or disable particular pref settings. If a target has no setting enabled for a particular pref, then the *Default* settings are examined. If the *Default* also has no setting enabled for the pref, then Apt will not change the prevailing setting when the target launches. Hope you got that!
In the screenshot to the left, when the Contacs app is entered, Apt will set
the auto off time and brightness, the DIA area and status bar will be
closed, graffiti anywhere with ink will be enabled, and IR beaming
will be turned off (if it isn't already).
Be aware that if the *Default* setting for a particular
pref is disabled, then when you leave the app the setting will stay as
it was set in the target app, unless the next app that runs has that
setting enabled.
The numbers at the right indicate the numerical equivalents of the slider positions.
As an aside, note that changes to the *Default* app auto-off, volume or brightness levels take place immediately even if Apt is not enabled.
Oh, and an auto off time of 0 means never turn off (be careful with this).
Finally, for some devices some settings will not work. For instance, rotate may only work on a long-screen device, system sound seems to have trouble taking effect on one or more treo models.
Really finally, if you are having trouble setting the auto-off and brightness sliders with enough precision, you can use nav left/right to increase or decrease by one (when the slider has focus).
Lastly, if you find your DIA jumping up and down all the time, it's probably
because you havn't set it manually to your preferred setting (PalmOS
remembers the last manually set position and tries to restore it a lot).
Just use the status bar trigger one time to set it and things should calm
down.
Prefs+ Screen
This screen has some miscellaneous preferences.
Apt can be used to restrict access to particular applications. If one or more lock triggers
(max 3) are specified in the Prefs+ screen, then access will be denied unless the user can
replicate the sequence of triggers specified here (more information on 'triggers' later).
Some triggers are unsuitable for use as lock triggers, you will be informed when an invalid
trigger is selected. Strokes/taps do not function as lock triggers when it's not a full-screen lock (see below).
An interesting one is using a named memory card insertion to unlock an app
In the screenshot, Hard 3 button must be pressed and the screen tapped in a particular
place to gain access to the Calc app (keep those calculations secret, OK ?)
The lock triggers in the *Default* app have two purposes. Firstly, they are used to
lock Apt itself (if set of course). Secondly, they are used to make a lock whenever a
Lock action is executed (see below).
By default, a lock is applied after the target has run, and the lock window is
small so the target app can be seen in the background. When Full Screen is
selected, the lock window appears before the target runs and the screen is blanked.
Small note: with full-screen locking, -Lnch, +Lnch and Exit triggers (see later)
are never triggered if the lock check fails. With the small lock window they are.
whether to show the relevant menu command bar icons. If these are
enabled in *Defaults* or the target app, they will appear. The initial values for
these checkboxes in new target preferences follow those of *Default*.
if not checked, then visits to the target app will be ignored for the purposes of the Back and Rcnt actions (see Actions help item)
This control does not work for the *Default* app.
usually, the rotation, DIA and status bar settings from the Prefs screen (leftmost one)
are applied once an application has finished loading, setting
up the screen etc, otherwise the Apt preferences may get undone as the app loads.
For some apps, applying them before the app starts up may result in less flicker and 'jumping around'.
These checkboxes allow you to define lists of your favourite apps. Each checkbox includes the
current target app in one of 4 lists. You can then assign one of the actions Fill:Fav1-4 to e.g.
a button to show the apps with the corresponding checkbox checked. In the screenshot,
Contacts will be included whenever Favourites list 1 or 2 is shown,
If not checked in either *Default* or the target, when an external memory card is inserted
PalmOS is blocked from it's usual action of switching to Applications and showing apps
in PALM/Launcher.
sometimes you change your device and choose a new hotsync name. This option will allow you to keep using registered
software that uses your Hotsync name as a key. If the field is empty, the hotsync name is not changed.
The hotsync name is always applied Pre-Launch and the old one is restored automatically when the
application exits, you do not need to specify a 'Default'.
if you have installed the DB file from the Khroma distribution (KhromaDB.pdb, can also
be found in the thirdparties/ directory) you will
find here a list of available colour themes to apply. Unlike most other Apt preferences, the
colour theme is removed by the system when the target exits, so you do not need to set
a colour theme in *Default* if you don't wish to.
Whether to keep the app hidden (by setting the 'hide' attribute on the file). '-' means
Apt will not do anything with the attribute. When 'Keep Visible' is set, Apt will make
sure the target is visible, even when another app tries to make it hidden (and vice
versa for 'Keep Hidden').
This control does not work for the *Default* app.
Same as the 'Hiding' selector, but affects whether the 'backup' attribute on the file
is set i.e. whether it is backed up in a Hotsync.
This control does not work for the *Default* app.
The screens and actions executed behave identically, but the available triggers are dependent on the screen.
It's recommended that you experiment with the Buttons screen triggers before trying out the Graffiti and Events triggers, because you can easily test the button assignments.
Warning: Apt provides around 50 unique triggers and 100 actions. Some combinations will not work, or not work as expected. However, don't be afraid to experiment! No combination of triggers/actions should cause a crash (barring unknown bugs in the software).
Now go and test the assignments you've made. You should find the
following behaviour:
In App Event Result Any Hard 4 press and release Contacts launches Applications only Hard 4 press and hold 1 second Calc launches Any Hard 4 press and hold 2 second Apt menu appears
The third column is the action category. There are many actions which can be performed, hence the need to break them into categories.
The fourth column is the action within the category.
The last column is the action argument which modifies how the action is executed. Some action categories only have a single member, and then there is no action argument.
A coloured line down the centre separates triggers from actions and groups actions together (more later).
When changing strokes or taps, other strokes and taps which apply to the current target are displayed. Taps are show in blue. Relative strokes are shown in red. Fixed strokes are show in green.
For some triggers (the ones not completely displayable in the button), you can press on the trigger argument button, drag the pen out of the button, then release, to see the trigger argument displayed. This is most useful for the tap and stroke arguments.
Note that not all buttons are present on all devices. Just ignore the ones you don't have. In particular, VolUp, VolDown, Side and Option Hard 1-4 (oHrd1-4 in Apt) buttons are probably only available on Treos.
The 'Powr' button trigger only activates when you turn the device off.
To do things when the power is turned on, use the Events:Wake trigger.
Graffiti Screen
The taps and strokes on the left lead to the screen area definitions
on the right. It can be seen that the begin point of a stroke has a
small box and is labelled with the first associated action.
(leftmost image header is out of date, sorry about that).
In the shot on the left (not related to the previous configuration) you can see the strokes and taps
which are active in the target app. The 'grayed out' red stroke is a stroke defined
in the *Default* configuration (and thus active in all apps). You can see this view with
the Apt:Menu action.
A 'ronamatic' stroke from bottom-centre of the screen to top-centre.
A single tap somewhere on the screen. You can define the tap position in
as many as three different ways!
When you are actually using the trigger, the tap does not have to be on the
exact same pixel that you defined. The range within it must be is specified
in the
trigger argument section for more info on defining points.
Warning: tap points will obscure controls which are at the same place
Although this can of course be useful sometimes, usually you will want to find
an area in the target app without any controls.
A drag of the pen from one specific point on the screen to another. The start and
end points can be defined as for the Tap above.
When the pen goes down inside the start point of a stroke, controls underneath
the stroke will not see it. However, if the pen goes up outside of the
defined end point then Apt will resend the original pen up and pen down events.
In other words, controls underneath should not be affected by fixed Apt strokes, but
it remains to be seen :-)
Tip: to cancel a stroke (return it to undefined), you can just tap twice on the screen
during recording.
A drag of the pen from one point on the screen to another, a specific direction
and distance away. The direction and distance can be defined as for the Stroke above.
In the screenshot, the red strokes show that the brightness can be increased/decreased
by making a side stroke right/left anywhere on the screen. Of necessity, relative strokes
are more likely to affect underlying screen elements so it might be preferable to use fixed
ones where possible.
Note: relative strokes will not be registered if they start in the silkscreen/DIA area. They
may, however, end there.
Tip: to cancel a relative stroke (return it to undefined), you can just tap twice on the screen
during recording.
Graffiti characters a-z. Does not trigger if a field has focus. * arg matches any lowercase letter.
Digit 0-9. Does not trigger if a field has focus. * arg matches any digit.
Backspace character. Does not trigger if a field has focus.
Space character. Does not trigger if a field has focus.
Full-stop character. Does not trigger if a field has focus. Useful as a double-tap
on the graffiti area to do something.
$ character. Does not trigger if a field has focus. No, it's unknown
why this one was put in, perhaps a money fetish ?
Events Screen
Events are 'things which happen' on your palm, not necessarily triggered
directly by yourself.
Triggers before the target is launched. Note that there are no controls on the screen at
this point.
Triggers after the target has launched, and is waiting for input. Important: do
not use this trigger to go to another app, do something and come back, otherwise
you'll hit an infinite loop. Use -Launch for that purpose.
Triggers when the target is about to exit. There are still controls on the screen
when this trigger executes.
When you leave an app via an Apt launch (e.g. from a button trigger) ,
if there is an Exit trigger defined the macro will end at the first launch action
and the Exit macro begin. However, after the Exit macro the launch action
will take place to take you wherever you wanted to go.
Triggers when the form with the ID x is about to open (it hasn't been
drawn yet...). If x is 0 any form opening is matched.
actions to be performed when the device has finished a soft reset. Currently this
trigger is only respected for the *Default* target.
Triggers when there has been no pen/button input for the specified number
of seconds.
Triggers once as above then stops. When input is received after it has triggers,
the timer is reset and it can trigger again.
Triggers again and again after the specified idle time. In the screenshot above,
every 8 seconds the screen brightness is reduced by 20.
When some input is received after the device has been idle for the specified
number of seconds. Warning: do not perform any complicated actions here
if you also have an Apt trigger associated with the input event (e.g. a keypress).
If you are using in association with Idle actions, to restore something, it's recommended
you put the Input time at least 1 second less than on the Idle trigger.
Triggers when an expansion card has been inserted in the device with
the specified name. A blank name matches all names. In the example
above, aeroplayer is launched when the card labelled 'music' is inserted,
when any other card is inserted FileZ is launched.
Triggers when any expansion card has been removed from the device.
The device has just woken up (powered on). Note, that this may not be due to
someone pressing the power button. For instance, you may have alarms scheduled
to do something in the middle of the night.
The command bar is about to come up
The command bar has just disappeared
The DIA just opened
The DIA just closed
The control with resource ID x has just been selected (or pressed, dependent on the control).
Actions will take place before the control's normal action (but some actions e.g. app launches
will take place after).
The menu item with resource ID x has just been selected.
Actions will take place before the menu item's normal action (but some actions e.g. app launches
will take place after).
To enable 5-way navigation support, press left, right or centre on the navigator pad.
Once enabled it will remain until you exit Apt.
To find out the resource IDs of buttons you are interested in, you can use the ListCtrl action (from the AptMenu) while in the target or try running the DA (included in the thirdparty/ directory) GetCoords.prc (also possible via AptMenu) and then tap on the control. Thanks to Alexander Pruss for writing GetCoords.prc.
Alternatively, if you leave the resource ID as zero then Apt will use the object with focus, if it's a ctrl, otherwise the first control of the right type it finds in the form.
If you have trouble finding the resource ID of a control (some applications do not use the normal palm system) you could also try a simulated pen tap (Pen:Tap) action at the coordinates of the button. Use Apt:GetPoint to get the coordinates and Menu->Edit->PastePoint to paste it into the coordinates field.
As a final option to activate a control, you could look in the applications menu
to see if there is a menu item that has the same effect as the control, and activate
that instead (use Apt:ListMenu from the AptMenu).
To enable VFS support, you need to set the checkbox in the Settings form. However, that will only
be possible if your device actually supports external memory cards.
When enabled:
DAs and Panels on an external memory card cannot be launched.
The number of apps which can be included from external memory cards is dependent on the
lengths of their names. Two or three hundred should be OK, though Apt's loading may
be much slower and some other operations while Apt's UI is not loaded may also be slower
(untested).
Memory Card Support
Apt supports applications on external memory cards. This is sometimes called VFS support, where
VFS stands for Virtual File System.
Apt only looks in the directory PALM/Launcher on each external memory card.
Note that when the app runs, it may create several database files in the internal device memory.
These are not deleted by Apt.
Random Notes
If you disable a button in Apt, it will not interfere with other programs using the same button.
Configuration Examples
User-maintained configuration examples can be found online at wikidot.
Known Bugs/Limitations
ToDo List Items
These are items that are under consideration (not bugs needing fixing).
Most of them will not be done unless there's a reasonable amount of interest in Apt.
('multi' is my term for macros, popup lists or star menus).
a separate form allowing definition of a named set of actions which can then
be referred to by a 'multi' action. This would allow nested multis
and actioning the same multi in several places without needing to redefine it.
Would also be nicer to show a multi name rather than just the first action when
press-n-holding.