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:
- 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. - 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:
- Minor variations of another style.
Often for commonly reused element of your GUI. These make simple changes to the color, size, or other basic attributes. - Derived from another style.
Starts with a basic foundation from another style, but makes substantial additions to its attributes, rendering, or actor functions. - Entirely new style.
When no other styles have what you need, you must build one from scratch. This will require greater knowledge of the system.
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
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
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
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
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
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
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
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
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.