Updated October 2012

CTLOP_CLR (opcode 4) is just like opcode 3, except for the following differences:

•   If ctlid is specified, then only the children of that control are deleted. This is most useful with Tab controls, where, as you change panes, you need to remove the children previously displayed on the old pane and create the ones corresponding to the new one. If ctlid does not refer to a control with children, then it is ignored (i.e. treated as if zero), in which case it identifies the controls to be deleted by the coordinates (assuming ctext = "*"). See XTREE/XTEXT Tab Performance for an alternative to clearing and recreating XTREE and XTEXT controls within Tab panes.

•   It only deletes "unprotected" controls. By default static text controls are unprotected (as are those created with EPRINT), while most other types are protected. (You can, however, remove protection from protected controls by adding MBF_UNPROTECTED when the control is created.) To add protection to text controls, you have to add the dim attribute and also enable protection just like you would with regular text, using Tab(-1,13). For text controls created with AUI_CONTROL, you add protection by specifying MBF_DIM when creating the control. For text controls created via TPRINT commands, the MBF_DIM attribute is set automatically if the current text mode is dim (i.e., if Tab(-1,11) was issued previously.) The point of all this is to allow you to perform the same "trick" that is possible with dumb terminals, whereby you can protect the background of a form and clear the foreground with just a couple of commands. If it just seems confusing, you can probably ignore it.

Note: In order for CTLOP_CLR to clear the controls from the Tab control pane, those controls must be children of the Tab control! A common mistake when working with Tab controls is to fail to explicitly set the parentid of the controls appearing within the active pane; typically this results in those controls being children of the outer dialog—siblings of the Tab control—and thus outside the scope of the CTLOP_CLR operation on the Tab control. An easy way to visualize this problem is to generate a Control Dump, which clearly shows the parentid of each control.

Tab(-1,10) (clear to end of screen) and Tab(-1,9) internally perform an opcode 4 for the region in question.

History

2012 October, A-Shell 6.0.1261:  AUI_CONTROL refinement: When using opcode CTLOP_CLR, you may now set the MBST_TEXTONLY flag in the cstate parameter to cause it to clear the text from any affected control, rather than delete the control entirely. This is mainly useful with controls containing data in a form, where you want to clear the data but leave the form. Note that in such a case, you will probably want to protect the label controls from being cleared, which you can do by creating them with the MBF_DIM attribute set, and using TAB(-1,13) to enable protection immediately prior to the AUI_CONTROL, CTLOP_CLR operation. Use TAB(-1,14) afterward to disable protection.

For example, to clear the text from the unprotected controls, and leave the protected controls alone (in the region of rows 1-24 and cols 1-80):

? tab(-1,13);   ! enable protection

xcall AUI, AUI_CONTROL, CTLOP_CLR, NUL_CTLID, "*", MBST_TEXTONLY, NUL_CTYPE, NUL_CMD$, NUL_FUNC$, 1, 1, 24, 80

? tab(-1,14);   ! disable protection

Note that the "*" in the ctext parameter is required to select all the controls.