Definition
Define a portion of the screen to display bitmap images.
[enabled|disabled] [visible|invisible]
[[color] BCOLOR] [primary]
image region IR_NAME
size XSIZE YSIZE at {[position] X Y|default position}
[in PARENT_NAME1 [in PARENT_NAME2] ...]
[window size WINDOW_XSIZE WINDOW_YSIZE
at [position] WINDOW_X WINDOW_Y]
[[color] FCOLOR foreground]
[priority is PRIORITY_NO]
[parameter is PAR_STRING]
[[extended] 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] ]
[no scale|sample|preserve {foreground|background}]
[action bar AB_NAME]
[popup menu STANDALONE_PULLDOWN_NAME]
[minimize button [using MINIMIZE_ICON_FILE] ]
[maximize button]
[pointer [is] POINTER_FILE]
[file FILE_NAME [using IMAGE_MAP] ]
enabled | disabled
Define the image region as selectable or not. If you define it 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 BCOLOR
A string value, integer value, or color keyword representing an ESL color that you want to use for the background of the region. The default background BCOLOR is black.
Colors specified in IMAGE_MAP override the foreground and background colors.
primary
This is the program's primary region.
IR_NAME
The identifier for the image region.
size XSIZE YSIZE
Integer values representing the dimensions of the region's viewport in X Y coordinates of the parent. These refer to the dimensions of the viewport itself, and do not include the space occupied by the frame. The default size is the viewport size. To override the default window size, use the window size attribute.
at position X Y
Integer values representing the position of the 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 image region at the graphics cursor of the parent; otherwise, position the object at 0 0.
in PARENT_NAMEn
The identifier for a parent object. If the region is primary, you cannot specify ancestry; the region's parent is always in desktop. To place a region outside of a primary region, specify its ancestry as in desktop. The default ancestry for a non-primary region is in primary region.
window size WINDOW_XSIZE WINDOW_YSIZE
Integer values representing the dimensions of the region's window, in X Y coordinates of the object. The window defines the portion of the region's contents that is visible in the viewport.
at position WINDOW_X WINDOW_Y
Integer values representing the position of the region's window.
color FCOLOR 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 FCOLOR is white.
priority is PRIORITY_NO
An integer value representing the priority of the region. You cannot assign a priority to the primary region and regions whose ancestry is in desktop. The default priority is 0.
parameter is PAR_STRING
A string value representing the parameter of the region. The default parameter string 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. The default HELP_ID is "".
extended
This is the extended help panel ID for this region and its children.
border
Draw a border around the region. If you specify border or COLOR border, ESL draws a one-pixel border of the color indicated (white, by default). If you specify other frame attributes for the region, then the border specification will result in a one-pixel wide border in the Windows border color. Note that frame attributes or child of desktop causes ESL to ignore COLOR border.
size border
Surround the region with a sizing border that can be used to resize the region.
title bar TITLE_STRING
A string value representing the title that will appear in the region's title bar. The title bar can be used for repositioning the region.
system menu
The region will contain a system menu. The system menu button will be in the upper left-hand corner.
horizontal scroll bar
Include a scroll bar along the bottom edge of the region just inside the border, if one exists. Scroll the region's contents as specified by SCROLL_INC.
The horizontal scroll bar contains solid 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 units in the region's coordinate system by which you want the region's window position to change when one of the arrows in the scroll bar is pressed. When paging, the page increment is the X or Y window size minus one scroll increment. The default SCROLL_INC is one unit.
vertical scroll bar
Include a vertical scroll bar along the far right edge of the region just inside the border, if one exists. Scroll the region's contents as specified by SCROLL_INC.
The vertical scroll bar contains solid arrows and a slider, whether or not there is information outside the region's window.
no scale
Do not scale the region's contents when changing the region size (i.e., the window size is constrained by the viewport). When the size of the region is changed, its window size is changed in parallel. Resizing the region thus exposes or covers more of the region contents, rather than causing the contents to be rescaled to fit into the new size of the region. Note that the window size attribute will have no effect if you include this attribute.
sample
Perform scaling using the sample method, which arbitrarily selects the scan lines to be retained and discards the others without examining them. This is the default scaling method.
preserve foreground
Perform scaling, giving preference to preserving the foreground color.
preserve background
Perform scaling, giving preference to preserving the background color.
action bar AB_NAME
The identifier for an action bar template you want included. 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
Include a minimize button in the upper right-hand corner of the region.
using MINIMIZE_ICON_FILE
A string value representing the name, including the extension, of the file containing the icon to use when the region is minimized.
maximize button
Include a maximize button in the upper right-hand corner of the region. (The maximize button will turn into a restore button when the 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 region.
file FILE_NAME
A string value representing the name, including the extension, of the file you want to use for the image region's initial contents.
using IMAGE_MAP
The identifier for a previously defined image map, which maps the color of an image. Colors specified in IMAGE_MAP override the foreground and background colors.
Description
In a windowed application, the primary region must be the first object you define. There can be only one primary region. All other regions and keys are, by default, children of the primary region.
Only the region specification, the identifier, the size specifications, and the at [position] specification are required, and they must be specified in the order shown in the model. Other attributes are optional, using the defaults indicated.
Except for the file option, which must be specified last, any of the attributes after ancestry can be specified in any order.
When you define a region's size, you are actually defining two characteristics: the region's viewport and the region's window. You can also specify the window size separately.
When you specify a system menu and a minimize and/or maximize button, and do not specify a title bar, a title bar with the name of the program executable is added.
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.
Disabling a region disables its viewport and its frame, and also disables the region's children.
The scroll bars and slider are disabled when the window is empty.
Bitmap Files
An image region can read in the following file formats:
Microsoft Windows 3.0 bitmap files (16- and 256-color)
Two-color .PCX files may also be displayed.
We recommend that ESL for Windows applications do not display multiple windows that use different 256-color tables, as this will degrade the performance of your applications. The reason for this lies in the way that Windows manages color palettes. Because Windows has only one system palette, it must load a new logical palette each time your application displays a new window. This does not cause any degradation when using 16-color palettes, as they are all the same. 256-color palettes, however, may contain any of a near-infinite combination of shades. Therefore, Windows must reload the appropriate palette each time the application changes windows. You can use 16-color palettes in multiple windows simultaneously, or a single 256-color palette in combination with 16-color palettes, but do not use multiple 256-color palettes.
Example
enabled visible color 25 image region MyRegion_IR
size 465 275
at 90 20
color 8 foreground
size border
title bar "Image Region"
system menu
horizontal scroll bar scroll by 20
vertical scroll bar scroll by 20
no scale
minimize button using "ic2.ico"
maximize button
pointer is "SOLDER.PTR"
file "circuit2.bmp"
