This chapter provides reference material for the Progress Manager.
Progress Manager Functions
Application-Defined Functions
The header file Progress.h declares the API that this chapter describes. For more information on the progress manager, see the section "Progress Dialogs" in the Palm OS Programmer's Companion, vol. I.
Progress Manager Functions

PrgHandleEvent

Purpose
Handles events related to the active progress dialog.
Prototype
Boolean PrgHandleEvent (ProgressPtr prgGP, EventType *eventP)
Parameters
-> eventP | Pointer to an event. You can pass a NULL event to cause this function to immediately call your PrgCallbackFunc function and then update the dialog (for example, after you call PrgUpdateDialog). |
Result
Returns true if the system handled the event. If it returns false, you should check if the user canceled the dialog by calling PrgUserCancel.
Comments
Use this function instead of SysHandleEvent when you have a progress dialog. PrgHandleEvent internally calls SysHandleEvent as needed.
Note that the auto power-off feature of the system is automatically disabled when you use this function, unless the dialog is just displaying an error. This function also prevents appStopEvent events.
If an update to the dialog is pending (from a call to PrgUpdateDialog, for example) this function handles that event and causes the dialog to be updated. As part of this process, the textCallback function you specified in your call to PrgStartDialog is called. Your textCallback function should set the textP buffer in the PrgCallbackData structure with the new message to be displayed in the progress dialog. Optionally, you can also set the bitmapId field to include an icon in the update dialog. For more information about the textCallback function, see the section "Application-Defined Functions."
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
PrgStartDialog, PrgStopDialog, PrgUpdateDialog, PrgUserCancel
PrgStartDialog

Purpose
Displays a progress dialog that can be updated.
Prototype
ProgressPtr PrgStartDialog (const Char *title, PrgCallbackFunc textCallback, void *userDataP)
Parameters
-> title | Pointer to a title for the progress dialog. Must be a NULL-terminated string that is no longer than progressMaxTitle (20). |
-> textCallback | Pointer to a callback function that supplies the text and icons for the current progress state. See PrgCallbackFunc. |
-> userDataP | A pointer to data that you need to access in the callback function. This address gets passed directly to your function. |
Result
A pointer to a progress structure. This pointer must be passed to other progress manager functions and must be released by calling PrgStopDialog. NULL is returned if the system is unable to allocate the progress structure.
Comments
The dialog created by this function can be updated by another process via the PrgUpdateDialog function. The dialog can contain a Cancel or OK button. The initial dialog defaults to stage 0 and calls the textCallback function to get the initial text and icon data for the progress dialog.
This function saves the screen bits behind the progress dialog, and these are restored when you call PrgStopDialog. Because of this, you should minimize changes to the screen while the progress dialog is displayed, otherwise, the restored bits may not match with what is currently being displayed.
Compatibility
This version of the function is available only if 3.2 New Feature Set is present. On earlier systems, PrgStartDialog has the prototype shown for PrgStartDialogV31.
See Also
PrgHandleEvent, PrgStopDialog, PrgUpdateDialog, PrgUserCancel
PrgStartDialogV31

Purpose
Displays a progress dialog that can be updated.
Prototype
ProgressPtr PrgStartDialogV31 (const Char *title, PrgCallbackFunc textCallback)
Parameters
-> title | Pointer to a title for the progress dialog. Must be a NULL-terminated string that is no longer than progressMaxTitle (20). |
-> textCallback | Pointer to a callback function that supplies the text and icons for the current progress state. See PrgCallbackFunc. |
Result
A pointer to a progress structure. This pointer must be passed to other progress manager functions and must be released by calling PrgStopDialog. NULL is returned if the system is unable to allocate the progress structure.
Compatibility
This function corresponds to version of PrgStartDialog available on Palm OS® 3.0 and Palm OS 3.1.
See Also
PrgHandleEvent, PrgStopDialog, PrgUpdateDialog, PrgUserCancel
PrgStopDialog

Purpose
Releases memory used by the progress dialog and restores the screen to its initial state.
Prototype
void PrgStopDialog (ProgressPtr prgP, Boolean force)
Parameters
-> force | true removes the progress dialog immediately, false causes the system to wait until the user confirms an error, if one is displayed. |
Result
Returns nothing.
Comments
If the progress dialog is in a state where it is displaying an error message to the user, this function normally waits for the user to confirm the dialog before it removes the dialog. If you specify true for the force parameter, this causes the system to remove the dialog immediately.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
PrgHandleEvent, PrgStartDialog, PrgUpdateDialog, PrgUserCancel
PrgUpdateDialog

Purpose
Updates the status of the current progress dialog.
Prototype
void PrgUpdateDialog (ProgressPtr prgGP, UInt16 err, UInt16 stage, const Char *messageP, Boolean updateNow)
Parameters
-> err | If non-zero, causes the dialog to go into error mode, to display an error message with only an OK button. |
-> stage | Current stage of progress. The callback function can use this to determine the correct string to display in the updated dialog. |
-> messageP | Extra text that may be useful in displaying the progress for this stage. Used by the callback function, which can append it to the base message that is based on the stage. |
-> updateNow | If true, the dialog is immediately updated. Otherwise, the dialog is updated on the next call to PrgHandleEvent. |
Result
Returns nothing.
Comments
For more information about how the parameters are used and the callback function, see the section "Application-Defined Functions."
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
PrgHandleEvent, PrgStartDialog, PrgStopDialog, PrgUserCancel
PrgUserCancel

Purpose
Macro that returns true if the user cancelled the process via the progress dialog.
Prototype
PrgUserCancel (prgP)
Parameters
-> prgP | Pointer to a progress structure (ProgressPtr) created by PrgStartDialog. |
Result
Returns the value of the cancel field in the progress structure (as a UInt16).
Comments
This is a macro you can use to check if the user cancelled the process. If the user did cancel, you can change the progress dialog text to something like "Cancelling," or "Disconnecting," or whatever is appropriate for your application. Then you should cancel the process, end the communication session, or do whatever processing is necessary.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
PrgHandleEvent, PrgStartDialog, PrgStopDialog, PrgUpdateDialog
Application-Defined Functions

PrgCallbackFunc

Purpose
Supplies the text and icons for the current progress state.
Prototype
Boolean (*PrgCallbackFunc) (PrgCallbackDataPtr cbP)
Parameters
<-> cbP | A pointer to a PrgCallbackData structure. See below. |
Result
Returns true if the progress dialog should be updated using the values you specified in the PrgCallbackData structure. If you specify false, the dialog is still updated, but with default status messages. (Returning false is not recommended.)
Comments
This is a callback function that you specify when you call PrgStartDialog. The callback function is called by PrgHandleEvent when it needs current progress information to display in the progress dialog.
The system passes this function one parameter, a pointer to a PrgCallbackData structure. Here are the important fields in that data structure (note that -> indicates you set the field in the textCallback function):
<- UInt16 stage | Current stage (passed from PrgUpdateDialog). |
<-> Char *textP | Buffer to hold the text to display in the updated dialog. You might want to look up a message in a resource file, based on the value in the stage field. Also, you should append the additional text in the message field, to form the full string to display. Be sure to include a null terminator at the end of the string you return, and don't exceed the length in textLen. |
<- UInt16 textLen | Maximum length of the text buffer textP. Note that this value is set for you by the caller. Be careful not to exceed this length in textP. |
<- Char *message | Additional text to display in the dialog (from the messageP parameter to PrgUpdateDialog). This should be no longer than progressMaxMessage (128). |
<- Err error | Current error (passed from the err parameter to PrgUpdateDialog). |
-> UInt16 bitmapId | Resource ID of the bitmap to display in the progress dialog, if any. |
<- UInt16 canceled:1 | true if user has pressed the cancel button. |
<- UInt16 showDetails:1 | true if user pressed the down arrow button on the PalmTM device for more details. (Because this is a non-standard user interface technique, you shouldn't use this feature to display details that users need under normal conditions. It's more for debugging purposes.) |
-> UInt16 textChanged:1 | If true, then update text (defaults to true). You can set this to false to avoid an update to the text. |
<- UInt16 timedOut:1 | true if update caused by a timeout. |
<-> UInt32 timeout | Timeout in ticks to force next update. After this number of ticks, an update is automatically triggered (which sets the timedOut flag). You can use this feature to do a simple animation effect. Note that you must set the timeout for EvtGetEvent to a value that is equal to or less than this value, otherwise you won't get update events as frequently as you expect. |
-> UInt16 delay:1 | If true, delay for one second after updating the dialog. Use this value when you are displaying the final progress message so that users have a chance to see the message before the dialog closes. This field is available only if 3.2 New Feature Set is present. |
<- void *userDataP | A pointer to any application-defined data that the function needs to access. You specify this pointer as a parameter to PrgStartDialog if the callback function needs to access some application data but does not have access to application globals. This field is available only if 3.2 New Feature Set is present. |
In this function, you should set the value of the textP buffer to the string you want to display in the progress dialog when it is updated. You can use the value in the stage field to look up a message in a string resource. You also might want to append the text in the message field to your base string. Typically, the message field would contain more dynamic information that depends on a user selection, such as a phone number, device name, or network identifier, etc.
For example, the PrgUpdateDialog function might have been called with a stage of 1 and a messageP parameter value of a phone number string, "555-1212". Based on the stage, you might find the string "Dialing" in a string resource, and append the phone number, to form the final text "Dialing 555-1212" that you place in the text buffer textP.
Keeping the static strings corresponding to various stages in a resource makes it easier to localize your application. More dynamic information can be passed in via the messageP parameter to PrgUpdateDialog.
NOTE: This function is called only if the parameters passed to PrgUpdateDialog have changed from the last time it was called. If PrgUpdateDialog is called twice with exactly the same parameters, the textCallback function is called only once.
|