Window

Description: This function opens a new window, starts a module inside, and eventually returns the module's value.

Returns: Module Instance

Usage: Steady State

Format: Window(Left, Top, ViewWidth, ViewHeight, VirtualWidth, VirtualHeight, Module, Style, Title, Color, Enable [, HelpFileName, HelpContext, enableDynamicPositioning])

Parameters: Left { numeric } { required } { no default: }

Any numeric expression that gives the left coordinate of the new window. If the new window is a child window, Left is the user coordinate within the window of the calling module. If the new window is not a child window, Left is the number of pixels from the left of the screen.

Top { numeric } { required } { no default: }

Any numeric expression that gives the top coordinate of the new window. If the new window is a child window, Top is the user coordinate within the window of the calling module. If the new window is not a child window, Top is the number of pixels from the top of the screen.

ViewWidth { numeric } { required } { no default: }

Any numeric expression that gives the window width in pixels. The minimum width allowable is based on the operating system in use and the style options of the window (see the Comments section below for more details).

ViewHeight { numeric } { required } { no default: }

Any numeric expression that gives the window height in pixels. This value must be greater than or equal to 0.

VirtualWidth { numeric } { required } { no default: }

Any numeric expression that gives the width inside the new window in user coordinates (which may be pixels). If VirtualWidth is larger than the client area specified, a horizontal scroll bar appears.

VirtualHeight { numeric } { required } { no default: }

Any numeric expression that gives the height inside the new window in user coordinates (which may be pixels). If VirtualHeight is larger than the client area specified, a vertical scroll bar appears.

Module { Module } { required } { no default: }

Any expression that uses a module call. The module will start, and all graphics in the module will draw in the new window.

Style { numeric } { required } { no default: }

Any numeric expression that gives the style of the window when it opens. This parameter has no effect after the window has opened. Style is formed by adding together numbers from the table below:

Style	Bit Number	Description
1	0	Enable system close button (if bit 1 is set)
2	1	Show title bar
4	2	Thick border, not resizable
8	3	Thin border, not resizable
16	4	Enable minimize button (if bit 1 is set )
32	5	Enable maximize button (if bit 1 is set)
64	6	Create window minimized (as icon)
128	7	Create window maximized (full virtual size)
256	8	Disable scroll bars
512	9	Child window
1024	10	Always on top
2048	11	Reserved for future use
4096	12	Modal window (like dialog box)
8192	13	Use pixel coordinates in window (otherwise user coordinates)
16384	14	Use Load statement to size window
32768	15	Owned window
65536	16	Initially inactive window
131072	17	Invokes "automatic" alpha blending, where the window is set to be 50% translucent when inactive and opaque when active
262114	18	Window is to be rendered as transparent, with whatever color is specified as the background color being the transparent color.
524288	19	Indicates that a WindowClose statement will be associated with this window. See WindowClose for more details.
1048576	20	Force the window to remain at a fixed aspect ratio

Notes on the style settings:

• The default window (if Style is set to 0) has a thick border and is resizable.

• If bit 1 is not set, the title bar is not shown, and bits 0, 4 and 5 have no effect.

• If bits 2 and 3 are both set, there will not be a border unless bit 1 is set, in which case there will be a thin border. If neither bit 2 nor bit 3 is set, the border will be a resizable thick border.

• Bits 4 and 5 specify whether minimize and maximize buttons are disabled, rather than specifying whether they are visible (both the minimize and maximize buttons will be either visible or not visible). Furthermore, these options have no effect without bit 0 being set (except under Windows NT 3.51); the system close button must be enabled for the user to have any control over the minimize and maximize buttons.

• Setting bit 8 disables the scroll bars that are normally shown if the window has been resized (smaller). In this case, the entire window must be enlarged to its original size if you wish to view its contents.

• Bit 9 (child window) specifies a "window within a window". The new window is another graphic object within the calling window and is truncated by the borders of the parent window. This means that as the parent window is dragged, the child stays on top of the parent window in the same position within and relative to the parent's borders. If the parent window is minimized, then the child window is also minimized. Child windows do not produce status line title-windows. It is impossible to make a window a child window if the Window statement is in a module that isn't running in a window already. A child window is always an owned window.

• Setting bit 12 means that the window will take all of the input until closed. Care should be taken when using this option in conjunction with bit 14 (size based on load); a problem will occur if the load file cannot be found, and the window will not show up but will still be modal. The result is that the system will take no input until the window is closed.

• Setting bit 14 hides the window until a Load statement is executed in Module. The window is then opened in the size required to display the loaded bitmap.

• Bit 15 (owned window) creates a window that is always in front of the calling window. Unlike child windows, which are controlled by their parents, owned windows are not restricted by their owner's boundaries, nor does the movement of the parent window change their position. The exception to this, however, is that if the owning window is minimized, the owned window will also be minimized. Owned windows do not produce status line title-windows. Although all child windows are owned, not all owned windows are child windows.

• Bit 17. An alpha-blended window is one that has an alpha channel set up in the final renderer, resulting in a translucent effect to the window (i.e. it behaves like a normal window, except that you can see through the window to some degree. The degree of translucency ranges from zero (invisible) to 255 (completely opaque, just like a normal window). Setting bit 17 on your Window statement invokes "automatic" alpha blending, where the window is set to be 50% translucent when inactive and opaque when active. This is useful for dialogs that are non-modal and always on-top, so that when another window is active, you can see through to the underlying windows. If you need a finer degree of control on this, do not set bit 17, but use a new value for the "Option" parameter of WindowOptions (9) and set the WindowOptions "OptValue" parameter to the degree of alpha-blending that you wish (0 to 255). Note that these effects DO NOT work with child windows. Also note that these effects are NOT designed for animation purposes are not sufficiently efficient for this. The amount of processing power required to redraw one of these windows depends on the rating of the graphics card in your machine. The newer and faster the better.

• Bit 18. A transparent window is one that has a transparent background. The intended use for this is to allow the display of non-rectangular windows, by rendering the background as transparent and allowing mouse messages (movement and clicks) to "drill-through" the transparent area. The simplest way to create a transparent window is to specify a background color less than zero (-1, for example). The underlying implementation, however, requires that a specific color is used as a "key" color. All pixels of that color in the otherwise rectangular screen area that the window occupies are rendered as transparent. Using a background color of < 0 results in the key color being black [i.e. RBG(0, 0, 0)] and the window background being set to that color. It may well be that you wish to have black as a color in your window, however. Therefore, setting bit 18 in the Window statement also announces that this window is to be rendered as transparent, with whatever color is specified as the background color being the transparent color.

A WinXLoc/WinYLoc statement for the new window registers the values for the parent window when the mouse is over the parent and not itself, and will register the values for itself when the mouse is over it. The same is also true for the parent (it will see the values for the child window when the mouse is over the child).

Title { text } { required } { no default: }

Any text expression that gives the window title.

Color { numeric } { required } { no default: }

Any numeric expression that gives the background color of the window's client area when the window opens. This parameter has no effect after the window has opened.

Enable { Boolean } { required } { no default: }

Any logical expression. If true, the window opens and Module starts. If false, the window is closed and Module is stopped.

HelpFileName { text } { optional } { default: see note }

Optional file name of the help file to use if the user presses F1 while this window is the active window. If absent or invalid when the user presses F1, the parent window will be checked for a file name. This continues recursively until the top of the window tree is reached. If no help file name is found, the default help file is used. The default help file can be set through the Setup.ini variable WEBHelp, or by using the EnableHelp statement.

HelpContext { numeric } { optional } { no default: }

Optional help context. If absent or invalid, but the HelpFileName is valid, then the "finder" dialog for help is displayed when the user presses F1. If valid and numeric, the help file is searched for a matching topic number and help is displayed for that topic. If valid and textual, the help file is searched for an exact match on the text string among the topic index of the help file. If there is more than one text match, the index is positioned at the first partial string match. If valid but a topic match is not found (neither textual nor numeric), the same action as an Invalid HelpContext is taken. If the HelpFileName parameter is Invalid, this parameter is ignored.

enableDynamicPositioning { Boolean } { optional } { default: false }

An optional parameter that, when set to TRUE, will cause the window position to be updated if the window is a child window inside a GUITransform that moves, or if the LEFT or TOP parameters change. Set to FALSE by default.

Comments: This function returns the value returned by Module.

When a window is maximized, its maximized size is not based on the size of the screen, although for many commercial applications the two are the same, but rather, its full size is defined by the fifth and sixth parameters, namely virtual width and height. If the view area and the virtual area of the window have been defined to be the same, selecting the maximize button will appear to have no effect.

The minimum size of a window is based on the operating system under which the application is running, as well as the attributes of the window itself as defined by the Style parameter. The width need only be greater than or equal to 0. Window heights similarly need only be greater than or equal to 0.

Example:

Window(250, 200 { Top left corner },

210, 280 { View width and height },

210, 280 { Virtual width and height },

DialogBox() { Module to run in window },

1+2+8+8192+32768 { System menu button, thin border,

title, pixel coords, owned window },

"Grid Options" { Window title },

15 { Color is white },

boxOpen { Opens the window });

When boxOpen becomes valid and non-zero, this statement will open a window, and run the module DialogBox in it. If at any point boxOpen becomes 0, the window will immediately close and execution of the module will cease.