Rewritten January 2013
CTLOP_PANE (opcode 11) is only used with Tab controls, in order to select the current pane. There are two variations, one for the traditional (standard Windows) Tab control, and one for the TabX control.
Traditional Tab (or TabX) Control:
xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid, "", pane
TabX Control:
xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid, paneid, cstate, NUL_CTYPE, NUL_CMD$, NUL_FUNC$, cstatus
Parameters
id of the Tab or TabX control
pane (B,4) [in]
is the pane number (starting with 1)
paneid (String) [in]
the alphanumeric identifier for the desired pane, which may be either the pane's command string (e.g. "VK_xF302"), or the pane's label text (e.g. "&History"), or the pane number (e.g. "2"). Note that with TabX, since it is possible to insert and delete panes after the control has been created, the pane number could be subject to change, and thus the command string or label text is a more robust identifier.
cstate (B,4) [in]
may specify the optional flag MBST_SAVRES in which case the current panel's controls will be saved; if there is a previously saved set of controls for the new panel, it will be restored, and the number of restored controls will be returned in the cstatus parameter, allowing you to conditionally recreate the controls. For backwards compatibility, if paneid = "", you can specify the new panel number in the low word of the cstate parameter.
Note: Since the MBST_SAVRES flag signals both the save operation (for the current panel) and the restore operation (for the new panel), if you only want one of the operations, you'll have to use the two step method (CTLOP_CLR followed by CTLOP_PANE) so that you can specify the MBST_SAVRES flag on just the one operation.
cstatus (Signed Num) [out]
will return the number of controls restored if MBST_SAVRES was specified and there was a previously saved set of controls for the new panel. Otherwise it will return 0 for success, or < 0 for an error. See Comments for more details about using cstatus with MBST_SAVRES.
Comments
In the traditional Tab control, clicking a new pane automatically selected it, so that the CTLOP_PANE operation is technically redundant, except for the need to clear the old controls from the panel. The click operation only highlights the new panel label; since all the labels share the same panel, it doesn't actually do anything to the panel itself). You may use CTLOP_CLR to clear the controls from the pane, but CTLOP_PANE also clears the controls, and thus is a better choice for compatibility with the TabX control.
In the TabX control, clicking a new pane does not automatically select it or change the display in any way. It only sends the click string, leaving it to your application to decide whether to follow through or take some other action. Unlike the traditional Tab control, the TabX control supports different colors on each panel, so auto-selecting the panel on click would cause visual confusion if the application decided to delay or prevent the panel switch (due to some data validation issue on the current panel). To follow through the with panel switch, the application must use the CTLOP_PANE operation.
In the standard/traditional scenario, switching panels always involved recreating all the controls for the new panel. However, for panels with many or complex controls, this can slow down the panel switching operation. The MBST_SAVRES option streamlines the panel switch operation by automatically restoring the controls if the target panel had previously been displayed. Rather than trying to keep track of which panels have been displayed and saved, the easiest programming approach is use the returned cstatus value to determine whether the controls need to be recreated, e.g.:
xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid, paneid$, MBST_SAVRES, NUL_CTYPE, NUL_CMD$, NUL_FUNC$, cstatus
if cstatus < 1 then ! (no controls restored)
< (re)create controls for the new panel >
endif
This way, the first time you switch to a panel, the application will have to create the controls, but subsequently if you switch back to that panel, the controls will be automatically restored, allowing the application to skip recreating them.
If you don't want to use the restored controls and prefer instead to recreate them from scratch, you can use the CTLOP_CLR operation after CTLOP_PANE to remove the restored controls, then recreate them.
Since the MBST_SAVRES flag triggers both the save operation for the current panel, and the restore operation for the new panel, in order to use the save/restore feature on only some of the panels, you would have to break up the panel switch operation into two parts: CTLOP_CLR followed by CTLOP_PANE. Both operations support the MBST_SAVRES flag, but in the case of CTLOP_CLR, it only performs the save operation, while in the case of CTLOP_PANE, if the panel is already clear, the save operation is ignored and only the restore operation is attempted. So for example, to switch from a panel whose controls you do want to save, to a panel whose controls you want to recreate from scratch (i.e. not restore), use this sequence:
! save controls and then clear panel
xcall AUI, AUI_CONTROL, CTLOP_CLR, tabid, NUL_CTEXT$, MBST_SAVRES
! switch to new panel without restore
xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid, paneid2$
To reverse the sequence, i.e. to switch back from the panel whose controls are not being saved, to the one whose controls you do want to restore:
! clear panel without save
xcall AUI, AUI_CONTROL, CTLOP_CLR, tabid
! switch to new panel, requesting restore
xcall AUI, AUI_CONTROL, CTLOP_PANE, tabid, paneid1$, MBST_SAVRES, NUL_TYPE, NUL_CMD$, NUL_FUNC$, cstatus
if cstatus < 1 then ! if no controls restored
<recreate controls>
endif
History
2013 January, A-Shell 6.1.1333: CTLOP_PANE now supports one-step panel switch, with optional save/restore.