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