REBOL
Docs Blog Get-it

R3 GUI Styles

Technical documentation for developers.
Part of the R3 Graphical User Interface (GUI).
New users should read the R3 GUI - User's Guide.

Concepts

Styles define GUI elements.

A GUI is built from a collection of styles, such as button, field, text, and image. In essence a style defines a class of user interface object, specifying the attributes, variables, and functions that are used to create and operate that object. An instance of a style is a face, one or more of which are displayed in a panel.

Every style has a name that refers to the style during the construction of a GUI, within documentation, or later for debugging purposes. For example, button is the name for a style that looks and acts like a push-button.

Styles can be collected into a style-sheet that provides all of the definitions for the desired look and feel of a GUI. Style-sheets can be global across an entire application, or local to a specific section of the application. The GUI system supplies a default style-sheet that includes a standard set of useful styles.

Using Styles

GUI styles are used in two main ways:

  1. To create face objects to be displayed in the GUI.
    Styles create faces from a layout block (with the GUI dialect) provided to the view function and panel panels, or by calling the make-face function directly.
  2. To create new styles from existing styles.
    The new styles can be simple graphical changes or deeper modifications to the behavior of the style. For example, a cancel-button style might be defined from a plain button, but with a different color, shape, or default action.

With a Layout

Here's an example of styles used within a layout block.

view [
    text "Enter your name:"
    field
    button "Submit"
]

The words text, field, and button are the names of styles. They are used here to create faces that will be shown in the GUI when the window is created.

With Make-Face

You can also create a face from a style by calling the make-face function directly and providing the style's name and specification block:

btn-face: make-face 'button [text: "Submit"]

For more examples, see the R3 GUI Faces section.

With regard to the creation of new styles from existing styles, that is the subject covered in detail below.

Predefined Styles

The system defines a standard set of styles that implement the basic set of graphical elements (the widgets) of a GUI.

!add full list of styles, this is just a start

Style Description
area text input area
button expandable button
draw scalar vector graphic
field text input field
image bitmap image
h1 heading of level 1
h2 heading of level 2
scroller scrollbar
slider sliding controller
text section of text
toggle toggle button

Defining Styles

Styles are normally defined form existing styles. This approach saves time because you only need to define the additional attributes required by the new style.

When it comes to defining new styles, there are three common patterns, depending on how close existing styles are to what you need:

Style Functions

New styles are created by providing a definition block to the stylize or make-style functions:

Function Description
stylize Define one more more new styles from a block of names and definitions. The specification of the style is provided in a block format, similar to that used by objects.
make-style Define a new style of a given name. A parent style can be specified. The specification of the style is provided in a block format, similar to that used by objects.

Note that various other functions related to styles can be found on the R3 GUI Faces page.

Definition Format

In order to make style definitions easier to create and maintain, the stylize function accepts a special declaration format of the general syntax:

new-style: parent-style [specifications]

The specifications block consists of field names followed followed by their settings, attributes, or functions. The field names are those used by the style object, described in the next section.

Here's an example of the actual style definition for button:

button: clicker [

    about: "Single action button with text."

    facets: [
        size: 100x28
        max-size: 200x28
        min-size: 50x24
        text-body: "Button"
        text-style: 'button
    ]

    options: [
        text-body: [string! block!]
        area-color: [tuple!]
        size: [pair!]
        wide: [percent!]
    ]
]

This simple style is based on the clicker style which defines the main actor functions, as reused for buttons. It adds a new about string, a few new facets, and some options.

Many examples will be shown below.

Style Object

A style object includes at least these fields:

Field Datatype Description
name word! Identifies a style for construction or debugging purposes. The system finds styles by their unique names. Example names: button and text.
about string! A short summary of the style for display by help and documentation functions.
parent word! The name of the parent style. For example, the parent of button is a clicker.
facets object! Holds named attributes that are referenced within other parts of the style. For example the size or area-color of the style.
options object! Optional attributes that are used inline within the GUI definition as shortcuts. For example, a pair value may specify the size of an object.
actors map! Functions that are called by the GUI system at specific times for specific purposes. For example, on-click and on-resize.
draw block! A block of draw commands and their arguments that are used to render the style into a displayed image.
faced object! Face defined fields. These are special variables used by the style within the face object.
state block! Holds the prototype definition for the face instance variables used by a style.
content block! The panel layout for composite styles.

Standard Facet Names

Although you can add any facet name you want, many functions of the GUI depend on standard names. For example, the area-color is used for creating the gradient backgrounds of most graphical elements.

Some of the common names are:

Name Description
size define
area-size define
area-color define
pen-color define
area-fill define
edge-color define

add complete list!

Example Definitions

Here are some examples of the most common style creation methods.

Simple Variation

Here is a very simple variation on a style. It's called red-box, and it is based on the box style. It makes only one change, to define a new facet for the area-color. The rest of the style is inherited from the box style which is a base-style of the GUI system.

Missing image: /-code
Missing image: /-code
stylize [
   red-box: box [
       facets: [area-color: maroon]
   ]
]
view [red-box]

It should be noted that to make a new style from an existing style, you must know the names the facets and how they are being used. In the code above, we know that area-color controls the background color of the box. When you are not sure of what facets are used, you can review the definition of the parent style.

Here's another example of stylize that creates a new button style of a different color and default text label:

Missing image: /-code
Missing image: /-code
stylize [
    stop-button: button [
        about: "Implements a red stop button"
        facets: [
            area-color: 200.0.0
            text-body: "Stop"
        ]
    ]
]
view [stop-button]

New Style

Here's an example of a completely new style called circle that draws a circle of a fixed size and color:

Missing image: /-code
Missing image: /-code
stylize [
    circle: [
        about: "A circle style"
        facets: [
            size: 100x100
        ]
        draw: [
            pen black
            line-width 2.7
            fill-pen maroon
            circle 50x50 40
        ]
    ]
]
view [circle]

The facets block provides the size for the face and the draw block provides the drawing instructions.

Of course, this is just a static circle style with no variations, so let's add a few.

Facet Attributes

Taking the above circle style, we want to parameterize its size and color. This allows its attributes to be specified later, when it is used within a GUI.

Running this code and resizing the window, we see:

Missing image: /-code
Missing image: /-code
stylize [
    circle: [
        about: "A resizable circle style"
        facets: [
            size: 100x100
            max-size: 1000x1000
            area-color: maroon
            edge-color: black
        ]
        draw: [
            pen edge-color
            line-width 2.7
            fill-pen area-color
            circle (area-size / 2)
                ((min area-size/y area-size/x) - 3 / 2)
        ]
    ]
]
view [circle]

Several fields have been added to the facets, and you can see how they are used in the draw block.

Notice the max-size field; it allows the face to resize automatically. The draw block includes a bit of math to help compute the new values. Note that in the draw block, you can obtain the inner size of the face using area-size, which is a standard facet for all styles and thus not displayed in the facets block above.

When displayed, if a size is not provided, it will use its default size. However, it can be resized. If you enter this example, drag the window corner to see the circle resize automatically.

Options

An option is an attribute that can be specified directly within the GUI layout code.

For example, let's allow the circle color to be provided as an option. In addition, let's expand the code to use that color to make a gradient within the circle.

Missing image: /-code
Missing image: /-code
stylize [
    circle: [
        about: "A colorable resizable circle style"
        facets: [
            size: 100x100
            max-size: 1000x1000
            area-color: maroon
            edge-color: black
        ]
        options: [
            area-color: [tuple!]
        ]
        draw: [
            pen edge-color
            line-width 2.7
            grad-pen radial (area-size / 2) 0
                ((min area-size/y area-size/x) - 3 / 2)          
                (span-colors area-color [2.0 .2])
            circle (area-size / 2)
                ((min area-size/y area-size/x) - 3 / 2)
        ]
    ]
]
view [
    circle red
    circle green
    circle blue
]

Resize the window, and you will see all three automatically resize.

Local Attributes and Actors

You will notice that the above example recomputes a few values in the draw block every time the object is redrawn. Normally, this is not a problem, but if those computations were more complex, they may add a lot of extra time to the redraw, slowing down the GUI.

Instead, you can move some of those computed values out of the draw block, and make them attributes of the face. Then, you add some code to compute the values only when necessary.

Here's an example:

stylize [
    circle: [
        about: "Draws a resizable circle."
        facets: [
            size: 100x100
            max-size: 1000x1000
            edge-color: black
            area-color: maroon
        ]
        options: [
            area-color: [tuple!]
        ]
        faced: [
            area-fill: none
            diameter: 50
        ]
        draw: [
            pen edge-color
            line-width 2.7
            grad-pen radial (area-size / 2) 0 diameter area-fill
            circle (area-size / 2) diameter
        ]
        actors: [
            on-make: [
                face/facets/area-fill: span-colors get-facet face 'area-color [2.0 .2]
            ]
            on-resize: [ ; arg is the size
                face/gob/size: arg
                face/facets/area-size: arg - 2
                face/facets/diameter: (min arg/y arg/x) - 5 / 2
            ]
        ]
    ]
]
view [
    circle red
    circle green
    circle blue
]

The faced block is similar to facets block, but makes them local to each instance of the face. Now, they can be modified without effecting any other faces that are of the same circle style.

The actors block defines a few actor functions that are called from the GUI as needed. The first computes the area-fill when the face is created. The second handles resizing, recomputing the size of the face and the diameter of the circle.

Notice that within the actor functions, the face variables must be referenced via the face object itself. The faced variables of the style are stored in the facet object of the face.

You should note the use of get-facet for obtaining the area-color. This allows the area color to be obtained from the style facets or from the face facets, depending on if it was changed in the options line. This is the general method for obtaining the attributes of a style.

On the other hand, when you set an attribute, it must be part of the face facets. You are not allowed to directly modify the facets of the style itself, or you would change all faces of that style, affecting the entire GUI!

View All Styles

Here's an example that's a little bit extreme. It creates a three column window that shows all predefined viewable styles:

all-styles: find extract to-block guie/styles 2 'clicker
view repend [group 3] [all-styles]

We'll let you run it for yourself to see the results (because the window is too large to show in this document.)

Here's a more elaborate example that creates a list of the predefined styles, then let's you view each one separately.

Missing image: /-code
Missing image: /-code
all-styles: find extract to-block guie/styles 2 'clicker
last-view: none
view/options [
    title "Pick a style:"
    text-list all-styles do [
        if last-view [unview last-view]
        style-name: pick all-styles value
        last-view: view/options reduce [
            'title reform ["Example of a" style-name "style:"]
            style-name
        ][offset: 'center]
    ]
][offset: 50x50 size: 200x400]

The last-view variable provides a way to close the prior windows, otherwise you'd end up with a many windows on top of each other.

Advanced Examples

A number of other example styles can be found in the source code to the GUI system. They range from simple styles of just a few lines (e.g. a button) to advanced styles that may require one or two pages (e.g. a scroller).

Progress Bar

A progress bar is just an output display bar that can be set from your program or from other GUI objects.

Here's an example using the predefined progress style:

Missing image: /-code
Missing image: /-code
view [
    prog: progress
    button "Set 50%" set 'prog 50%
]

Normally, you won't need to create your own progress bar style, but if you did here's an example of what it might look like:

stylize [
    my-progress: [
        about: "Progress bar."
        facets: [
            size: 200x22
            max-size: 1000x22
            edge-color: 96.96.96
            area-color: 80.80.80.128
            area-fill: span-colors area-color [.3 .5 1]
        ]
        options: [
            bar-color: [tuple!]
            size: [pair!]
        ]
        faced: [
            bar-color: teal
            bar-size: 1x1 ; modified by the progress % value
            bar-fill: ; generated from bar-color option
        ]
        draw: [
            pen edge-color
            line-width 1.5
            grad-pen 1x1 0 20 90 area-fill
            box 1x1 area-size 3
            grad-pen 1x1 0 20 90 bar-fill
            box 1x1 bar-size 3
        ]
        actors: [
            on-make: [
                face/facets/bar-fill: span-colors
                get-facet face 'bar-color [1.0 1.5 .6]
            ]
            on-set: [ ; arg: event
                ; Update the bar size from the face value.
                face/state/value: arg/2
                v: clip-face-val face
                size: get-facet face 'area-size
                face/facets/bar-size: as-pair v * size/x size/y
            ]
        ]
    ]
]
view [
    prog: my-progress
    button "Set 50%" set 'prog 50%
]

Slider bar (numeric value input)

Here's a much more advanced example that shows how the slider style was defined. A slider bar is an input device that for setting a value between 0% and 100%.

Here's an example using the predefined slider style:

Missing image: /-code
Missing image: /-code
view [
    slider attach 'prog
    prog: progress 
]

Normally, you won't need to create your own slider style, but if you did here's an example of what it might look like:

stylize [
    my-slider: [
        about: "Slide-bar for numeric input (0% - 100%)"
        facets: [
            size: 200x22
            max-size: 1000x22
            edge-color: 96.96.96
            area-color: 80.80.80
            area-fill: span-colors area-color [0.5 2.0]
        ]
        options: [
            size: [pair!]
            knob-color: [tuple!]
        ]
        faced: [
            area-size: none
            knob-color: red
            knob-xy: 
            bias-xy: 6x0 ; pointer adjustment at ends
        ]
        draw: [
            pen edge-color
            line-width .4
            grad-pen 1x1 0 4 90 area-fill
            box 1x1 area-size 3
            line-width 1.5
            fill-pen knob-color
            translate knob-xy
            triangle -6x16 0x2 6x16
        ]
        actors: [
            on-resize: [ ; arg: size
                face/gob/size: arg
                face/facets/area-size: arg - 2 * 1x0 + 0x6
                do-style face 'on-update none
            ]
            on-update: [
                ; Compute the knob offset from face/value:
                val: clip-face-val face
                bias: face/facets/bias-xy
                size: face/facets/area-size - bias - bias
                face/facets/knob-xy: val * size * 1x0 + bias
            ]
            on-offset: [ ; arg: offset
                ; Compute face/value from knob offset:
                bias: face/facets/bias-xy
                arg:  max 0x0 arg - bias
                size: face/facets/area-size - bias - bias
                axis: face-axis? face
                face/state/value: val: min 100%
                max 0% to-percent arg/:axis / size/:axis
                face/facets/knob-xy: val * size * 1x0 + bias
            ]
            on-click: [ ; arg: event
                if arg/type = 'down [drag: init-drag face arg/offset]
                do-style face 'on-offset arg/offset
                if arg/type = 'down [
                    draw-face face
                    return drag
                ]
                do-face face
                ; Click UP: compute percentage value from xy offset none
                ; handled event
            ]
            on-drag: [ ; arg: drag
                do-style face 'on-offset arg/delta + arg/base
                draw-face face
                do-face face
            ]
            on-set: [ ; arg: [field value]
                if all [
                    'value = first arg
                    number? second arg
                ][face/state/value: second arg]
                do-style face 'on-update none ; will clip value range
            ]
        ]
    ]
]
view [
    my-slider attach 'prog
    prog: progress 
]

For details about the actor functions above, see the R3 GUI Actors section. Here is a quick summary of the ones used above:

Actor Description
on-resize changes the gob and area sizes, then calls update to recompute the knob location.
on-update is a general update function that recomputes the knob location.
on-offset is used during mouse input to convert the mouse position to the actual state value, which is a percentage between 0% and 100%. It also updates the knob location, just to save time.
on-click handles the mouse button when it is clicked in the bar. First, the knob is moved to where the click occurred. Then, if the user starts to drag, the drag operation begins.
on-drag takes care of the drag operation, updating the value as needed, depending on the location of the mouse.
on-set handles setting the slider from another GUI object or from the program. It's main job is to make sure the value is valid, then update the slider.

Descriptions of various other functions can be found in the R3 GUI Faces section.

About | Contact | PrivacyREBOL Technologies 2024