SaAutoRefresh(3tlib)

SaAutoRefresh: SaAutoRefresh, SaAutoRefreshOn, SaAutoRefreshOff, SaAutoRefreshPause, SaAutoRefreshResume, SaAutoRefreshGetState, SaAutoRefreshGetInterval, SaAutoRefreshSetInterval, SaAutoRefreshLoad, SaAutoRefreshStore, SaAutoRefreshCalled, SaAutoRefreshIntervalCB -- SCO Visual Tcl package for manual and automatic refreshing of data

Synopsis

SaAutoRefresh refreshCB [menu] [shortStr] [shortHelpCB] [intervalCB]
SaAutoRefreshOn [cbs]
SaAutoRefreshOff [cbs]
SaAutoRefreshPause [cbs]
SaAutoRefreshResume [[cbs]
SaAutoRefreshGetState
SaAutoRefreshGetInterval
SaAutoRefreshSetInterval interval
SaAutoRefreshLoad client
SaAutoRefreshStore client
SaAutoRefreshCalled [cbs]
SaAutoRefreshIntervalCB min max

Description

SaAutoRefresh provides a complete interface for manual and automatic refresh services. It includes standard menu items for a user interface for performing a refresh and enabling automatic refresh calls based on a user configurable interval. The Store and Load interface allow user configurable settings to persist across multiple invocations of the application.

SaAutoRefresh

initializes the refresh package by registering the application refresh callback along with optional arguments for defining the standard pulldown menu options, point help description, point help callback and an application specific interval configuration callback.

Optional arguments in TCL are positional: in order to provide a particular argument, all arguments to the left MUST be provided as well. This must be called before any other auto refresh procedures.

SaAutoRefreshOn

starts the auto refresh service. Behavior is based on the currently configured interval and whether or not auto refresh is "paused". When a refresh event is due, the application callback (refreshCB) will be called. The auto refresh service it typically enabled implicitly through the menu option. The application itself is not aware of this state change.

SaAutoRefreshOff

stops the auto refresh service. Any pending refresh events will be cancelled. The auto refresh service is typically disabled implicitly through the menu option. The application itself is not aware of this state change.

SaAutoRefreshPause

pauses the auto refresh service. This may be called regardless of whether auto refresh enabled or not. The application may effectively block refresh events without disturbing the on/off state of the auto refresh service.

SaAutoRefreshResume

resumes the auto refresh service. This may be called regardless of whether auto refresh enabled or not. The application may effectively unblock refresh events without disturbing the on/off state of the auto refresh service.

SaAutoRefreshGetState

returns a boolean (1 = on) indicating the state of the auto refresh service.

SaAutoRefreshGetInterval

returns the currently configured auto refresh interval. The interval value is in seconds.

SaAutoRefreshSetInterval

configures the auto refresh interval. The interval value is in seconds.

SaAutoRefreshLoad

loads and configures auto refresh parameters retained from the most recent SaAutoRefreshStore. This includes the auto refresh state (on or off) and the interval (in seconds). This should be called soon after the call to SaAutoRefresh. SaAutoRefreshLoad uses SaScreenPolicyGet(3tlib).

SaAutoRefreshStore

stores the currently configured auto refresh parameters: auto refresh state (on or off) and the interval (in seconds). This is typically called from the exit routine of the application, just before terminating and after the user's final opportunity to modify these parameters. SaAutoRefreshStore uses SaScreenPolicySet(3tlib).

SaAutoRefreshCalled

returns a boolean indicating whether or not this callback was invoked from the auto refresh service versus explicitly by the application. This is useful if the application calls its refresh callback (refreshCB) internally and needs to distinguish this case from an automatic refresh call.

SaAutoRefreshIntervalCB

built-in callback that presents a user interface for configuring the auto refresh interval. Interval configuration is optional. If interval configuration is desired, the application must supply a callback to SaAutoRefresh. SaAutoRefreshIntervalCB is available as a default. Applications may supply their own callback if a customized user interface is necessary. The default interface presents a scale widget bounded by min and max values supplied by the application.

When passed as an argument to SaAutoRefresh, SaAutoRefreshIntervalCB must appear in a list along with min and max values (in seconds):

{SaAutoRefreshIntervalCB min max}

Arguments

RefreshCB

application callback that implements refresh events. RefreshCB must accept a callback structure (cbs):

proc RefreshCB {cbs}

menu

SCO Visual Tcl widget string for the pulldown menu where the refresh options will appear. The menu options are:

   Auto Refresh -> on
   		off
   		----
   		Interval
   Refresh Now

Note the Interval menu option only appears if the application supplies the intervalCB to SaAutoRefresh.

If menu must be provided as a positional parameter but an actual menu is not used, it may be null: ``{}''.

shortStr

string representing the application's name for the object being refreshed, (such as "Data", "Print Jobs", "Statistics" and so on).

shortHelpCB

callback that deals with point help. This defaults to SaShortHelpCB. Provides point help for refresh menu options.

intervalCB

callback that presents a user interface for configuring the auto refresh interval. Applications may specify the built-in callback SaAutoRefreshIntervalCB (see above). If this argument is omitted, interval configuration will not appear on the pulldown menu.

client

string that uniquely identifies application used for storing/loading refresh parameters in a common file. Must conform to the rules for Stanza section names.

interval, min, max

arguments specifying interval values in seconds.

cbs

callback structure. This is a standard argument passed by SCO Visual Tcl to all callback procedures. Those auto refresh procedures showing cbs as optional will work either as callbacks (with a cbs) or as directly called procedures (without a cbs).

Diagnostics

The Load and Store procedures may throw errors from the underlying SaScreenPolicy interfaces and should be handled withErrorCatch.

References

SaScreenPolicy(3tlib), SaShortHelp(3tlib).

Notices

All application callbacks are auto locked. See SCO Visual Tcl and -autoLock.