# Clear Control

> [HTML Version](clear_control.htm)

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](xtreextexttabperformance.htm.md) 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](proportionalfonttextobjects.htm.md) 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](parentid_aui_control.htm.md) 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](controldump.htm.md), which clearly shows the [parentid](parentid_aui_control.htm.md)_ _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.