7. StdWindow
Prev |  | Next

## 7. StdWindow

In the Object I/O library there are two main window types:

`data Dialog c ls ps = Dialog Title (c ls ps) [WindowAttribute ls ps]`

  The dialogs are nonresizable modal or nonmodal windows. They adjust their size to the common size of the contained controls. They usually have two special buttons called `Ok` and `Cancel`. When the user presses Enter or Esc keys, the dialog interprets this event as clicking on `Ok` or `Cancel`.

`data Window c ls ps = Window Title (c ls ps) [WindowAttribute ls ps]`

  The windows are resizable and one can draw in the view domain.This can be programmed as a Haskell's function. They also can have vertical and horizontal scroll bars, which extend logical view frame of the windows.

Both windows and dialogs can contain various kinds of controls but they can't contain other windows or dialogs. The type variable `c` mentioned above corresponds to the type of the containing controls.

The type variables `ls` and `ps` as usual define local state and process state types.

`WindowAttribute` defines a set of built-in window attributes.

    data    WindowAttribute ls ps                        -- Default:
             --     Attributes for Windows and Dialogs:
             =      WindowActivate   (GUIFun ls ps)              -- id
             |      WindowClose      (GUIFun ls ps)              -- user can't close window
             |      WindowDeactivate (GUIFun ls ps)              -- id
             |      WindowHMargin    Int Int                     -- system dependent
             |      WindowId         Id                          -- system defined id
             |      WindowIndex      Int                         -- open front-most
             |      WindowInit       (GUIFun ls ps)              -- no actions after opening window
             |      WindowInitActive Id                          -- system dependent
             |      WindowItemSpace  Int Int                     -- system dependent
             |      WindowOuterSize  Size                        -- screen size
             |      WindowPos        ItemPos                     -- system dependent
             |      WindowViewSize   Size                        -- screen size
             |      WindowVMargin    Int Int                     -- system dependent
             --     Attributes for Dialog only:
             |      WindowCancel     Id                          -- no cancel  (Custom)ButtonControl
             |      WindowOk         Id                          -- no default (Custom)ButtonControl
             --     Attributes for Windows only:
             |      WindowCursor     CursorShape                 -- no change of cursor
             |      WindowHScroll    ScrollFunction              -- no horizontal scrolling
             |      WindowKeyboard   KeyboardStateFilter SelectState (KeyboardFunction ls ps) -- no keyboard input
             |      WindowLook       Bool Look                   -- show system dependent background
             |      WindowMouse      MouseStateFilter SelectState (MouseFunction ls ps) -- no mouse input
             |      WindowOrigin     Point2                      -- left top of picture domain
             |      WindowPen        [PenAttribute]              -- default pen attributes
             |      WindowSelectState       SelectState          -- Able
             |      WindowViewDomain        ViewDomain           -- {zero,max range}
             |      WindowVScroll           ScrollFunction       -- no vertical scrolling

### 7.1. Windows creation.

If the user wants to define his/her own window types, there are polymorphic creation functions.

    class Windows wdef where
            openWindow :: ls -> wdef ls ps -> ps -> GUI ps ps

    class Dialogs ddef where
            openDialog :: ls -> ddef ls ps -> ps -> GUI ps ps
            openModalDialog :: ls -> ddef ls ps -> ps -> GUI ps (ps, (Maybe ls))

The user must define instances of Windows or Dialogs classes for his/her own window or dialog types. Built-in types have instances defined as:

    instance Controls c => Dialog (Dialog c)
    instance Controls c => Window (Window c)

where `Controls` type class has instances for all types of controls.

### 7.2. Windows closing.

    closeWindow :: Id -> GUI2Fun ps
    closeActiveWindow :: GUI2Fun ps

`closeWindow`

  closes window with specified Id

`closeActiveWindow`

  closes active window. Often we can use `closeActiveWindow` together with WindowClose attribute. For example adding

      WindowClose (noLS
                  closeActiveWindow)

  to the window attributes list closes the window when the user clicks the close button.

### 7.3. Getting and setting active window

    setActiveWindow :: Id -> GUI ps ()
    getActiveWindow :: GUI ps (Maybe Id)

`setActiveWindow`

  activates window with specified Id

`getActiveWindow`

  returns Id of active window if it exists.

### 7.4. Getting and setting active control inside a window

    setActiveControl :: Id -> GUI ps ()
    getActiveControl :: GUI ps (Maybe Id)

`setActiveControl`

  activates control with specified Id.

`getActiveControl`

  returns Id of active control if it exists.

### 7.5. Stacking order

    stackWindow :: Id -> Id -> GUI ps ()
    getWindowStack :: GUI ps [(Id,WindowKind)]
    getWindowsStack :: GUI ps [Id]
    getDialogsStack :: GUI ps [Id]

`stackWindow`

  `stackWindow id1 id2` stacking window with id1 before window with id2.

`getWindowStack`

  returns list of window and dialog ids in stacking order.

`getWindowsStack`

  returns list of window ids in stacking order.

`getDialogsStack`

  returns list of dialog ids in stacking order.

### 7.6. Window margins

Getting values of default horizontal and vertical window margins and control item space

    getDefaultHMargin :: Bool -> GUI ps Int
    getDefaultVMargin :: Bool -> GUI ps Int
    getDefaultItemSpace :: GUI ps (Int,Int)

Getting values of current horizontal and vertical window margins and control item space

    getWindowHMargin :: Id  -> GUI ps (Maybe (Int,Int))
    getWindowVMargin :: Id  -> GUI ps (Maybe (Int,Int))
    getWindowItemSpace :: Id -> GUI ps (Maybe (Int,Int))

Current values are defined with `WindowHMargin`, `WindowVMargin`, `WindowItemSpace`

### 7.7. Enable/Disable Window, Keyboard and Mouse

The following functions correspond to WindowSelectState attribute:

    enableWindow :: Id -> GUI ps ()
    disableWindow :: Id -> GUI ps ()
    getWindowSelectState :: Id -> GUI ps (Maybe SelectState)

`enableWindow`

  enables window with specified Id

`disableWindow`

  disables window with specified Id

`getWindowSelectState`

  returns current select state

The following functions correspond to WindowMouse attribute

    enableWindowMouse  :: Id -> GUI ps ()
    disableWindowMouse :: Id -> GUI ps ()

    setWindowMouseSelectState :: SelectState -> Id -> GUI ps ()
    getWindowMouseSelectState :: Id -> GUI ps (Maybe SelectState)

    getWindowMouseStateFilter :: Id -> GUI ps (Maybe MouseStateFilter)
    setWindowMouseStateFilter :: Id -> MouseStateFilter -> GUI ps ()

`setWindowMouseSelectState`

  set current select state for mouse events

`enableWindowMouse`

  enables receiving mouse events for a window with a specified Id

      enableWindowMouse =
                  setWindowMouseSelectState Able

`disableWindowMouse`

  disables receiving mouse events for a window with a specified Id

      disableWindowMouse =
                  setWindowMouseSelectState Unable

`getWindowSelectState`

  returns current mouse select state

`getWindowMouseStateFilter`, `setWindowMouseStateFilter`

  Receiving mouse event can be additionally disabled with specified MouseStateFilter

The following functions correspond to WindowKeyboard attribute

    enableWindowKeyboard  :: Id -> GUI ps ()
    disableWindowKeyboard :: Id -> GUI ps ()

    setWindowKeyboardSelectState :: SelectState -> Id -> GUI ps ()
    getWindowKeyboardSelectState :: Id -> GUI ps (Maybe SelectState)

    getWindowKeyboardStateFilter :: Id -> GUI ps (Maybe KeyboardStateFilter)
    setWindowKeyboardStateFilter :: Id -> KeyboardStateFilter -> GUI ps ()

`setWindowKeyboardSelectState`

  sets current select state for keyboard events

`enableWindowKeyboard`

  enables receiving keyboard events for a window with a specified Id

      enableWindowKeyboard = setWindowKeyboardSelectState Able

`disableWindowKeyboard`

  disables receiving keyboard events for a window with a specified Id

      disableWindowKeyboard = setWindowKeyboardSelectState Unable

`getWindowKeyboard`

  returns current keyboard select state

`getWindowKeyboardStateFilter`, `setWindowKeyboardStateFilter`

  Receiving of keyboard event can be additionally disabled with specified KeyboardStateFilter

### 7.8. Drawing

Every window can have its own WindowLook attribute, which describes its Look function. The Look is defined as the type `SelectState -> UpdateState -> Draw ()` and this function is called every time when the window needs to be redrawn

The current look can be accessed by the following functions:

    setWindowLook :: Id -> Bool -> (Bool,Look) -> GUI ps ()
    getWindowLook :: Id -> GUI ps (Maybe (Bool,Look))

Use `updateWindow` to force window redrawing

    updateWindow :: Id -> Maybe ViewFrame -> GUI ps ()

We can also draw directly in the window with `drawInWindow` function but in this case everything displayed with `drawInWindow` will be erased after the next updateWindow call.

    drawInWindow :: Id -> Draw x -> GUI ps (Maybe x)

See Section 10, “StdPicture” for details about drawing.

### 7.9. Window positioning and window resizing

    setWindowPos :: Id -> ItemPos -> GUI ps ()
    getWindowPos :: Id -> GUI ps (Maybe Vector2)

`setWindowPos`

  positions the specified window to a given position

`getWindowPos`

  returns current window position

    moveWindowViewFrame :: Id -> Vector2 -> GUI ps ()
    getWindowViewFrame :: Id -> GUI ps ViewFrame

`ViewFrame` is the current visible `Rectangle` of the window. When there are horizontal and vertical scroll bars, then the changing of the scroller thumb changes the ViewFrame.`getWindowViewFrame` returns the current ViewFrame and `moveWindowViewFrame` moves it through the specified vector.

    setWindowViewSize :: Id -> Size -> GUI ps ()
    getWindowViewSize :: Id -> GUI ps Size

`ViewSize` is the current inner size of the window (It doesn't include the title bar and the scrollers' area). The above functions get/set the current ViewSize value.

    setWindowOuterSize :: Id -> Size -> GUI ps ()
    getWindowOuterSize :: Id -> GUI ps Size

`OuterSize` is the current full window size. The above functions get/set the current OuterSize value.

    setWindowViewDomain :: Id -> ViewDomain -> GUI ps ()
    getWindowViewDomain :: Id -> GUI ps (Maybe ViewDomain)

`ViewDomain` is a `Rectangle` which specifies the logical drawing area of the window. The above functions get/set the current ViewDomain value.

### 7.10. Windows scrolling

    setWindowScrollFunction :: Id -> Direction -> ScrollFunction -> GUI ps ()
    getWindowScrollFunction :: Id -> Direction -> GUI ps (Maybe ScrollFunction)

The ScrollFunction describes the behaviour of the horizontal or vertical (according to `Direction` parameter) scroll bars. The ScrollFunction calculates the step by which ViewFrame is moved inside the ViewDomain.

### 7.11. Mouse cursor

    setWindowCursor :: Id -> CursorShape -> GUI ps ()
    getWindowCursor :: Id -> GUI ps (Maybe CursorShape)

The `CursorShape` describes the shape of the mouse cursor when it is over the window.

### 7.12. Window title

    setWindowTitle :: Id -> Title -> GUI ps ()
    getWindowTitle :: Id -> GUI ps (Maybe Title)

`Title` is a string, which is displayed at the top of the window. The title can also be defined with the WindowTitle attribute.

### 7.13. Dialogs: Ok and Cancel buttons

    getWindowOk :: Id -> GUI ps (Maybe Id)
    getWindowCancel :: Id -> GUI ps (Maybe Id)

The above functions return Ids of Ok and Cancel buttons of the specified dialog. These Ids must be defined with WindowOk and WindowCancel attributes.

Prev |  | Next
6. StdId | Home | 8. StdControl