GuiCreateWindow()

Creates a window (and all of its controls) based upon the WINDOW definition in a GUI block.


Synopsis

error = GuiCreateWindow(Show, Parent)


Args

Show determines how (or if) the window is visually displayed.

Options Meaning
HIDE Hides the window and activates another window.
NORMAL Activates and displays the window. If minimized or maximized, the window is restored to its original size and position.
AMIN Activates the window and displays it as a minimized window.
AMAX Activates the window and displays it as a maximized window.
RESHOW Displays the window in its most recent size and position. The active window remains active.
ACTIVATE Activates the window and displays it as a minimized window.
MIN Minimizes the window and activates the next top-level window.
MIN2 Displays the window as a minimized window. The active window remains active.
SHOW Displays the window in its current state. The active window remains active.
RESTORE Activates and displays the window. If minimized or maximized, the window is restored to its original size and position. Your script should specify this when restoring a minimized window.
DEFAULT Sets the show state based on the preferred setting of the program used to launch your script.
FORCE Force the window minimized.

If Show is omitted, then it defaults to 'HIDE'. You can subsequently modify the window when GuiCreateWindow returns, and then call GuiSetCtlPlacement to show the window.

Parent is a handle to the parent window if this window is to be opened inside of another window, and will be automatically destroyed when its parent is destroyed. If omitted, then the window does not open inside of any other. If a -1, then the window is created modal, and the user must close the window before he can operate any other windows that your script has created.


Returns

If successful, an empty string is returned, and the variable named GuiWindow is set to the handle of the window. If an error occurs, GuiCreateWindow returns an error message.


Notes

If the GuiX and GuiY variables are set, then these override the X and Y positions specified for the window in the GUI block. If the GuiWidth and GuiHeight variables are also set, then these override the Width and Height specified for the window in the GUI block, and in this case, the values are expressed in window points (not Dialog Units) and include the entire window frame (ie, titlebar, border, and menu).

This must be called by a Window Layout script. It is typically called in the layout script's Create function if it is desired to create the window as soon as the main script calls CreateObject on that Window Layout script.

If you do not pass the Show arg, then GuiCreateWindow does not initialize it controls to be in sync with their associated REXX variables. You can sync them all by following up with a call to GuiSetCtlValue, passing no arguments to it. Typically, you will do this before called GuiSetCtlPlacement to show the window.

GuiCreateWindow may return the following error numbers/messages. If you choose to raise a condition, then from your CATCH instructions, you can use CONDITION('D') to fetch the message, and CONDITION('E') to fetch the number. Note that where you see part of a message enclosed within < and >, this will be replaced by some other, more detailed text in the error message.

Number Message
101Out of memory for this operation
102Object already has a window
103An existing object must call this function
105GUI block not found
106WINDOW definition not found in GUI block
107WINDOW x, y, width, and height must be whole numbers or omitted
108Control x, y, width, and height must be whole numbers
111FONT height and width must be whole numbers
114Not a defined type of control
115Error creating MENU heading <headingNum>
116Error creating MENU item <headingNum> : <itemNum>
117Error creating MENU item <headingNum> : <itemNum> : <subItemNum>
119Can't find the STRING definition named <name>
120STRING definition is missing its DEND
121Error adding the string: <string>
122Bad TREE position specified
123Item not found matching the value of <string>
124Error initializing the control <controlVariable>
125Error getting a line for <controlVariable>
126Error fetching the value for control <controlVariable>
127<controlVariable> low/high range must be numeric values
129Can't find the MENU definition named <name>
130MENU definition is missing its DEND
131Bad accelerator: <accelerator>
195Message will vary. It concerns GuiCreateWindow failing to add the menu to the window
198Message will vary. It concerns bad styles specified for some control in your WINDOW definition
199Message will vary. It concerns GuiCreateWindow failing to create the window