Refresh

The Refresh callback is called when the application context is changed. The context message is passed back as an array of STRINGs in !args[0], !args[1], and !args[2] where:

• !args[0] defines what changed ('CONTEXT', 'INITIALISED', 'CE', ...).

• !args[1] describes how it changed ('CHANGED', ...).

• !args[2] contains an identifier (for example, name of an element or a form or a context message depending on the message type in !args[0]).

Application context is changed using the !!CMSYS object which will send the message:

'CONTEXT', 'CHANGED', '<context message>'

For example, a command attached to a tab could change tab visibility depending on the context as follows:

define method .refresh(!args is ARRAY)

!change = !args[0]

!type = !args[1]

!message = !args[2]

if( !change neq 'CONTEXT' ) then

return

endif

if (!message eq 'Piping') then

-- Make piping tab visible

!this.visible(true)

else

-- Make piping tab invisible

!this.visible(false)

endif

endmethod

An array of filters can be added in the command constructor to restrict the messages sent to the refresh callback. For example, if the following filters are set then refresh will only be called if the message is 'INITIALISED' or 'CONTEXT'.

!filters[1] = 'INITIALISED'

!filters[2] = 'CONTEXT'

!this.refreshFilters = !filters

If no filters are set, then all messages will be sent to the refresh callback.

Note:
It is strongly advised use filters to minimize the number of calls to refresh methods. If no filters are used then the refresh method will be executed on every CE change and every time that a form is activated, deactivated or closed. This can adversely affect performance by executing many lines of PML code unnecessarily. If it is necessary to execute a refresh method, it is advisable to minimize the amount of code executed on each call to the method. Bugs in code executed on refresh events can be difficult to debug.