REBOL/View Graphics - Face Functions

The functions that power the graphics system.

Face Functions

The View system was designed to keep the number of native (internal) graphics functions to an absolute minimum. The system only requires two lower-level functions to operate:

show	Display or refresh a face or block of faces.
hide	Hide a face or block of faces.

Although a few other native functions exist to help with text mapping and color conversion, they are not critical (and are covered in separate parts of this document).

Show Function for Display and Refresh

The show function is used to display a face either for the first time or after some kind of change has been made to the face.

If the face has not been shown before, it will be displayed. If the face is already displayed, it will be refreshed (redrawn). If the face contains subfaces, they will all be refreshed as well. If the face is a window, the entire window including all of its faces will be refreshed.

The show function takes a single argument: a face or block of faces.

show face

show [face1 face2 face3]

Note that the block can contain words (variables) for faces, but it is otherwise not evaluated. (Use reduce if you need to do that.)

In order to be affected, the face or faces must be part of face hierarchy (part of a pane somewhere). If you attempt to show a face and nothing happens, make sure that the face is part of the display hierarchy. That is, the face must be present in the pane list of another face that is being displayed.

Normally when you display a face for the first time, you use the view function to create a new window. The view function includes a call to the show function, so you do not need to call it again unless you make changes to the faces within the window.

The example below shows how the show function is used within an event handler (engage) to refresh the face on the screen.

view make face [
    offset: 100x100
    pane: reduce [
        make face [
            text: "Click to see the color change."
            color: yellow
            edge: none
            feel: make feel [
                engage: func [face action event] [
                    if action = 'down [
                        color: random white
                        show face
                    ]
                ]
            ]
        ]
    ]
]

Note that the show function frequently appears within VID object actions (because VID is built on top of the View graphics system). For instance, a button may change the attributes for another face and show must be called to see the result.

Here is an example of how show is used with VID:

view layout [
    bx: box teal "Example"
    btn "Show" [
        bx/text: now/time
        bx/color: random white
        show bx
    ]
]

Beginner Note:

Beginners often make the mistake of changing some of the fields of a face but forget to call the show function. As a result, the face does not change, and the user is not sure why. All that is needed is to correct the problem is to call show after the change has been made. (The face accessor functions (e.g. set-face) were added in View 1.3 to make this easier.)

Also note that you do not want to call show over and over for each small change, unless you really need the screen to refresh. Note that the above example changes both the text and the color but only calls show once.

Hide Function

The hide function temporarily removes the face from view. It does not remove the face from its parent face's pane.

Note that the face will become visible again the next time the face is shown either directly or indirectly through one of its parent faces.

The hide function is rarely used in most applications. It is better to remove a face from the display hierarchy then call show to refresh the parent face (hence, removing the face on the screen).

For window faces, the hide function closes the window. Normally, you will want to use the unview function to close the window, because unview also removes the window face from the screen-face pane.

View and Unview

There are two higher-level functions that are frequently used in the View system:

view	Opens a window face, displaying its contents.
unview	Shuts a window face.

View Function

The view function creates and updates windows. It takes a face as its argument. The contents of the window is determined from a face that holds a pane of the graphical objects.

The position and size of the window are determined from the face fields of the window. The window's title (caption) will be the text field of the face. To provide a different title, use the /title refinement and a string.

The first use of view within an application is special. It displays the window and initializes the graphical interface system. Subsequent calls to view update the window and do not create new windows unless the /new refinement is provided.

The first call to the view function will not return immediately. At that point your code becomes event driven, calling the feel functions associated with various faces. While the first call to view remains active any other calls to w: will return immediately. The first call will return only after all windows have been closed. This is equivalent to calling the do-events function. Here is an example to help clarify:

print "opening window..."
view make face [
    offset: 100x100
    color: papaya
    text: "Example"
]
print "continuing..."
halt

In the above example, note that print that follows the view is not printed until after the window is closed.

In some cases you may want to view a window but continue evaluating code after the window is open. You can do that by specifying the new refinement. Here is an example:

print "opening window..."
view/new make face [
    offset: 100x100
    color: papaya
    text: "Example"
]
print "continuing..."

The print will occur after the view opens the window. When you are ready to process events, call do-events:

do-events
print "all windows closed"
halt

The do-events will process events and wait until all windows are closed before resuming.

The new refinement is also used when you want to open additional windows without closing the current window.

Calls to view can specify options, such as whether the window has borders and is resizable. Single options are provided as a word and multiple options are specified in a block.

To better understand the view function, type:

source view

Unview Function

The unview function is used to close a window previously opened with the view function.

By default, the last window that has been opened will be closed. To close a specific window, use the /only refinement and specify the window's face. All windows can be closed with the /all refinement.

Note that the view function will not return until all windows have been closed. (Use view/new to return immediately after the window is opened.)

Special Face Changes

The face changes field is provided for special types of operating system (or window system) actions that may occur on window faces.

These flags are executed as part of the show function.

Flag	Description
offset	the offset has changed.
text	the text has changed. This is used to update Window titles.
activate	activate (make it the system focus) the window on the screen.
maximize	expand the window to full screen size.
minimize	shrink the window to its minimum or iconic size.
restore	restore to the prior window size.

Here is an example that shows how to use the changes field to maximize a window.

window: make face [
    offset: 100x100
    size: 100x100
    pane: reduce [
        make face [
            text: "Click"
            size: 80x24
            effect: [gradient 1x1 gold tan]
            edge: make edge [
                color: red
                size: 2x2
                effect: 'bevel
            ]
            feel: make feel [
                engage: func [face act evt][
                    if act = 'down [
                        window/changes: [maximize]
                        show window
                    ]
                ]
            ]
        ]
    ]
]

Window Face Options

A window face may have special values set in its options facet that control the window's appearance and behavior on screen. These options are set in the options field of the window's face object. The options field can be a single word or a block of words.

Here is list of the available options:

Option	Description
no-title	The window will display without a title (caption) bar. (Sometimes used for startup splash screens and special types of dialog boxes -- otherwise it should be used rarely.)
no-border	The window will display without borders. Note that the face's edge facet may still be used. If you want no borders at all, set the w: edge to none.
resize	Allows the window to be resized by the user. On most operating systems, the borders will look different to indicate that the window can be resized.
all-over	Causes the over event to report a continuous stream of mouse positions as the mouse moves over the face. Do this only if you need to; it can impact performance..
activate-on-show	Activate the window when the show function is called for the face. This is used to keep a window on top. (Note, however, that newer versions of MS Windows will not bring the window to the top unless REBOL is the currently selected application. But, it will blink the REBOL task bar to show that the window has been activated.)
min-size	Set the minimum size for resizable windows. This value is passed along to the operating system (it is not handled by REBOL directly). For MS Windows, the size is the full window size, including the title bar and borders (if any). The min-size word must be followed by a pair value that specifies the minimum window size. (So this option requires that you use an options block, not a single word.)

Window System Dependent - The no-title and other options depend to some degree on the windowing system being used. They may not work in an identical fashion on all operating/windowing systems.

Here is an example that will display a window with no title bar and no borders:

view make face [
    offset: 100x100
    edge: none
    color: papaya
    text: "Example"
    options: [no-title no-border]
]

The window options can also be specified as an argument to the view function:

view/options make face [
    offset: 100x100
    edge: none
    color: papaya
    text: "Example"
] [no-title no-border]

Note that if you need to change the options used for a window, you must unview the window and view it again to apply the changes. The next example demonstrates this:

this-face: make face [
    offset: 100x100
    size: 300x200
    text: "Click to change options"
    options: [no-border no-title]
    feel: make feel [
        engage: func [face action event] [
            if action = 'down [
                unview this-face
                options: [resize min-size 300x200]
                view this-face
            ]
        ]
    ]
]
view this-face

Other Functions

Other low level native View functions are listed here. These functions will be described in more detail within specific sections of this document.

Function	Description
size-text	Returns the size of the text in a face.
textinfo	Sets the line text information in an object for a face.
offset-to-caret	Maps from a graphical position to a string position. Returns the string series position within the face/text field that corresponds with the given XY graphical location (a pair!).
caret-to-offset	Maps from a string position to a graphical position. Returns XY graphical location (relative to the face) for a given string series position.
rgb-to-hsv	Converts RGB value to HSV (hue, saturation, value).
hsv-to-rgb	Converts HSV (hue, saturation, value) to RGB.
draw	Draws scalable vector graphics to an image (returned).

	Contents
Face Functions Show Function for Display and Refresh Hide Function View and Unview View Function Unview Function Special Face Changes Window Face Options Other Functions