This chapter provides reference material for the Progress Manager.
Progress Manager Structures and Types
Progress Manager Constants
Progress Manager Events
Progress Manager Functions and Macros
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."
Progress Manager Structures and Types
PrgCallbackData Struct
Purpose
Structure used to share information between the Progress Manager and the PrgCallbackFunc()
callback function.
Declared In
Progress.h
Prototype
typedef struct { uint16_t stage; uint16_t bitmapId; DmOpenRef bitmapDatabase; uint32_t textLen; char *textP; char *message; status_t error; uint16_t canceled:1; uint16_t showDetails:1; uint16_t textChanged:1; uint16_t timedOut:1; uint16_t displaySkipBtn:1; uint16_t skipped:1; uint16_t spareBits1:10; uint16_t padding1; uint32_t timeout; uint32_t padding2; uint32_t barMaxValue; uint32_t barCurValue; char *barMessage; uint16_t barFlags; uint16_t delay:1; uint16_t spareBits2:15; void *userDataP; } PrgCallbackData, *PrgCallbackDataPtr
Fields
-
→ stage
- Current stage passed from
PrgUpdateDialog()
. -
↔ bitmapId
- Resource ID of the bitmap to display in the progress dialog, if any.
-
↔ bitmapDatabase
- Open database containing
bitmapId
. -
→ textLen
- Size in bytes of the text buffer
textP
. Note that this value is defined by the system, not by your callback function. Be careful not to exceed this length intextP
. -
↔ 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 themessage
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 intextLen
. -
→ message
- Additional text to display in the dialog (from the
messageP
parameter toPrgUpdateDialog()
). This string is no longer thanprogressMaxMessage
. -
↔ error
- Current error (passed from the
err
parameter toPrgUpdateDialog()
). -
↔ canceled
-
true
if user has pressed the Cancel button. -
→ showDetails
-
true
if user pressed the down arrow button on the 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.) -
← textChanged
- If
true
, then the system should update text (defaults totrue
). You can set this tofalse
to avoid an update to the text. -
→ timedOut
-
true
if and only if the update was caused by a timeout. If an application callsPrgUpdateDialog()
and a timeout occurs before the callback is called, this field isfalse
. -
← displaySkipBtn
- If
true
, the progress dialog displays a skip button, which allows the user to skip the current stage. -
↔ skipped
- If
true
, the user tapped the skip button to skip the current stage. -
spareBits1
- Not used.
-
padding1
- Not used.
-
↔ 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 forEvtGetEvent()
to a value that is equal to or less than this value, otherwise you won't get update events as frequently as you expect. -
padding2
- Not used.
-
↔ barMaxValue
- The maximum value for the progress bar.
-
↔ barCurValue
- The current value that the progress bar should display.
-
barMessage
- Not used.
-
barFlags
- Not used.
-
↔ delay
- 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. -
spareBits2
- Not used.
-
→ 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 the application's global variables.
ProgressType Struct
Purpose
Internal structure that identifies the current progress. This structure is created with PrgStartDialog()
and passed to all other Progress Manager functions. A ProgressPtr
defines a pointer to a ProgressType
structure.
Declared In
Progress.h
Prototype
typedef struct ProgressType ProgressType, *ProgressPtr
Fields
Progress Manager Constants
Progress Manager String Length Constants
Purpose
Specify the maximum sizes of the strings that are displayed in the progress dialog.
Declared In
Progress.h
Constants
-
#define progressMaxButtonText 7
- Maximum length of the text in the OK or Cancel button.
-
#define progressMaxMessage 128
- Maximum length of the
message
field inPrgCallbackData
. -
#define progressMaxTitle 31
- Maximum length in bytes for a title to a progress dialog.
Progress Manager Events
prgUpdateEvent
Purpose
Sent when another thread has updated the progress.
Declared In
EventCodes.h
Prototype
Progress Manager Functions and Macros
PrgGetError Function
Purpose
Returns the current error, if any.
Declared In
Progress.h
Prototype
status_t PrgGetError (
const ProgressType *prgP
)
Parameters
-
→ prgP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
.
Returns
The value of the error
field in PrgCallbackData
.
PrgHandleEvent Function
Purpose
Handles events related to the active progress dialog.
Declared In
Progress.h
Prototype
Boolean PrgHandleEvent ( ProgressPtrprgGP
, EventType*eventP
)
Parameters
-
→
prgGP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
. -
→
eventP
- Pointer to an event. You can pass a
NULL
event to cause this function to immediately call yourPrgCallbackFunc()
function and then update the dialog (for example, after you callPrgUpdateDialog()
).
Returns
true
if the system handled the event. If it returns false
, you should check if the user cancelled the dialog by calling PrgUserCancel()
.
Comments
Use this function instead of SysHandleEvent()
when you have a progress dialog. PrgHandleEvent()
internally calls SysHandleEvent()
as needed.
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 PrgCallbackFunc()
function you specified in your call to PrgStartDialog()
is called. Your PrgCallbackFunc()
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
and bitmapDatabase
fields to include an icon in the update dialog.
See Also
PrgStartDialog()
, PrgStopDialog()
, PrgUpdateDialog()
, PrgUserCancel()
PrgStartDialog Function
Purpose
Displays a progress dialog that can be updated.
Declared In
Progress.h
Prototype
ProgressPtr PrgStartDialog ( const char*title
, PrgCallbackFunctextCallback
, void*userDataP
)
Parameters
-
→
title
- Pointer to a title for the progress dialog. Must be a null-terminated string that is no longer than
progressMaxTitle
. -
→
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.
Returns
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 thread using 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.
Progress dialogs cannot be associated with window constraints resources, and usually one is not necessary. The UI Library makes sure that the dialog is always the same size and snaps to the bottom of the application area. If you need to set window creation attributes that you would normally set in a constraints resource, use PrgStartDialogWithFlags()
.
See Also
PrgHandleEvent()
, PrgStopDialog()
, PrgUpdateDialog()
, PrgUserCancel()
PrgStartDialogWithFlags Function
Purpose
Displays a progress dialog that can be updated. Uses the specified window flags to create the dialog.
Declared In
Progress.h
Prototype
ProgressPtr PrgStartDialogWithFlags ( const char*title
, PrgCallbackFunctextCallback
, void*userDataP
, WinFlagsTypeflags
)
Parameters
-
→
title
- Pointer to a title for the progress dialog. Must be a null-terminated string that is no longer than
progressMaxTitle
. -
→ 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.
-
→ flags
- Window attributes to use when creating the dialog. See
WinFlagsType
. The attributewinFlagModal
is set for you.
Returns
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
Use this function instead of PrgStartDialog()
in one of two circumstances:
- You need the window created for the progress dialog to be a transitional window so that you can draw to it outside of
frmUpdateEvent
s. In this case set the winFlagBackBuffer bit inflags
. - You are displaying a progress dialog outside of the application process and it should appear in the same window layer as all of the other windows in that process.
See Also
PrgHandleEvent()
, PrgStopDialog()
, PrgUpdateDialog()
, PrgUserCancel()
PrgStopDialog Function
Purpose
Releases memory used by the progress dialog and restores the screen to its initial state.
Declared In
Progress.h
Prototype
void PrgStopDialog ( ProgressPtrprgP
, Booleanforce
)
Parameters
-
→
prgP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
. -
→
force
-
true
removes the progress dialog immediately,false
causes the system to wait until the user confirms an error, if one is displayed.
Returns
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.
See Also
PrgHandleEvent()
, PrgStartDialog()
, PrgUpdateDialog()
, PrgUserCancel()
PrgUpdateDialog Function
Purpose
Updates the status of the current progress dialog.
Declared In
Progress.h
Prototype
void PrgUpdateDialog ( ProgressPtrprgGP
, status_terr
, uint16_tstage
, const char*messageP
, BooleanupdateNow
)
Parameters
-
→
prgGP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
. -
→
err
- If nonzero, 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. Iffalse
, sends aprgUpdateEvent
, which causes the dialog to be updated on the next call toPrgHandleEvent()
.
Returns
Comments
This function can be called from a background thread to update the dialog in the application thread. The updateNow
parameter must be false
in this situation.
For more information about how the parameters are used and the callback function, see the section "Application-Defined Functions."
See Also
PrgHandleEvent()
, PrgStartDialog()
, PrgStopDialog()
, PrgUserCancel()
PrgUserCancel Function
Purpose
Returns true
if the user cancelled the process using the progress dialog.
Declared In
Progress.h
Prototype
Boolean PrgUserCancel (
const ProgressType *prgP
)
Parameters
-
→
prgP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
.
Returns
true
if the user tapped the Cancel button; false
otherwise.
Comments
This is a function 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.
See Also
PrgHandleEvent()
, PrgStartDialog()
, PrgStopDialog()
, PrgUpdateDialog()
PrgUserSkip Function
Purpose
Returns true
if the user skipped the current stage of the process using the progress dialog.
Declared In
Progress.h
Prototype
Boolean PrgUserSkip (
const ProgressType *prgP
)
Parameters
-
→ prgP
- Pointer to a progress structure created by
PrgStartDialog()
orPrgStartDialogWithFlags()
.
Returns
true
if the user tapped the Skip button; false
otherwise.
Comments
This is a function you can use to check if the user skipped the current stage of the process. If the user did skip, you can change the progress dialog text to something like "Skipping," or whatever is appropriate for your application. Then you should move on to the next stage of the process, or do whatever processing is necessary.
The progress dialog only has a skip button if you specifically enable it by setting displaySkipBtn
to true
in the PrgCallbackData
structure.
Application-Defined Functions
PrgCallbackFunc Function
Purpose
Supplies the text and icons for the current progress state.
Declared In
Progress.h
Prototype
Boolean (
*PrgCallbackFunc
) (
PrgCallbackDataPtr cbP
)
Parameters
-
↔
cbP
- A pointer to a
PrgCallbackData
structure.
Returns
true
if the progress dialog should be updated using the values you specified in the PrgCallbackData
structure. If you return 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.
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 message 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 by calling PrgUpdateDialog()
with a messageP
parameter.
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 callback function is called only once.