R3 View - Windowing System

R3 Graphical User Interface (GUI)

Concepts

The R3 View System handles windowing, events, popups, requestors, and modal operations. It is responsible for opening new windows on the screen and handling their events.

The windowing part of the system is independent of the higher level graphical user interface (the GUI) and also of lower level graphical objects (GOBs); however, it can interact with both of those sub-systems. Normally the GUI provides the contents to the view system, but users are also allowed to build and display their own windows directly or even write their own custom graphics systems.

Basic Functions

The view system provides these basic top level functions:

The VIEW Function

load-gui

The view function opens new windows and is the main function of the view system.

USAGE:
    VIEW spec /options opts /modal /no-wait /across /as-is

DESCRIPTION:
    Displays a window view from a layout block, face (panel), or low level graphics object (gob).
    VIEW is a function value.

ARGUMENTS:
    spec -- Layout block, face object, or gob type (block! object! gob!)

REFINEMENTS:
    /options
        opts -- Optional features, in name: value format (block!)
    /modal -- Display a modal window (pop-up)
    /no-wait -- Return immediately - do not wait
    /across -- Use horizontal layout for top panel (rather than vertical)
    /as-is -- Use GOB exactly as passed - do not add a parent gob

Primary Argument

The view function accepts several different datatypes for its window argument, and each has a different meaning:

Examples:

view [text "Hello world!"]
view make-face 'text [text: "Hello world!"]
view make gob! [text: "Hello world!"]

The first and second examples are equivalent, but there will be times when you want to provide a panel face object rather than the GUI description itself.

In the last example the gob is not the window itself, but the object to be displayed within the window. The view function will create a window to display that object with a title and other options.

Special Options

Window options are specified in a block in name-value format. For example:

view/options window [title: "Example" modes: [resize]]

Valid fields of the block are:

Examples:

view/options window [title: "My window title"]
view/options window [flags: [resize dropable]]
view/options window [no-wait: on]
view/options window [offset: 100x100]
view/options window [offset: 'center]
view/options window [as-is: true] ; GOB is the window object

Some of these also have refinements as shortcuts:

view/modal window
view/no-wait window

Implied Wait

When the view function is called it does not return immediately. Instead, it waits and allows windows to process their events. That is, your code becomes event-driven at that point. This happens only once, when the first window is opened. Of course, if you call view more than once without closing, subsequent calls will not wait. The view function will return only when all windows have been closed.

If you want view to return immediately, you can use:

view/no-wait win

Then, when you are ready, call the do-events function to start the event-driven mode of your code.

Example:

view/no-wait win
...other stuff...
do-events

Moving Windows

This example shows how to dynamically relocate a window by changing its GOB offset and calling show again (in this case, show-later, see note below.)

view [
    title "Click to move window"
    button "Move to 100x100" do [
        win: window-face? face
        win/gob/offset: 100x100
        show-later win
    ]
]

Notes:

1. The do reactor block uses its face (the button) with the window-face? function to find the top-level window face.
2. The GOB of the window has its offset changed to 100x100.
3. The show-later function will show the change when the GUI exits event handling (after processing the do reactor shown above.)

This example moves a window other than the one that contains the move button.

wgob: view/no-wait [
    title "This is the window"
    button "Quit" quit
]

view/options [
    title "Move other window"
    button "Move to 100x100" do [
        wgob/offset: 100x100
        show-later wgob
    ]
][offset: 200x200]

do-events

Notes:

1. The first window uses /no-wait in order proceed (not wait) and allow the second window to appear.
2. The first view returns a gob, which we call wgob.
3. The second window is positioned at 200x200 to avoid it appearing on top of the first window.
4. The second window sets the wgob offset.
5. The show-later function will show the change when the GUI exits event handling (after processing the do reactor shown above.)
6. do-events is called to process the window events for both windows.

Window Metrics

Metrics about the graphics system are stored in:

system/view/metrics

They include the primary metrics supported on most OS implementations. We do not provide all possible window metrics, because they may not be available in all systems, and code would become non-portable.

Here is an example of current metrics:

? system/view/metrics
SYSTEM/VIEW/METRICS is an object of value:
   screen-size     pair!     1152x864
   border-size     pair!     4x4
   border-fixed    pair!     3x3
   title-size      pair!     0x26
   work-origin     pair!     0x0
   work-size       pair!     1060x864

The work-origin and work-size provide the usable work-area of the screen (without task bar).

Event Handlers

When you call view, normally the system event handlers will be provided; however, you can specify your own event handler if needed.

Here is an example custom event handler:

view/options window [
    handler: [
        name: 'my-handler
        priority: 100
        handler: func [event] [
            if event/type = 'down [quit]
        ]
    ]
]

See the R3 View - Event Handling section for more about event handlers.