A-Shell Reference

Rewritten February 2013

CTLOP_CHG (opcode 2) can be used, in conjunction with various MBST_xxx flags in the cstate parameter, to change virtually any of the attributes of an existing control (such as the displayed text, state, command, etc.) For example, consider the following sample dialog:

The Connect button is disabled because the user hasn't entered enough information to even justify attempting a connection. Once they do so, we want to enable the Connect button, which we can do with something like the following:

xcall AUI, AUI_CONTROL, CTLOP_CHG, btnid, NUL_CTEXT, MBST_ENABLE

The key parameters here were the button identifier and the MBST_ENABLE flag. We're not changing the button text, so we just supply NUL_CTEXT (defined as "" in the ashell.def) for the ctext parameter, and none of the other parameters are required. If we wanted to know what the prior state of the control was, we could pass the cstatus parameter (and those prior to it), but in most cases, we don't care about the prior state.

To take another example, let's say we want to change the label associated with the second field, depending on the Database Connector - for MySQL, "Host/Server" seems appropriate, but for ODBC, "Data Source" might be better. To accomplish that, we can use a slight variation of the CTLOP_CHG operation:

xcall AUI, AUI_CONTROL, CTLOP_CHG, btnid, "Data Source", MBST_CHANGE + MBST_TEXTONLY

The combination of the MBST_CHANGE and MBST_TEXTONLY flags in the cstate parameter causes the operation to only affect the text of the control, for which we supplied the string "Data Source".

Depending on which MBST_xxx flags are specified, you may need to specify more parameters, with the extreme case being MBST_CHANGEX which replaces all of the attributes of the control (essentially deleting and recreating it). Virtually all of the MBST_xxx cstate flags can be used with CTLOP_CHG, but the following ones apply uniquely to CTLOP_CHG and are therefore worth noting: