Written December 2023
The AUI_CONTROL operation has many parameters, many of which are effectively optional but still need to be specified as placeholders (unless using Named Parameters in Subroutines syntax). As an aid to self-documenting code and to keeping the parameters in order, the following symbols are defined for specifying "don't care" parameters.
Symbol |
Value |
Meaning |
|---|---|---|
NUL_CTLID |
0 |
Use when you don't need to refer to the control again by its id. |
NUL_CTEXT$ |
"" |
|
NUL_CSTATE |
0 |
Enabled, visible (i.e., normal). |
NUL_CTYPE, NUL_CTYPE2 |
0 |
Mainly used for operations that do not affect the control type. |
NUL_CMD$ |
"" |
For controls with no command string and/or function strings. |
|
|
|
NUL_CSTATUS |
"" |
cstatus parameter normally numeric; this form disables any return status, which makes it much faster in ATE environment. |
NUL_SROW, NUL_SCOL, NUL_EROW, NUL_ECOL |
0 |
Use when coordinates are not being affected by the operation. |
NUL_FCG, NUL_BGC |
-2 |
Default colors. Default foreground is based on the Windows theme text color, usually black. Default background is transparent for text controls, else based on the Windows theme for dialogs and other controls with solid backgrounds. |
NUL_FONTATTR |
0 |
Standard text attributes; upright, don't care which symbol set. |
NUL_FONTSCALE |
0 |
Standard/default font scale; equivalent to the Windows dialog font scale). |
NUL_FONTFACE$ |
"" |
Standard/default Windows font face; probably Arial or something similar. |
NUL_TOOLTIP$ |
"" |
No tooltip. |
NUL_PARENTID |
0 |
Default parent is either the current modal dialog, if there is one, else the main A-Shell window. |
NUL_WINCLASS$ |
"" |
Let window class be determined by ctype, ctype2. The only reason for using anything else here is when creating special control types known to Windows but not A-Shell. |
NUL_WINSTYLE, NUL_WINSTYLEX |
0 |
Standard/default control style flags. |
Definition file: ashell.def |
||
For example, to create a reasonably standard button control that you didn't need to reference by ID and had no other special attributes, you could code it with just these parameters:
xcall AUI, AUI_CONTROL, CTLOP_ADD, NUL_CTLID, "Click Me", NUL_CSTATE, MBF_BUTTON+MBF_KBD, "VK_xF101"
But if you want to add a tooltip, then you would need to specify several placeholder parameters; using the symbol names instead of literal values will make the code easier to read:
xcall AUI, AUI_CONTROL, CTLOP_ADD, NUL_CTLID, "Click Me", NUL_CSTATE, MBF_BUTTON+MBF_KBD, "VK_xF101", NUL_FUNC$, NUL_CSTATUS, 20, 50, 21, 60, NUL_FCG, NUL_BGC, NUL_FONTATTR, NUL_FONTSCALE, NUL_FONTFACE$, "Don't bet on the horses"
Another approach, which eliminates the need for placeholder parameters, would be to use named parameter syntax (based on the DEFXCALL definitions in xcall.def), e.g.:
xcall AUI, AUI_CONTROL, CTLOP_ADD, NUL_CTLID, "Click Me", cmd="VK_xF101", ctype=MBF_BUTTON+MBF_KBD, srow=20, scol=50, erow=21, ecol=60, tooltip="This is a tip"
Also See
