Progress Bar Control
toolslib\custctrl\progressbar.fp
This instrument driver provides functions for creating and configuring progress bar controls.
Add a progress bar control to your user interface to provide a visual cue of the advancement of a task that is currently running. These controls are especially useful for showing the progress of lengthy tasks.
To create a progress bar programmatically, use the ProgressBar_Create function. You also can convert an existing numeric slide control to a progress bar by calling the ProgressBar_ConvertFromSlide function. If you convert from a slide control, you must use numeric slide level controls or flat slide controls instead of pointer slide controls.
The progress bar moves across the length of the control to illustrate how much of a task is left to complete. You can set the position of the progress bar in the following ways:
- Percentage Value—Call ProgressBar_SetPercentage to move the progress bar to the percentage value you specify.
- Milestones—Call the milestones functions to move the progress bar according to milestones you create. When you create a milestone, you associate a percentage value with the milestone; the percentage value specifies how far to move the progress bar when the milestone is reached. You can create a single milestone with the ProgressBar_AddMilestone function. If you want to create multiple milestones at one time, call the ProgressBar_SetMilestones function. To advance the progress bar to the next milestone, use the ProgressBar_AdvanceMilestone function.
Use one of the following modes to specify how to move the progress bar:
- Manual—In manual mode, the progress bar moves when you explicitly update the value of the progress bar using percentage values or milestones.
Use manual mode when you can interrupt the task frequently to update the progress bar in small increments.
If you use milestones in manual mode, you must start a session. - Auto—In auto mode, the progress bar moves automatically and asynchronously according to the estimated total time for the task.
If you have milestones defined for the control, the progress bar stops when it reaches each milestone until you explicitly advance the control to that milestone.
Use this mode when you cannot interrupt the task frequently to update the progress bar and when you expect repeated sessions to have similar duration times.
You must start a session to begin movement of the progress bar in auto mode.
If another control on the panel overlaps the progress bar, you must be able to process events regularly in the thread that owns the progress bar's panel. - Marquee—In marquee mode, a shortened portion of the progress bar moves continuously across the control. The progress bar does not indicate how far along the task is. This functionality is equivalent to a wait cursor.
Use this mode when it is not possible to estimate how far along a task is, and instead you want to indicate that a task is in progress.
You must start a session to begin movement of the progress bar in marquee mode.
If another control on the panel overlaps the progress bar, you must be able to process events regularly in the thread that owns the progress bar's panel.
The progress bar includes functionality to automatically adjust how quickly the bar moves. When you enable the ATTR_PROGRESSBAR_AUTO_ADJUST attribute, LabWindows/CVI averages the time intervals of progress bar sessions and adjusts the movement of the progress bar to match the actual elapsed time of the task.
The progress bar can receive the EVENT_PROGRESSBAR_MILESTONE_REACHED event during auto mode. This event is sent when the progress bar catches up to the next milestone or the end position before you programmatically set the milestone. This is the point at which the progress bar stops advancing until you explicitly advance it.
eventData1 is the one-based index of the milestone reached or 0 if the end position is reached. If you want to get the actual position of the progress bar, you can call ProgressBar_GetPercentage or ProgressBar_GetMilestone.
The progress bar is available as a custom control. Select Create»Custom Controls»Toolslib Controls»Progress Bar to add a progress bar as a custom control to your user interface.
The functions in this instrument driver are multithread-safe.