Added January 2013; see History

The cstate flag MBST_SAVRES can be applied to the CTLOP_CLR and CTLOP_PANE operations operations when operating on TabX controls to have the client module save the contents of the panel being cleared, and restore the previously saved contents of the new panel (if available).

When switching from one TabX panel to another, the traditional protocol is to first call CTLOP_CLR to clear the controls from the current panel, then call CTLOP_PANE to establish the new panel, and finally (re)create the controls on the panel. The new feature doesn't change that logic, except as follows:

To request that the existing contents of the panel be saved before the panel is cleared, specify the cstate parameter with the MBST_SAVRES flag in the CTLOP_CLR call:

xcall AUI, AUI_CONTROL, CTLOP_CLR, tabid$, NUL_CTEXT$, MBST_SAVRES

To request that the previously saved controls for the new panel be restored, specify the cstate parameter with the MBST_SAVRES flag in the CTLOP_PANE call. To confirm whether any controls were actually saved, you should also specify up to the cstatus parameter (which will return the count of the number of controls restored):

xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid$, paneid$, MBST_SAVRES, NUL_CTYPE, NUL_CMD$, NUL_FUNC$, status

if status <= 0 then   ! if no controls restored

   <(re)create the controls for the new panel>

 endif

Notes

•   You need to identify the panel to switch to by putting the panel's label text or cmd string into the paneid$ parameter (i.e. ctext), rather than putting the panel number into the cstate parameter (as in the traditional Tab control). This leaves the cstate parameter available for the MBST_SAVRES flag.

•   By checking the returned status parameter, you can determine whether the restore operation was successful without actually having to keep track of whether that panel has previously been displayed and saved (or even whether the ATE client version is sufficient to support the feature).

•   You must perform the CTLOP_CLR first, then the CTLOP_PANE. The reverse order is possible, but not when using MBST_SAVRES.

•   The motivation behind the MBST_SAVRES feature is not to simplify your application coding; in fact, it makes it slightly more complex. Instead, the motivation is to improve the performance of switching between panels, particularly with ATE and with complex controls like XTREE and XTEXT.

History

2013 January, A-Shell 6.1.1332:  Flag added to A-Shell