Controls may be given names, which can then be used instead of the ID numbers to reference them. To assign a name to a control when creating it, specify a string parameter with the desired name in place of the CTLID parameter, i.e.:

CTLNAME$ = "Cus-cbTaxExampt"

PARENTNAME$ = "dlgCustomer"

xcall AUI, AUI_CONTROL, CTLOP_ADD, CTLNAME$, CTEXT$, CSTATE, CTYPE, CMD$, FUNC$, CSTATUS, SROW, SCOL, EROW, ECOL, FGC, BGC, FONTATTR, FONTSCALE, FONTFACE, TOOLTIP, PARENTNAME$, WINCLASS, WINSTYLE, WINSTYLEX, CTYPE2, CAUXDATA

In the example above, the string variable CTLNAME$ is being used in place of the normal numeric CTLID parameter (which normally returns the ID of the newly created control). Since we are assigning the name "Cus-cbTaxExempt" to the control, we probably don't need to get back the numeric control ID, but in case you do want to save it, it will be in the CSTATUS parameter. (Previously CSTATUS was set to 0 for success; now, if a string name is used in place of the CTLID parameter, CSTATUS will return the ID #.)

Similarly, the PARENTID parameter may be replaced with a string name in order to reference the parent by its name rather than number.

Control names should be unique across all controls used within a single program. You may want to adopt a naming standard which includes a prefix for the dialog and perhaps another prefix to identify the control type, as in our example above, where "Cus-cbTaxExempt" is meant to indicate that it is part of the Cus dialog, and it is a checkbox (cb). Names may be up to 23 characters long, plus a trailing null.

You can retrieve the control ID # associated with a control name, or vice versa, using the CTLOP_INFO opcode. To get the ID # associated with the name, just use CTLOP_INFO with the name in place of the CTLID parameter; the ID # will be returned in CSTATUS (just as when the control was created). For example:

xcall AUI, AUI_CONTROL, CTLOP_INFO, CTLNAME$, CTEXT$, CSTATE, CTYPE, CMD$, FUNC$, CSTATUS

   if CSTATUS > 0 then CTLID = CSTATUS

To get the name associated with a control ID #, specify a string variable in place of the CTLID parameter, that contains the string representation of the control ID #, e.g.:

CTLNAME$ = str(CTLID)   ! e.g. "7"

xcall AUI, AUI_CONTROL, CTLOP_INFO, CTLNAME$, CTEXT$, CSTATE, CTYPE, CMD$, FUNC$, CSTATUS

In this case, the CTLNAME$ parameter will be updated on return, with the name of the control.

A new "Name" column has been inserted into the Control Dump, providing a convenient way for you to verify how your control names and numbers are matching up.

Note that although you may specify a name for the PARENTID parameter, the name is converted to the equivalent number at the time the control is added. So the PARENTID name doesn't show in the control dump. But the CTLOP_INFO command will return the PARENT control name if you specify a string variable in place of the PARENTID parameter.

Also note that for controls and functions that do not currently support a convenient means of specifying a symbolic name for the control ID or parent ID when creating the control (e.g. XTREE, XTEXT, EVENTWAIT), you have to convert the control names to ID numbers (using CTLOP_INFO if necessary).

The symbolic names are currently supported in all forms of AUI_CONTROL, AG_CONTROL, MX_AUTOPARENT and AUTO_PARENT.