REBOL/View Graphics - Face Hierarchy

How faces are layered and composited into windows and panels.

Concept

REBOL/View provides a system for the construction of graphical displays and graphical user interfaces in a straightforward manner. Such displays normally consist of much more than just one face. Typical interfaces may require dozens, if not hundreds, of faces that are layered orcomposited together within one or more windows.

To reduce the complexity of the implementation of a user interface, faces are normally organized into a hierarchy. The hierarchy defines the relationship between faces, such as the way the faces overlay each other or how they are positioned relative to each other. The hierarchy also allows the efficient update of areas of the screen as faces change, and helps speed the propagation of events to their target faces.

In REBOL, the view system hierarchy is implemented in a direct and easy-to-understand manner. It is simple to construct the layers of faces and achieve the desired results. The system design also supports dynamic changes in the hierarchy, allowing it to be changed on the fly according to the requirements of your application.

Panes

The graphical hierarchy is constructed using thepane field that is part of every face. A pane is simply a block of faces (or a single face) that are graphically related, or event related, to a givenparent face. The faces within the pane aresubfaces of the parent face.

For example, a display face may be constructed from many other faces. When you view it, the result may look like this:

but, under the hood, this display is built from many separate faces as shown here:

Using thepane field of faces, the graphical hierarchy of objects is created. The top level face provides a pane that lists the objects of the next level, and each of those objects includes panes that list the objects of the next level beyond that.

Only faces that appear within the pane blocks of the hierarchy will be displayed on the screen. If a face is not in one of these panes, it will not appear.

Relative Coordinates

Theoffset field of a face always specifies its location relative to its parent face. If a face has an offset of 0x0 it will appear at the same upper left coordinate as its parent face. This relative positioning of faces is used for all of the faces in a pane, and it makes it easy to position or move entire sections of the graphical display by simply changing the offset location of a single parent face.

Depth Arrangement

The order of faces in a pane determines which faces are on top of others. The first face of thepane block is in the back; the last is in the front.

For example, if apane is has this order:

pane: [city flower dance]

The faces will overlay like this:

However, if you reverse the pane:

pane: [dance flower city]

You will see this order:

Note that the positions of the faces did not change. They are at the same coordinates, but appear in a different order.

Here is an actual example you can try:

the-pane: reduce [    make face [        text: "Face 1"        color: red    ]    make face [        offset: 50x50        text: "Face 2"        color: green    ]]window: make face [    offset: 100x100    size: 150x150    pane: the-pane]view windowreverse the-paneview window

Screen Face

A special face object is predefined to represent the screen of the computer. This face issystem/view/screen-face. You can view its field values with the line:

? system/view/screen-face

The main fields of interest are thesize and thepane. The size indicates the width and height of the computer screen in pixels. The pane holds a block of the REBOL windows that are open on the screen.

You don't normally need to be concerned about thescreen-face unless you want the screen size for your application. Functions likeview isolate the need to access thescreen-face directly, and it is recommended that you use them.

Window Faces

Every REBOL window is also a face. The face appears on screen whenever it is added to thescreen-face pane (above).

The depth arrangement of windows is the same as it is for any face. The last face is the topmost window.

The fields of a window face have the following meanings, fairly consistent with faces in general:

A window will be displayed when it is added to thescreen-face pane and theshow function is called on thescreen-face. This is normally handled by theview function and you do not need to do it yourself manually.

Similarly, theunview function removes windows from the screen by removing them from thescreen-face pane and callingshow on thescreen-face.

Panels

When creating more complex user interfaces, there are times when you need to group several user interface elements together. The pane of a face can be used to create such panels, even if the face itself contains no graphics of its own (no image or color backdrop, etc.)

The advantage of such panels is that they allow you to move all the elements within them together as a single unit. You do not need to update the positions of each element.

In addition, these panels are clipped in the same manner as all faces, allowing you to easily create scrolling subpanels that hold more user interface elements than can be shown in the window at one time. The user preferences panel of REBOL/View is a good example of such a panel.

To move or scroll a panel, just change theoffset value of its face and callshow on the face.

Important Notes

There are just a few areas where problems occur that may be difficult to debug, so we want to mention them here...

1. Face not in a pane.
   You do ashow on a face, but it is not part of any pane. The face will not be shown.
2. Face in more than one pane.
   It is not valid to add the same face object to more than one pane. If you need to do that,make a clone of the object, and use that in the other pane.
3. Negative face sizes.
   A face size can never be negative (either in x or in y). Trying to do that is considered an error.