Definition
Define a textual region.
[enabled|disabled] [visible|invisible]
[[color] COLOR] [primary] [colored]
textual region TR_NAME
{size XSIZE YSIZE|window size COLUMNS columns LINES lines}
at {[position] X Y|default position}
[ in PARENT_NAME1 [in PARENT_NAME2] ... ]
[[color] COLOR foreground]
[priority is PRIORITY_NO]
[parameter is PAR_STRING]
[helpid is HELP_ID]
[[size| [color] COLOR] border]
[title bar TITLE_STRING]
[system menu]
[horizontal scroll bar [scroll by SCROLL_INC] ]
[vertical scroll bar [scroll by SCROLL_INC] ]
[action bar AB_NAME]
[popup menu STANDALONE_PULLDOWN_NAME]
[minimize button [using MINIMIZE_ICON_FILE] ]
[maximize button]
[pointer [is] POINTER_FILE]
[font FONT_NAME]
[TEXT_DRAWING_STATEMENT] ...
enabled | disabled
Define the textual region as selectable or not. If you define the textual region as disabled, it is displayed grayed and cannot be selected. The default is enabled.
visible | invisible
A visible object is displayed when it is defined. An invisible object is not displayed until you specifically make it visible. The default is visible.
color COLOR
A string value, integer value, or color keyword representing an ESL color that you want to use for the background of the textual region. The default is black.
primary
This textual region is the program's primary region.
colored
This is a colored textual region. Note that you cannot use colors 26 and 27 in a colored textual region.
TR_NAME
The identifier for a textual region.
size XSIZE YSIZE
Integer values representing the dimensions of the textual region's viewport in the parent's coordinate system. These refer to the dimensions of the viewport itself, and do not include the space occupied by the region's frame.
window size COLUMNS columns LINES lines
Integer values representing the number of columns and lines of the window in the textual region's coordinate system. The viewport size in X Y coordinates is inferred from the window size.
at X Y
Integer values representing the position of the textual region's viewport in the parent's coordinate system (not the position of the outside frame).
at default position
When the parent is a graphical region, position the object at the graphics cursor of the parent; otherwise, position the object at 0 0.
in PARENT_NAMEn
The identifiers for a parent object. If the textual region is the primary region, you cannot specify ancestry; it is always in desktop. To place a textual region outside of a primary region, specify its ancestry as in desktop. The default ancestry for a windowed application is in primary region; for a fullscreen application, it is in master.
COLOR foreground
A string value, integer value, or color keyword representing an ESL color that you want to use for the foreground of the region. The default foreground COLOR is white.
priority is PRIORITY_NO
An integer value representing the priority of the region. The primary region and regions whose ancestry is in desktop cannot be assigned a priority. The default priority is 0.
parameter is PAR_STRING
A string value representing the parameter of the region. The default is "".
helpid is HELP_ID
A string or integer value representing the identifier of the help panel you want displayed when the user requests help for this region. This should match the help panel defined in the library specified by the help library declaration.
size border
Surround the textual region with a sizing border that can be used to resize the region.
COLOR border
The type of border you want placed around the textual region. If you specify border or COLOR border, ESL draws a one-pixel border of the color indicated (white, by default). If other frame attributes are specified for the region, then the border specification will cause a one-pixel wide border in the Windows or PM border color to be displayed. Note that frame attributes or desktop children cause ESL to ignore COLOR border.
title bar TITLE_STRING
A string value representing the title that will appear in the textual region's title bar. This will generate a title bar that can be used for repositioning the region.
system menu
Specifies that the textual region will contain a system menu. The system menu button will be in the upper left corner.
horizontal scroll bar
Put a scroll bar along the bottom edge of the textual region just inside the border, if one exists. The textual region's contents will be scrolled as specified by SCROLL_INC.
The horizontal scroll bar will contain arrows and a slider, whether or not there is information outside the region's window.
scroll by SCROLL_INC
An integer value representing the number of columns (if horizontal scroll) or number of lines (if vertical scroll) by which the textual region's window position will be changed when one of the arrows in the scroll bar is pressed. The defaults are one column (horizontal scroll) and one line (vertical scroll).
vertical scroll bar
Place a scroll bar along the right edge of the textual region just inside the border. The textual region's contents will be scrolled as specified by SCROLL_INC.
The vertical scroll bar will contain arrows and a slider, whether or not there is information outside the region's window.
action bar AB_NAME
The identifier for an action bar template. Only those regions that are children of the desktop can have action bars.
popup menu STANDALONE_PULLDOWN_NAME
The identifier for the standalone pulldown template.
minimize button
Put a minimize button in the upper right corner.
using MINIMIZE_ICON_FILE
A string value representing the name, including the extension, of the file containing the icon to use when the textual region is minimized.
maximize button
Put a maximize button in the upper right corner. (The maximize button will turn into a restore button when the textual region is maximized.)
pointer is POINTER_FILE
A string value representing the name, including the extension, of the file containing the bitmap to use as a pointer whenever the pointer is over this textual region.
font FONT_NAME
The name of the font you want used in the region. You may use either system or ESL fonts. (See the description of the font is Font Reference Definition.) The default font is medium.
TEXT_DRAWING_STATEMENT
A textual drawing statement.
Description
In a windowed application, the primary region must be the first object you define.
Only the textual region specification, the identifier, the size specifications, and the at specification are required, and you must specify them in the order shown in the model. Other attributes are optional, using the default values shown.
A textual region cannot be the ancestor of any object.
When you specify a system menu, minimize and/or maximize button, and do not specify a title bar, a title bar with the name of the program executable is added.
ESL disables the scroll arrows and the slider when the window is empty.
When you define a textual region's size or window size, you are actually defining two characteristics: the region's viewport and the region's window. The region's viewport and window are always the same size. There is no scaling.
The region size only includes the area of the viewport itself. It does not include the frame attributes, which are external to the viewport. If the size of the primary region is the same as the screen size, you will not be able to see any frame attributes.
Textual regions without frame attributes (such as title bar, scroll bar, etc.) will not display partially clipped lines and columns.
Disabling a region disables its viewport and its frame.
For colored textual regions, the color specifications in the definition are for the background and foreground of the entire textual region. The color specifications for individual characters in a colored textual region override the color specifications in the definitions. To specify colors for individual characters, use either the make segment or make block action statement, or the CText module.
Colors 26 and 27 cannot be used in a colored textual region.
Specifying size causes the number of columns and lines to be determined based on font size.
The maximum size of a textual region is 32K lines, at a maximum of 32K per line.
Example
In this example, color 26 picks up the Windows window background color, and color 27 picks up the Windows window foreground color.
enabled visible color 26 textual region Information_TR
size 260 160
at position 140 95
in desktop
color 27 foreground
size border
title bar "Text Window"
system menu
horizontal scroll bar scroll by 6
vertical scroll bar scroll by 16
action bar Information_AB
minimize button using "TEXT.ICO"
maximize button
pointer is "TEXT.PTR"
