|
|
|
|
16
Progress ManagerProgress.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.
Boolean PrgHandleEvent (ProgressPtr prgP, EventType *eventP)
-> |
Pointer to a progress structure created by |
true if the system handled the event. If it returns false, you should check if the user canceled the dialog by calling PrgHandleEvent internally calls SysHandleEvent as needed.
appStopEvent events.
textCallback function you specified in your call to 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."
ProgressPtr PrgStartDialog (Char *title, PrgCallbackFunc textCallback, void *userDataP)
-> |
Pointer to a title for the progress dialog. Must be a NULL-terminated string that is no longer than progressMaxTitle (20). |
-> |
Pointer to a callback function that supplies the text and icons for the current progress state. See |
-> |
A pointer to data that you need to access in the callback function. This address gets passed directly to your function. |
NULL is returned if the system is unable to allocate the progress structure.
textCallback function to get the initial text and icon data for the progress dialog.
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.
PrgStartDialog has the prototype shown for ProgressPtr PrgStartDialogV31 (Char *title, PrgCallbackFunc textCallback)
-> |
Pointer to a title for the progress dialog. Must be a NULL-terminated string that is no longer than progressMaxTitle (20). |
-> |
Pointer to a callback function that supplies the text and icons for the current progress state. See |
NULL is returned if the system is unable to allocate the progress structure.
void PrgStopDialog (ProgressPtr prgP, Boolean force)
-> |
Pointer to a progress structure created by |
-> |
true removes the progress dialog immediately, false causes the system to wait until the user confirms an error, if one is displayed. |
true for the force parameter, this causes the system to remove the dialog immediately.
void PrgUpdateDialog (ProgressPtr prgP, UInt16 err, UInt16 stage, Char *messageP, Boolean updateNow)
-> |
Pointer to a progress structure created by |
-> |
If non-zero, causes the dialog to go into error mode, to display an error message with only an OK button. |
-> |
Current stage of progress. The callback function can use this to determine the correct string to display in the updated dialog. |
-> |
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. |
-> |
If true, the dialog is immediately updated. Otherwise, the dialog is updated on the next call to |
true if the user cancelled the process via the progress dialog.
PrgUserCancel (prgP)
cancel field in the progress structure (as a UInt16).
Boolean (*PrgCallbackFunc) (PrgCallbackDataPtr cbP)
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.)
PrgCallbackData structure. Here are the important fields in that data structure (note that -> indicates you set the field in the textCallback function):
<- |
Current stage (passed from PrgUpdateDialog). |
<- |
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. |
<- |
Additional text to display in the dialog (from the messageP parameter to PrgUpdateDialog). This should be no longer than progressMaxMessage (128). |
<- |
Current error (passed from the err parameter to PrgUpdateDialog). |
-> |
Resource ID of the bitmap to display in the progress dialog, if any. |
<- |
true if user has pressed the cancel button. |
-> |
If true, then update text (defaults to true). You can set this to false to avoid an update to the text. |
<- |
true if update caused by a timeout. |
-> |
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. |
<- |
A pointer to any application-defined data that the function needs to access. You specify this pointer as a parameter to |
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.
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.
messageP parameter to PrgUpdateDialog.
NOTE: This function is called only if the parameters passed toPrgUpdateDialoghave changed from the last time it was called. IfPrgUpdateDialogis called twice with exactly the same parameters, thetextCallbackfunction is called only once.
|
|
|
|