Apt Userguide

By Lee Wilmot AKA Pent
Version RC4 9/4/2008

Contents


Install / Remove

Important: do not try to run Apt from a removable memory card.

First Install

To install the application, you need to install the file Apt.prc. If you get an error message from Apt, then you also need to install
AptAssist.prc, a Desk Accessory which Apt uses to provide some functionalliy. You may also find it useful to install one or more of the files in the thirdparty/ directory at some point (these files are mentioned later).

Removal

In Apt, select Menu->Apt->Remove.

New Version Install

Up to and including version 1.0, you should remove Apt completely as described above, before reinstalling (all settings will be lost).

Post version 1.0, you can:

Using this procedure, all settings will be retained.

Important Terms

Getting Started

  1. Run Apt and enable it by selecting Menu->Apt->Enable
  2. Decide which prefs you want to be affected for *all* apps, enable them with the rectangular buttons on the left, then set their values with the controls that will appear.
  3. Select an app with the app pulldown to the right of the title bar.
  4. Decide which prefs you want to be *different* from the *Defaults*, press the enable buttons for those then set their values.
  5. Sit back and relax. When you run the target app, just after it launches Apt will set the desired prefs
  6. Try setting up a button trigger here
  7. Try setting up a graffiti trigger here
  8. Wonder what all that other stuff is for, then decide to read the rest of the manual.

Screens

An Apt profile is divided over 5 screens, which are described later. However, there are some controls present on all the screens. On the left, you see the Prefs tab is selected, and a target app is being chosen.

Note that the Contacts app is written in bold, meaning there are some preferences set for that app.

To enable 5-way navigation support, press left, right or centre on the navigator pad. Once enabled it will remain until you exit Apt.

Prefs Screen

This screen allows setting of 'environmental' prefs like brightness and sound levels. These settings are applied when the target launches.

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.

Trigger Screens

About Triggers

The rightmost three screen tabs (at the top) take you to screens for defining triggers and actions. A trigger is any event that can cause Apt to do something. An action is the thing it does when the trigger occurs.

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).

Trying Out Button Triggers

Click on the buttons tab, and you'll see a single trigger is assigned to hard button 4. The '2' indicates that the button must be held down for two seconds to match the trigger. On the right of the blue line are the action category ('Apt') and the action ('Menu'). This tells us that when hard button 4 is held down for 2 seconds, the Apt menu will be displayed. Try exiting app (make sure it's enabled on the settings screen first), then hold the button till the menu appears.
Now add a trigger of your own. Select 'Hrd 4' with the left most pulldown menu. The default number of presses is '0', which means that you press and release the button to match the trigger. Notice the default action is 'App' , which means to launch an app. Try picking a different app to launch.
Finally, use the target selector in the top right to pick a different target (Applications in the screenshot). And assign another trigger to hard 4. Press the left most button to increase the repeat count to one, meaning the trigger activates when hard 4 is held for 1 second. Assign Calc to that trigger.

Now go and test the assignments you've made. You should find the following behaviour:

In AppEventResult
AnyHard 4 press and releaseContacts launches
Applications onlyHard 4 press and hold 1 secondCalc launches
AnyHard 4 press and hold 2 secondApt menu appears

Trying Out A Tap Trigger

Select the 'Calc' app with the target selector on the top right. Tap the 'Graffiti' tab. Select the 'Tap' trigger with the pulldown on the left, and the 'Applications' app with the pulldown on the the right. Your screen should look like this one. The ? means the tap coordinates are undefined. Let's go to the Calc app and define them.
In the calc app, press Hard 4 and hold it for 2 seconds. This will bring up the Apt menu (left). Press hard 3 (or tap on 'Get Tap') and then tap on the number 6. You've now defined a tap coordinate. Check that: press and hold hard 4 again and select 'S. Graffiti'. Your tap point should be shown. If you tap on the number 6 in the calculator it will now take you back to the applications launcher. Congratulations :-)
Now here comes the nitty gritty....

Layout

Each row in the screen pairs events and actions. The second column indicates the triggering event while the first column is the trigger argument which modifies how the trigger is interpreted.

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).

Trigger Evaluation

Here's how trigger/action evaluation takes place:

Trigger Arguments

Some triggers have arguments. For those, not only the trigger must match the event, but also the argument: In all cases, tap on the trigger arguments button (1st column) to change the argument.

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.

Macros And Menus

Trigger/argument pairings must be unique. Apt will prevent you repeating them. If you wish to have several actions associated with a pairing, you must use one of the special triggers which are the first three trigger items in the list: You can have as many actions assigned to a trigger as permitted by the screen size, but you can't mix them. The coloured lines down the centre of the screen alternate colours to emphasize action groups.

Buttons Screen

This screen allows actions to be triggered based on pressing of the hardware buttons and some of the on-screen soft buttons. The 0/Centre configuration on the left leads to the star menu on the right when the centre navigator button is pressed in the Calc application.

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.

Events Screen

Events are 'things which happen' on your palm, not necessarily triggered directly by yourself.

Supplementary Action Info

This is not a complete reference. Only actions needing some explanation are mentioned. The actions are preceded by their category and a colon, and a possible argument is given in brackets.

Menu Items

Command Bar

Apt adds two icons to the command bar of all other apps when it is enabled in the Prefs+ screen. Apt Apply has the same icon as Paste, and Apt Save has the same icon as Copy. This will change eventually.

Apt Settings Form

These are settings which affect how Apt itself behaves. You can access this form via Menu->Apt->Settings on the main form.

To enable 5-way navigation support, press left, right or centre on the navigator pad. Once enabled it will remain until you exit Apt.

Resource IDs

Often you will want to manipulate a control and need to find the resource ID with which PalmOS identifies it.

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).

Memory Card Support

Apt supports applications on external memory cards. This is sometimes called VFS support, where VFS stands for Virtual File System.

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:

Apt only looks in the directory PALM/Launcher on each external memory card.

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).

Random Notes

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.