| **Navigation:**  [[introduction.htm|Language Reference]] > 6 - Windows >====== WINDOW (declare a dialog window) ====== | [[application  declare an mdi frame window .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[menubar  declare a pulldown menu .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

{{newc7.jpg|NewC7.jpg}}

//label     //**WINDOW( **//'title //')  [,**AT( )**] [,**CENTER**] [,**SYSTEM**] [,**MAX**] [,**ICON( )**] [,**STATUS( )**] [,**HLP( )**]

| [,**CURSOR( )**] [,**MDI**] [,**MODAL**] [,**MASK**] [,**FONT( )**] [,**GRAY**][,**TIMER( )**] |
| [,**ALRT( )**] [,**ICONIZE**] [,**MAXIMIZE**] [,**MSG( )**] [,**PALETTE( )**] [,**DROPID( )**] [,**IMM**] |
| [,**AUTO**] [,**COLOR( )**] [,**TOOLBOX**] [,**DOCK( )**] [,**DOCKED( )**] [,**LAYOUT( )**] |

| [,| **TILED**| ] | [,| **HSCROLL**| ] | [,| **DOUBLE**| ] |
| | **CENTERED **| | | **VSCROLL **| | | **NOFRAME**| |
|  | | **HVSCROLL**| | | **RESIZE**| |

| [ **MENUBAR** |
| //menus and/or items// |
| **END** ] |
| [ **TOOLBAR** |
| //Controls// |
| **END** ] |
| //Controls// |
| **END** |

{{blk2blue.jpg|blk2blue.jpg}}

| **WINDOW** | Declares a document window or dialog box. |
| //label// | A valid Clarion label. A //label// is required. |
| //title// | A string constant containing the window's title text (PROP:Text). |
| **AT** | Specifies the initial size and location of the window (PROP:AT). If omitted, default values are selected by the runtime library. |
| **CENTER** | Specifies that the window's initial position is centered on screen relative to its parent window, by default (PROP:CENTER). This attribute takes effect only if at least one parameter of the AT** **attribute is omitted. |
| **SYSTEM** | Specifies the presence of a system menu (PROP:SYSTEM). |
| **MAX** | Specifies the presence of a maximize control (PROP:MAX). |
| **ICON** | Specifies the presence of a minimize control, and names a file or standard icon identifier for the icon displayed when the window is minimized (PROP:ICON). |
| **STATUS** | Specifies the presence of a status bar for the window (PROP:STATUS). |
| **HLP** | Specifies the "Help ID" associated with the window (PROP:HLP). |
| **CURSOR** | Specifies a mouse cursor to display when the mouse is positioned over the window (PROP:CURSOR). This cursor is inherited by the WINDOW's controls unless overridden on the individual control. |
| **MDI** | Specifies that the window conforms to normal MDI child-window behavior (PROP:MDI). |
| **MODAL** | Specifies the window is "system modal" and must be closed before the user may do anything else (PROP:MODAL). |
| **MASK** | Specifies pattern input editing mode of all entry controls in this window (PROP:MASK). |
| **FONT** | Specifies the default font for all controls in this window (PROP:FONT). |
| **GRAY** | Specifies that the window has a gray background for use with 3-D look controls (PROP:GRAY). |
| **TIMER** | Specifies periodic timed event generation (PROP:TIMER). |
| **ALRT** | Specifies "hot" keys active when the window has focus (PROP:ALRT). |
| **ICONIZE** | Specifies the window is opened as an icon (PROP:ICONIZE). |
| **MAXIMIZE** | Specifies the window is maximized when opened (PROP:MAXIMIZE). |
| **MSG** | Specifies a string constant containing the default text to display in the status bar for all controls in the window (PROP:MSG). |
| **PALETTE** | Specifies the number of hardware colors used for graphics in the window (PROP:PALETTE). |
| **DROPID** | Specifies the window may serve as a drop target for drag-and-drop actions (PROP:DROPID). |
| **IMM** | Specifies the window generates events whenever it is moved or resized (PROP:IMM). |
| **AUTO** | Specifies all window controls' USE variables re-display on screen each time through the ACCEPT loop (PROP:AUTO). |
| **COLOR** | Specifies a background color for the WINDOW and default background and selected colors for the controls in the WINDOW (PROP:COLOR). |
| **TOOLBOX** | Specifies the window is "always on top" and its controls never retain focus (PROP:TOOLBOX). |
| **DOCK** | Specifies a window with the TOOLBOX attribute is dockable (PROP:DOCK). |
| **DOCKED** | Specifies a window with the DOCK attribute is opened docked (PROP:DOCKED). |
| **LAYOUT** | Indicates the orientation of window controls and field sequence. A style of (1) essentially "flips" the window controls' display as a mirror image of the layout specified in the Window Formatter. Default field navigation moves from right to left. (PROP:LAYOUT) |
| **WALLPAPER** | Specifies the background image to display in the window's client area (PROP:WALLPAPER). The image stretches to fill the entire client area of the window unless the TILED or CENTERED attribute is also present. |
| **TILED** | Specifies the WALLPAPER image displays at its default size and is tiled to fill the entire client area of the window (PROP:TILED). |
| **CENTERED** | Specifies the WALLPAPER image displays at its default size and is centered in the entire client area of the window (PROP:CENTERED). |
| **HSCROLL** | Specifies a horizontal scroll bar is automatically added to the window when any scrollable portion of the window lies horizontally outside the visible area (PROP:HSCROLL). |
| **VSCROLL** | Specifies a vertical scroll bar is automatically added to the window when any scrollable portion of the window lies vertically outside the visible area (PROP:VSCROLL). |
| **HVSCROLL** | Specifies both vertical and horizontal scroll bars are automatically added to the window when any scrollable portion of the window lies outside the visible area. |
| **DOUBLE** | Specifies a double-width frame around the window (PROP:DOUBLE). |
| **NOFRAME** | Specifies a window with no frame (PROP:NOFRAME). |
| **RESIZE** | Specifies a thick frame around the window, which does allow window resizing (PROP:RESIZE). |
| **MENUBAR** | Defines a menu structure (optional). |
| //menus and/or items// | MENU and/or ITEM declarations that define the menu selections. |
| **TOOLBAR** | Defines a toolbar structure (optional). |
| //controls// | Control declarations that define tools available on the TOOLBAR, or the control fields in the WINDOW. |

A **WINDOW** declares a document window or dialog box which may contain controls, and may be used to display output to the user. When the WINDOW is first opened, it remains hidden until the first DISPLAY statement or ACCEPT loop is encountered. This enables any changes to be made to the appearance before it is displayed. Any previously opened WINDOW on the same execution thread is disabled. Events for the WINDOW are processed by the first ACCEPT loop encountered after the WINDOW is first opened.

A WINDOW automatically receives a single-width border frame unless one of the DOUBLE, NOFRAME, or RESIZE attributes are specified. Screen coordinates are measured in dialog units. A dialog unit is defined as one-quarter the average character width and one-eighth the average character height of the font specified in the WINDOW's FONT attribute (or the system font, if no FONT attribute is specified on the WINDOW).

A WINDOW with the MODAL attribute is system modal; it takes exclusive control of the computer. This means that any other progam running in the background halts its execution until the MODAL WINDOW is closed. Therefore, the MODAL attribute should be used only when absolutely necessary. Also, the RESIZE attribute is ignored, and the WINDOW cannot be moved when the MODAL attribute is present.

A WINDOW without the MDI attribute, when opened in an MDI program on an MDI execution thread, is application modal. This means that the user must respond before moving to any other window in the application. The user may, however, move to any other program running in Windows at the time. Non-MDI windows may be opened either before or after an APPLICATION is opened, and may be on the same execution thread as the APPLICATION or any MDI child window (application modal) or their own thread (not application modal).

A WINDOW with the MDI attribute is an MDI "child" window. MDI "child" windows are clipped to the APPLICATION frame and automatically moved when the frame is moved, and can be totally concealed by minimizing the parent APPLICATION. MDI "child" windows are modeless; the user may change to the top window of another execution thread, within the same application or any other application running in Windows, at any time. An MDI "child" window must not be on the same execution thread as the APPLICATION. Therefore, any MDI "child" window called directly from the APPLICATION must be in a separate procedure so the START procedure can be used to begin a new execution thread. Once started, multiple MDI "child" windows may be called in the new thread.

The MENUBAR specified in a WINDOW with the MDI attribute is automatically merged into the "Global menu" (from the APPLICATION) when the WINDOW receives focus unless either the WINDOW's or APPLICATION's MENUBAR has the NOMERGE attribute. A MENUBAR specified in a WINDOW without the MDI attribute is never merged into the "Global menu"--it always appears in the window itself.

The TOOLBAR specified in a WINDOW with the MDI attribute is automatically merged into the "Global toolbar" (from the APPLICATION) when the WINDOW receives focus, unless either the WINDOW's or APPLICATION's TOOLBAR has the NOMERGE attribute. The toolbar specified in a WINDOW without the MDI attribute is never merged into the "Global toolbar"--it always appears in the window itself.

A WINDOW with the TOOLBOX attribute is automatically "always on top" and its controls do not retain focus (just as if they all had the SKIP attribute). This creates a window whose controls all behave in the same manner as controls in the toolbar. Normally, a WINDOW with the TOOLBOX attribute would be executed in its own thread.

**Events Generated:**

| EVENT:PreAlertKey | The user pressed an ALRT attribute hot key. |
| EVENT:AlertKey | The user pressed an ALRT attribute hot key. |
| EVENT:CloseWindow | The window is closing. |
| EVENT:CloseDown | The application is closing. |
| EVENT:OpenWindow | The window is opening. |
| EVENT:LoseFocus | The window is losing focus to another thread. |
| EVENT:GainFocus | The window is gaining focus from another thread. |
| EVENT:Docked | A TOOLBOX window has been docked. |
| EVENT:Undocked | A TOOLBOX window has been undocked. |
| EVENT:Timer | The TIMER attribute has triggered. |
| EVENT:Move | The user is moving the window. CYCLE aborts the move. |
| EVENT:Moved | The user has moved the window. |
| EVENT:Size | The user is resizing the window. CYCLE aborts the resize. |
| EVENT:Sized | The user has resized the window. |
| EVENT:Restore | The user is restoring the window's previous size. CYCLE aborts the resize. |
| EVENT:Restored | The user has restored the window's previous size. |
| EVENT:Maximize | The user is maximizing the window. CYCLE aborts the resize. |
| EVENT:Maximized | The user has maximized the window. |
| EVENT:Iconize | The user is minimizing the window. CYCLE aborts the resize. |
| EVENT:Iconized | The user has minimized the window. |
| EVENT:Completed | AcceptAll (non-stop) mode has finished processing all the window's controls. |
| EVENT:DDErequest | A client has requested a data item from this Clarion DDE server application. |
| EVENT:DDEadvise | A client has requested continuous updates of a data item from this Clarion DDE server application. |
| EVENT:DDEexecute | A client has executed a DDEEXECUTE statement to this Clarion DDE server application. |
| EVENT:DDEpoke | A client has sent unsolicited data to this Clarion DDE server application. |
| EVENT:DDEdata | A DDE server has supplied an updated data item to this Clarion client application. |
| EVENT:DDEclosed | A DDE server has terminated the DDE link to this Clarion client application. |

**Related Procedures:**

[[accept  the event processor .htm|ACCEPT]], [[alert  set event generation key .htm|ALERT]], [[event  return event number .htm|EVENT]], [[post  post user defined event .htm|POST]], [[register  register event handler .htm|REGISTER]], [[unregister  unregister event handler .htm|UNREGISTER]], [[yield  allow event processing .htm|YIELD]], [[accepted  return control just completed .htm|ACCEPTED]], [[change  change control field value .htm|CHANGE]], [[choice  return relative item position .htm|CHOICE]], [[close  close a data structure .htm|CLOSE]], [[contents  return contents of use variable .htm|CONTENTS]], [[create  return new control created .htm|CREATE]], [[destroy  remove a control .htm|DESTROY]], [[disable  dim a control .htm|DISABLE]], [[display  write use variables to screen .htm|DISPLAY]], [[enable  re activate dimmed control .htm|ENABLE]], [[erase  clear screen control and use variables .htm|ERASE]], [[field  return control with focus .htm|FIELD]], [[firstfield  return first window control .htm|FIRSTFIELD]], [[focus  return control with focus .htm|FOCUS]], [[getfont  get font information .htm|GETFONT]], [[getposition  get control position .htm|GETPOSITION]], [[help  help window access .htm|HELP]], [[hide  blank a control .htm|HIDE]], [[incomplete  return empty req control .htm|INCOMPLETE]], [[lastfield  return last window control .htm|LASTFIELD]], [[message  return message box response .htm|MESSAGE]], [[mousex  return mouse horizontal position .htm|MOUSEX]], [[mousey  return mouse vertical position .htm|MOUSEY]], [[open  open a data structure .htm|OPEN]], [[popup  return popup menu selection .htm|POPUP]], [[select  select next control to process .htm|SELECT]], [[selected  return control that has received focus .htm|SELECTED]], [[set3dlook  set 3d window look .htm|SET3DLOOK]], [[setcursor  set temporary mouse cursor .htm|SETCURSOR]], [[setfont  specify font .htm|SETFONT]], [[setposition  specify new control position .htm|SETPOSITION]], [[settarget  set current window or report .htm|SETTARGET]], [[unhide  show hidden control .htm|UNHIDE]], [[update  write from screen to use variables .htm|UPDATE]]

**Example:**

** !MDI child window with system menu, minimize and maximize buttons, status bar,**

** ! scroll bars, a resizable frame, with menu and toolbar which are merged into the **

** !application's menubar and toolbar:**

**MDIChild ****WINDOW****('Child One'),MDI,SYSTEM,MAX,ICON('Icon.ICO'),STATUS,HVSCROLL,RESIZE**

**      MENUBAR**

**       MENU('File'),USE(?FileMenu)**

**        ITEM('Close'),USE(?CloseFile)**

**       END**

**       MENU('Edit'),USE(?EditMenu)**

**        ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)**

**        ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)**

**        ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)**

**        ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)**

**       END**

**       END**

**       TOOLBAR**

**       BUTTON('Cut'),USE(?CutButton),ICON(ICON:Cut),STD(STD:Cut)**

**       BUTTON('Copy'),USE(?CopyButton),ICON(ICON:Copy),STD(STD:Copy)**

**       BUTTON('Paste'),USE(?PasteButton),ICON(ICON:Paste),STD(STD:Paste)**

**       END**

**       TEXT,HVSCROLL,USE(Pre:Field)**

**       BUTTON('&OK'),USE(?Exit),DEFAULT**

**     END**

**!Non-MDI, system menu, maximize button, status bar, non-resizable frame,**

**NonMDI ****WINDOW****('Dialog Window'),SYSTEM,MAX,STATUS**

**        TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')**

**        BUTTON('&OK'),USE(?Exit),DEFAULT**

**       END**

**!System-modal window with non-resizable frame, with only a message and Ok button:**

**ModalWin ****WINDOW****('Modal Window'),MODAL**

**          IMAGE(ICON:Exclamation)**

**          STRING('An ERROR has occurred')**

**          BUTTON('&OK'),USE(?Exit),DEFAULT**

**         END**

**See Also:**

[[accept  the event processor .htm|ACCEPT]]

[[application  declare an mdi frame window .htm|APPLICATION]]