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.