REBOL/View Graphics - Face Functions
The functions that power the graphics system.
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 [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 ] ]
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.|
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:
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.
|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:
|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 low level native View functions are listed here. These functions will be described in more detail within specific sections of this document.
|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).|