SclProgressFeedback
Overview
The SclProgressFeedback command allows you to create a visual feedback facility on the status bar (at the bottom of the software window) to display the progress of a task in your script. There are two styles of feedback known as a bar and a bounce.
Bar feedback is used when you can measure the progress of your task such as processing 100 drill holes, where you know at any point how many drill holes you have processed. Bounce feedback is used when you can't measure the progress of the task but want to display some feedback to indicate that the script is working. An example use for bounce feedback would be loading a file where you don't know in advance how many records are in the file.
Progress bars and bounces exist in a hierarchical structure where more than one feedback operation can be in existence at any stage. The last feedback operation created takes precedence and will occupy the majority of the display area on the status bar. It is important that you end the progress feedback operation when you are finished so that the display of any previous feedback can recommence.
Notes on Macro User Abort
Macro scripts that consume the computers resources for extended periods have an adverse effect on the computers ability to respond to user abort events. A user abort event is instigated when the macro user presses the abort button that is part of the progress feedback display or depresses the macro playback icon on the main toolbar.
By calling the SclProgressFeedback update methods at regular intervals in the script the system is able to check for this event and respond appropriately by terminating the macro. If you want to catch and handle the user abort event in the script yourself, then this can be done by using the sclUserAbort system option as described in the user abort documentation.
Synopsis
SclProgressFeedback <sub option> <optional parameters>
Description
The SclProgressFeedback command provides functions to manage the progress feedback facility by creating, updating, and ending a progress feedback operation. When creating a progress feedback operation you supply a message that will be displayed as part of the feedback. You must also update the feedback at regular intervals to increase the size of a bar feedback and to also ensure that macro abort events can be responded to. Ending a feedback operation will remove it from the status bar.
The SclProgressFeedback command supports the following options:
SclProgressFeedback bar <message> <startValue> <endValue>
SclProgressFeedback bounce <message>
SclProgressFeedback update <$progressHandle> <value>
SclProgressFeedback update <$progressHandle>
SclProgressFeedback end <$progressHandle>
Synopsis
SclProgressFeedback bar <message> <startValue> <endValue>
Description
Create a bar style progress feedback and display on the status bar. A bar feedback contains a message and has a start and end value that determine the range of values for the bar. When created the bar progress is set to the start value so that the bar is not coloured. You must use the update function at intervals to increase the value towards the end value at which point the bar will be completely colour filled.
Arguments
- bar
- <message>
- <startValue>
- <endValue>
A literal string to identify the function
The message to display in the progress feedback area
The bars starting (lower) value
The bars ending (upper) value
Returns
This function returns a reference handle to the progress bar. This reference handle must be passed as a parameter to other SclProgressFeedback functions.
Examples
# create a bar feedback item set progressBar [SclProgressFeedback bar "Percentage complete" 0 100] |
See the examples at the end of this page
Synopsis
SclProgressFeedback bounce <message>
Description
Create a bounce style progress feedback and display on the status bar. A bounce feedback contains a message that is displayed in the bar. When created a small coloured region will be displayed that moves from left to right and back across the display region to give the appearance of a bounce.
Arguments
- bounce
- <message>
A literal string to identify the function
The message to display in the progress feedback area
Returns
This function returns a reference handle to the progress bounce. This reference handle must be passed as a parameter to other SclProgressFeedback functions.
Examples
# create a bounce feedback item set progressBounce [SclProgressFeedback bounce "Processing"] |
See the examples at the end of this page
Synopsis
SclProgressFeedback update <$progressHandle> <value>
Description
Update a progress feedback bar. When updating a bar you must also supply a value that is within the start and end value range that you specified when creating the bar. It is also important to update the bar so that processing of any macro abort events can occur. If you don't perform this function the script can lock up the computers resources for long periods. Calling the update method to often can also have an impact on performance so a balanced interval between calls to the update method should be used.
Arguments
- update
- <$progressHandle>
- <value>
A literal string to identify the function
The reference handle to the progress bar to update
The value to update the bar to. The value is used as a percentage indicator between the start and end values for the bar.
Returns
Returns SCL_OK.
Examples
# create a bar feedback item set progressBar [SclProgressFeedback bar "Percentage complete" 0 100] # update the bar to halfway SclProgressFeedback update $progressBar 50 |
See the examples at the end of this page
Synopsis
SclProgressFeedback update <$progressHandle>
Description
Update a progress feedback bounce. It is also important to update the bounce at regular intervals so that processing of any macro abort events can occur. If you don't perform this function the script can lock up the computers resources for long periods. Calling the update method to often can also have an impact on performance so a balanced interval between calls to the update method should be used.
Arguments
- update
- <$progressHandle>
A literal string to identify the function
The reference handle to the progress bounce to update
Returns
Returns SCL_OK.
Examples
# create a bounce feedback item set progressBounce [SclProgressFeedback bounce "Processing"] # update the bounce to check for macro abort SclProgressFeedback update $progressBounce |
See the examples at the end of this page
Synopsis
SclProgressFeedback end <$progressHandle>
Description
This function removes the display of the feedback operation and will release all memory associated with it.
Arguments
- end
- <$progressHandle>
A literal string to identify the function
The reference handle to the progress bar or bounce to end
Returns
Returns SCL_OK.
Examples
# create a bar feedback item set progressBar [SclProgressFeedback bar "Percentage complete" 0 100] # update the bar to halfway SclProgressFeedback update $progressBar 50 # update the bar to completion SclProgressFeedback update $progressBar 100 # end the feedback SclProgressFeedback end $progressBar |
See the examples at the end of this page
Working Examples
Example 1
An example that shows the use of a progress feedback bar.
# create the progress bar
set progressBar [SclProgressFeedback bar "Processing holes" 0 100]
for {set i 0} {$i < 100} {incr i} {
# a loop to consume some time
for {set j 0} {$j < 10000} {incr j} {}
# update the bar to increase the colour filled region
SclProgressFeedback update $progressBar $i
}
# end the bar feedback and cleanup
SclProgressFeedback end $progressBar
SclDestroy progressBar
|
Example 2
An example that shows the use of a progress feedback bounce
# create the progress bounce
set progressBounce [SclProgressFeedback bounce "Processing items"]
for {set i 0} {$i < 1000} {incr i} {
# a loop to consume some time
for {set j 0} {$j < 10000} {incr j} {}
# update the bounce, if you press abort the script will stop
SclProgressFeedback update $progressBounce
}
# end the bounce feedback and cleanup
SclProgressFeedback end $progressBounce
SclDestroy progressBounce
|
Example 3
An example that shows how progress feedback operations can co-exist
# create a progress bar
set progressBar [SclProgressFeedback bar "Processing holes" 0 100]
for {set i 0} {$i < 100} {incr i} {
# create a progress bounce
set progressBounce [SclProgressFeedback bounce "Processing hole $i"]
for {set j 0} {$j < 10000} {incr j} {
if {!($j % 100)} {
# update the bounce
SclProgressFeedback update $progressBounce
}
}
# end the bounce feedback and cleanup
SclProgressFeedback end $progressBounce
# update the bar to increase the colour filled region
SclProgressFeedback update $progressBar $i
}
# end the bar feedback and cleanup
SclProgressFeedback end $progressBar
SclDestroy progressBar
|