UpdatedDecember 2013; see History
Static text controls are the simplest kind of controls, consisting just of a text string formatted within a rectangular area, with an optional click notification. You may adjust the font and color, but in most cases, will just want to use the default font and color to get the most uniform, Windows-like look.
In the main window, static text controls correspond to PRINT statements and use the same coordinate system. In dialogs, ordinary PRINT statements are not permitted, and multiple coordinate systems are available (see Dialog Positioning) but otherwise the following discussion applies to static text controls in all contexts unless otherwise noted.
The simple PRINT statement:
PRINT TAB(10,5);"Customer Name:";
would correspond to this static text object:
xcall AUI, AUI_CONTROL, CTLOP_INFO, ID, "Customer Name:", MBST_ENABLE, MBF_STATIC + MBF_LFJUST, "", "", STATUS, 10, 5, 10, 19
This probably seems like overkill, but before addressing that, we should first clarify some subtle distinctions between the standard text and static text control implementations.
• Because the text and GUI layers in the main window use the same coordinate system, in both cases, the message starts in the same location (row 10, column 5). Also, since we set the ending column of the GUI version to 19, both will occupy the same amount of space. (This fact is important in converting from the fixed pitch to proportional font layouts. But, although the static text control occupies the same amount of space as the text counterpart, some of that space may appear blank (depending on the size of the font and how much difference there is between the fixed and proportional font metrics for this particular string. Typically, lower case characters will take up much less space in a proportional font than in a fixed pitch font, but the reverse may be true with all upper case. So if your text prompts are all upper case, you may need to allow more room (or convert them to lower case, or add the font parameters to the AUI CONTROL call to adjust the font to fit.)
• Because the proportional version of the character string will not appear to take up the same amount of space as the fixed pitch text version, attempts to position adjacent messages based on columnar calculations will not work very well in the proportional environment. See the section on Text Message Tokenization for further comments.
• In the above example, we did not define a command to be associated with clicking on this static text object, but we easily could, in which case the static text object acts like a button. To define a click event, add the MBF_KBD (or MBF_CMDLIN or MBF_SHLEXC flag) to the ctype parameter and put the string to be sent (or executed) in the cmd parameter. You may also want to add a tooltip so the user knows what to expect when clicking.
• Although (in the main window) the static text object exists in a layer above the standard text layer (and thus would obscure anything below it), as a convenience, it may be deleted by the same kinds of Print Tab operations that would delete the text version.
• If your screen prompts are parameterized (loaded from a file and output using a centralized routine), then converting from the PRINT version to the AUI CONTROL version will be simple. But if you have thousands of literal PRINT statements throughout your programs, you might want to consider one of the following shortcuts:
• PRINT statements may be replaced one-to-one with TPRINT statements, which, when compiled with the /X:2 switch, are equivalent to the AUI CONTROL shown above. That is, every segment or argument to a TPRINT statement will be converted to a separate static text control starting in the position it would have in the fixed pitch environment, and occupying the same frame space (although likely with some trailing space at the right edge of the frame.) When compiled without /X:2, TPRINT statements revert to PRINT.
• PRINT statements may also be replaced with DPRINT or EPRINT statements, which are similar to TPRINT except use the MBF_SUNKEN and MBF_EDIT styles, respectively, both of which work well to separate data fields from labels.
• SET AUTOTPRINT may be used prior to running a program to automatically treat all PRINT statements like TPRINT. This method provides the fastest way to see how well your screen layouts behave with proportional fonts.
• PRINT TAB(-10,AG_CONTROL); TEXT$; chr(127) is equivalent to TPRINT TEXT$. The advantage of the AG_CONTROL approach is that it eliminates any compiler dependency (i.e. you could compile under AMOS, or use the same RUN under both AMOS and A-Shell). You would probably need to modify your AMOS terminal driver to filter out the trailing chr(127), or perhaps ideally, to send the necessary escape sequence so that an ATE client could understand the command just as A-Shell/Windows would have.
• Tab(x,y);expr$ statements may be replaced with Tab(x,y,z);expr$ where the z parameter can be used to invoke a previously defined set of attributes to associate with the string expression (converting it into a GUI control object). See MX_DEFTABXYZ for details.
Additional Static Text Control Notes
Justification: When using AUI_CONTROL, the default justification is centered, but all of the shortcuts listed above automatically set left justification. The AG_CONTROL option supports a second two-character argument of which the first character sets the style ("T" for TPRINT or "D" for DPRINT), and the second character sets the justification ("L", "C", or "R").
Auto-expand: When using AUI_CONTROL to create a static text control, you can add the MBF_AUTOGROW flag to ctype to allow the control to grow as needed (both to handle the case of unexpectedly wide characters or a dynamic/unpredictable amount of text.)
Wrap: Static text controls automatically wrap, although this is typically only applicable when using the AUI_CONTROL syntax, since it allows you to adjust the height to make room for multiple rows of text.
Font: If not specified explicitly, via the fontface, fontattr or fontscale parameters of AUI_CONTROL, the font face is set according to the global Settings > Font > Control menu option. The size (for main window static text controls) is determined by the Settings > Misc Settings Proprtional font scaling option. (If 0, it uses the standard Windows desktop font, otherwise it applies the specified scale to the grid cell size.) For static text controls within dialogs, the Settings > Dialog Sizing > Font Scaling factor is applied to the standard Windows dialog font size.
History
2013 December, A-Shell 6.1.1371: Static text controls without images can now have context menus attached, with or without the hover/auto-show feature. Use the same syntax as documented in the tooltip parameter for image controls.