Palm OS Programming - Advanced UI Elements

This is the text, extracted from a presentation for Palm OS Programming Advanced UI elements. The gotchyas and pitfalls were skipped because I already had that in a separate page. I don't use Adobe and I wanted a textual reference instead of printing out slides, so I did this.

Anatomy of the Stock Event Loop

EventType event;
do {
    EvtGetEvent(&event, evtWaitForever);
    if (! SysHandleEvent(&event))
        if (! MenuHandleEvent(0, &event, &error))
            if (! AppHandleEvent(&event))
                FrmDispatchEvent(&event);
} while (event.eType != appStopEvent);

FrmDispatchEvent passes the event FIRST to the handler that was registered (usually by AppHandleEvent)
If the event wasn't handled (i.e. the handler returns false) it flows to FrmHandleEvent, where it receives default handling
- Keystrokes flow into fields
- FrmUpdateEvent calls FrmDrawForm()

Opaque UI Structures

Myth:
- UI structures are documented so you can edit their contents.
Reality:
- UI structures are documented to help debugging.

Usable and Visible

Myth:
- Applications can control which form objects draw by setting the "visible" bit.
Reality:
- The "visible" bit is actually state information, not something you should be setting.
- Use FrmShowObject() and FrmHideObject()

Clipboard

Myth:
- The clipboard is just for boring text.
Reality:
- You can put bitmaps on the clipboard, too!
```
  ClipboardAddItem(clipboardBitmap, bitmapP, MemPtrSize(bitmapP));
```
- Text and bitmap clipboards are separate; one doesn't overwrite the other

Custom Fonts

Myth:
- Custom fonts aren't supported.
Reality:
- Custom fonts ARE supported. We don't make it easy (yet)..

Creating a Custom Font

Fonts are NFNT resources (well, almost)
- Slight differences in header
- Glyphs contain space
No support in Constructor for creating fonts
But there are various third-party tools for creating and importing fonts
- xFont
- PilRC
- ResEdit (Macintosh)

Adding a Font to your Project (PC)

Use xFont (freeware) to make a font in PilRC format
- Call it something like "myFont.pfn"
- Or create font directly in PilRC format - See PilRC Manual for details
Install PilRC CodeWarrior plugin
Add a .rcp file to project with this line in it:
```
  Font 'FONT' FONTID 128 "myFont.pfn"
```
Compile and get a .r file containing a "NFNT" resource
- data 'NFNT' (20052) means Resource ID is 20052

Installing a Custom Font

MemHandle fontH;
FontType* fontP;
fontH = DmGetResource(fontResource, 25002);
fontP = (FontType*) MemHandleLock(fontH);
FntDefineFont(fntAppFontCustomBase, fontP);
MemHandleUnlock(fontH);
DmReleaseResource(fontH);

fntAppFontCustomBase is the first ID available
- add an offset when defining multiple fonts

Using a Custom Font

WinDrawChars will now use this font
- if you call FntSetFont(fntAppFontCustomBase)
LstGlueSetFont, FrmGlueSetLabelFont, CtlGlueSetFont, TblSetItemFont can then take fntAppFontCustomBase to set the list, form, control or table font to the new custom font

High Resolution Font Families

LowRes
NFNT 2000  ---->      Constructor
                          or             ---->   Family
  HiRes    ---->  tfnf resource defines         NFNT 4000
NFNT 3000          font family members

Use only on Palm OS 5 and later
- Not backwards compatible (check OS version!)
DmGetResource('nfnt', myFontFamilyID);
From there use same as "old style" custom font

Tables

Myth:
- Tables are Complicated
Reality:
- Tables are Very Complicated

Do You Really Need a Table?

Tables are ideal when:
- You need UI widgets embedded in a table
  - fields, checkboxes, or anything that accepts input
Consider alternatives when:
- You simply want to display data in a multi-column format
- You require scrolling
  - Tables have no inherent scrolling functionality!

Alternatives to Tables

Lists
- Can have multiple columns when drawn by callback
- Great when rows can select together
Fields + Scrollbar
- Great for text-only data
Gadgets
- Most flexible, most work
- Get a rectangle that receives hits
- Implement only the functionality you need

Attention Manager

Myth:
- The Attention Manager is a 4.0 replacement for the Alarm Manager.
Reality:
- The Attention Manager is a central UI repository for attention getting messages from all applications.

Step 1: Call the Attention Manager

Often in response to an Alarm or Notification
AttnGetAttention(cardNo, dbID, userData, NULL, kAttlLevelSubtle, kAttnFlagsUseUserSettings, 5, 2); // Handle the launch code sysAppLaunchCmdAttention
case sysAppLaunchCmdAttention: HandleAttention((AttnLaunchCodeArgsType*)cmdPBP);

Step 2: Draw the Attention UI

switch (cmdPBP->command)
    case kAttnCommandDrawList:
        // Draw the item in the list
    case kAttnCommandDrawDetail:
        // Draw the detail screen

/// Code to help you out
x = cmdPBP->commandArgsP->drawList.bounds.topLeft.x;
y = cmdPBP->commandArgsP->drawList.bounds.topLeft.y;
WinDrawBitmap(iconP, x, y);
x += kAttnListTextOffset;
WinDrawChars(theStr, StrLen(theStr), x, y);

Step 3: Extras

case kAttnCommandPlaySound
- Chance to play a custom sound
- Sent if requested in AttnGetAttention() call
case kAttnCommandCustomEffect
- Chance to do any other custom effect

Step 4: Handle User's Choice

case kAttnCommandGotIt:
    // Selected the OK button

case kAttnCommandSnooze:
    // Selected the Snooze button

case kAttnCommandGoThere:
    // Selected the Go To button
    AttnForgetIt(cardNo, dbID, cmdPBP->userData);
    buf = (UInt32*) MemPtrNew(sizeof(UInt32));
    MemPtrSetOwner(buf, 0);
    *buf = paramP->userData;

    SysUIAppSwitch(cardNo, dbID,
                   sysAppLaunchCmdCustomBase, buf);
    // Handle sysAppLaunchCmdCustomBase in PalmMain()

Step 5: Update the Attention Manager

AttnForgetIt -- when something in the attention manager is no longer relevant
AttnIterate -- Iterates through everything that belongs to your app and gives your callback a chance to handle each one
- Update all attentions
- Erase all attentions
AttnUpdate -- Update specific attention
AttnGetCounts -- Use to find out how many attentions you have pending