Progress and Interrupt Methods

Software Customisation Guide

FMSYS Object and its Methods : Progress and Interrupt Methods

Form and Gadget callbacks may take a long time to execute, so it is often desirable to use the Progress Indicator on the Application Window's status bar (along the bottom) to indicate continuing progress to the user. The Progress Indicator consists of a display text field and a progress bar.

The user can write to the text field using

!!FMSYS.setProgressText(!text is STRING )

The user can set the %progress by

!FMSYS.setProgress(!percent is REAL)

The user can also query the current settings of both using the methods

!real = !!FMSYS.Progress()

!string = !!FMSYS.ProgressText()

Additionally for some callback operations it may be required to allow the user to interrupt the operation and choose to cancel it. The FMSYS methods Interrupt and setInterrupt allow this to be achieved.

The callback which provides the required operation, must be cyclical so that there is some repeated access point where the user can report progress (approximately as a percentage of the total task), and check to see if the user has clicked a stop button which the user has provided on some displayed form.

In the users callback function they must first notify the system of the identification of the stop button using the FMSYS method SetInterrupt:

!!FMSYS.setInterrupt(!!fmstop.stopButton )

Then at an appropriate point in the callback, check to see if the stop button has been pressed using the FMSYS Interrupt method, and exit with a message if it has:

-- Initialise progress bar

!!FMSYS.setProgress(0)

!!FMSYS.setProgressText('Routing pipes')

do !next from 1 to 50

...

 !!RoutePipe( !next, . . . )    $*Route next pipe

...

-- Update the progress bar - first update the percentage

completion

!percent = ...

!!FMSYS.setProgress( !percent )

 -- Check if user pressed interrupt button

 if ( !!FMSYS.Interruppt() ) then

 return error 1 'Processing aborted'

  endif

enddo

Following is the PML code for a simple interrupt form !!fmstop.pmlfrm:

$* F&M test harness: Stop form for interrupt management

layout form !!fmstop dialog NoAlign

title 'STOP (!!fmstop)'
path down
para   .stopText  text |Press to quit task|  width 20
button .stopButton |Quit| width 25 height 2

exit

define method .fmstop()

--Constructor
-- define callbacks
!this.firstShownCall = |!this.stopButton.background =
 'red'|

endmethod