TEXT
A TEXT control merely displays some text. The user can't edit the text in any way. It's simply for the purpose of displaying text in a window.
Uses
Can be used to display instructions, or label things in a window, or display some message to the user.
Styles
A TEXT must be created with one of the following 5 styles:
Left | Left-justified text display with word wrap. |
Center | Centered text display with word wrap. |
Right | Right-justified text display with word wrap. |
No wrap | (NOWRAP) Left-justified text display without word wrapping. Text that extends past the end of a line is clipped. Tabs are expanded. |
Simple | Left-justified text display without word wrapping. You can't change the text with GuiSetCtlText. The control’s window must not process the CTLCOLOR event. Also, if the control is disabled, its text is not grayed. This style of text imposes the minimum overhead on redrawing. |
A TEXT may also have any, all, or none of the following styles:
Notify | Causes the Window Layout's DBLCLK or CLICK subroutines for this control to be called when the mouse is double-clicked or clicked on the text. |
No Prefix | (NOPREFIX) Doesn't translate a "&" character into an underline. |
Sunken | Makes a sunken border. |
End Ellipsis | (ENDELLIPSIS) If the end of a string does not fit in the control, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the control, it is truncated without ellipses. |
Path Ellipsis | (PATHELLIPSIS) Displays ellipsis within a filename if the name can't fully fit within the control. Replaces characters in the middle of the string with ellipses so that the result fits in the control. If the string contains backslash (\) characters, PATHELLIPSIS preserves as much as possible of the text after the last backslash. |
Word Ellipsis | (WORDELLIPSIS) Truncates any word that does not fit in the control and adds ellipses. |
Entry | The TEXT control duplicates the text-displaying characteristics of a multiline ENTRY. Specifically, the average character width is calculated in the same manner as with an ENTRY, and a partially visible last line is not displayed. |
No Sibling | (NOSIBLING) Prevents this control from drawing into any overlapping controls. |
Group | Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins). |
Disabled | Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement. |
Hide | Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement. |
Border | Has a border. |
Extra styles
A TEXT may have the following extra styles:
Quiet | Do not report any events for this control. |
Modal Frame | (MODALFRAME) Has a double border. |
Static Edge | (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input. |
Client Edge | (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge. |
Accept files | (FILES) Accepts drag-and-drop files (ie, the DROPFILES event). |
Align text right | (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties). |
Read right-to-left | (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right). |
Transparent | The control is to be transparent. Any controls that are beneath this one are not obscured. |
Events
A TEXT generates the following events:
Event name When it occurs CLICK The user has clicked on the text. Note: A disabled text does not cause a CLICK event. This event also does not occur if the NOTIFY style is not specified for the control. DBLCLK The user has double-clicked on the text. Note: A disabled text does not cause a DBLCLK event. This event also does not occur if the NOTIFY style is not specified for the control.
REXX Variable
A TEXT must have a REXX variable associated with it only if you specify the NOTIFY style, or you wish to be able to change its label or state (with GuiSetCtlPlacement). You do not need to initialize the variable before opening the window which contains the TEXT control.
Dynamically add/remove TEXT
You can dynamically add a TEXT control to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
TEXT X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, TextX and Y is the position of the top left corner of the control, relative to the window's top left corner.
Width and Height are the size of the control, in pixels.
Styles and ExtraStyles are those listed above, with each style separated by a | character.
VariableName is the variable name to be associated with the control. You can omit this if you do not need to later remove/modify the control, nor receive events from it.
Accelerator is the keyboard shortcut that causes the control to generate a CLICK event.
Text is the text displayed by the control. You can omit this field if you want the TEXT control initially blank, or if you intend to set the text with GuiAddCtlText(). You can use the two characters \t to represent a TAB character. You can also include multiple lines by using the characters \n to mark the end of a line. If you want to put a \ character in the text, then you must double it up as \\. Placing a & character before another character causes that second character to be underlined. (This is referred to as a "prefix". If you do not desire this behavior, use the NOPREFIX style).
Note: There is a limit of 255 characters for the Text field. If you need to set a longer string, then use GuiAddCtlText().
For example, here we add a TEXT control at an X Y position of 10, 10, with a width and height of 80 and 40, with the styles LEFT and NOPREFIX, extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MyText, and two lines of text:
error = GuiAddCtl("TEXT 10,10,80,40, LEFT|NOPREFIX, CLIENTEDGE|QUIET, MyText, Line 1\nLine 2")
You can dynamically remove a TEXT control by calling GuiRemoveCtl. Here we remove the above control:
error = GuiRemoveCtl("MyText")
Change a TEXT's contents.
You can dynamically change the text displayed by calling GuiAddCtlText. You pass the REXX variable name for the text control, and the new contents. Here we change the above TEXT's contents to Hello there:
error = GuiAddCtlText("MyText", "Hello there")To blank out the TEXT, omit the second arg:
error = GuiAddCtlText("MyText")