REBOL
Docs Blog Get-it

R3 View - Graphical Objects

R3 Graphical User Interface (GUI)

Concept

A GOB is a low-level graphical object.

GOBs are used for for constructing windows, panels, images, text, and drawings. They support two dimensional compositing with transparency (alpha channel), scalar vector graphics, image effects, and rich-text.

A GOB is a highly optimized native datatype. It has been designed to provide the primary features required for graphics, but substantially reduce the memory footprint and processing overhead required. As a result, complex displays, such as animations, simulations, or video games can be created that are composed of thousands of individual GOB elements.

Users do not need this information just to use the GUI. This information is provided for users who want to use the graphics system directly or to create new styles for the GUI.

GOB is a Datatype

A GOB is an optimized datatype for supporting graphics. Technically, it is not a series nor is it an object, but it will respond to action functions similar to both of those.

Making GOBs

New GOBs are created with make and a specification block.

gob1: make gob! [text: "Example" size: 400x40]

gob2: make gob! [offset: 10x20 image: logo-image]

gob3: make gob! [
    offset: 100x200
    size: 400x400
    draw: [pen yellow line-width 5 circle 200x200 150]
]

Note that the specification block is not reduced and only valid field names are allowed (see list below.)

You can also create a GOB from another GOB, inheriting its settings:

gob4: make gob1 [text: "Another example"]

Content Types

Each GOB is of a content type that determines the format of its data and how it will be rendered on the display. Complex displays are created by combining layers of GOBs of these various types. For example, you can create a display that has colored text on top of an image on top of a draw-rendered gradient on top of a colored background.

Type Description
color An RGBA color to fill the specified area.
image An RGBA image. The size of the GOB is determined by the size of the image.
draw A block of scalar vector graphic (SVG) commands, such as line, box, and circle.
effect A block of special effect commands, such as blur or colorize, etc.
text A block of rich-text commands including special modes such as bold, italic, color, etc.

In addition a GOB may have no content type and just be used as a pane that holds a list of GOBs that will be composited together. For example a window or a panel used for an input form may be used just for "organizational" purposes.

Access Fields

A GOB datatype allows access to the following fields:

Field Datatype Description
offset pair! the x-y coordinate relative to parent
size pair! width and height of gob canvas or coordinate space
pane block! a block of child gobs (see below)
parent gob! the parent gob (in its pane)
data object! block! string! binary! integer! none! normally used to reference data related to the gob, such as the VID face object
flags block! special flags, see section below
alpha integer! alpha transparency for the gob overall
owner gob! a temporary field used for popup windows to specify the owning parent window

For example:

agob/offset: 100x100
print agob/size
bgob: agob/parent

In addition, these fields are used to access the content of a GOB, depending on its type:

Field Datatype Description
color tuple! the color of the gob
image image! an image within the gob
draw block! a DRAW dialect block
effect block! an EFFECT dialect block
text block! string! a richtext dialect block

Examples:

agob/color: blue
agob/image: load %photo.jpg
agob/draw: [
    pen edge-color
    line-width 1.5
    box 1x1 300x40 3
]

Note that you can only specify one content field per GOB. If you attempt to set a second field, it overwrites the earlier one.

Offset and Size

Spatial information about the GOB can be accessed with:

Name Description
offset The x-y offset of the GOB relative to its parent. Either value (or both) can be negative and clipping will occur.
size The width and height of GOB content area. Any graphics that extends outside this area will be clipped.

For example:

gob/offset: 100x20
print gob/offset
gob/size: 150x50

Data Reference

The primary purpose of the data field is to provide a way to reference an object, block, or other data related to your rendering, subsystem, or application.

Although the data field is under the control of the programmer and is not accessed by the GOB system itself, it is used by subsystems like the GUI. For example, in the GUI the data field might point to the face object that stores run-time information such as event handling to quickly locate the face.

Internally, the data field is pointer-sized (32 bits as of writing this page) for optimization reasons. It is not a fully-qualified value field, so can only hold the specific values mentioned above, and any series references contain no indexed offsets. If you need to store general values, use a block or object.

Panes

The pane field provides the tree structure (the hierarchy) for a GOB display. Each pane begins a new relative-coordinate system with sub-GOBs located within it.

Each GOB can include a content and a pane. In such cases, the content is layered behind any GOBs of the pane. The GOBs of the pane are also clipped according to the size of the parent GOB.

The order of layering for GOBs in a pane is last-on-top. That is, they are rendered in the order they appear in the pane, with each successive GOB on top of the others.

Reuse restriction: When a GOB can only be in one pane at a time. If you attempt to insert a GOB into more than one pane, it will be removed form it prior pane. This is a necessary requirement of the linked list used to manage panes and state internal variables required for rendering.

Adding GOBS to Panes

To add one or more GOBs to a pane, use the append or insert functions.

For example, given these gobs:

gob1: make gob! [size: 200x200 color: white]
gob2: make gob! [offset: 20x20 size: 40x30 color: red]
gob3: make gob! [offset: 120x80 size: 50x40 color: blue]

this line will add gob2 to the gob1 pane:

append gob1 gob2
view gob1

Or, you can add several GOBs at the same time:

append gob1 [gob2 gob3]
view gob1

Note that the block of words is not reduced, but words will be looked up.

Other Useful Actions

You can use other series-like functions, such as getting the length:

length? gob1
2

Or clearing the pane, or specific parts of the pane:

clear gob1
clear at gob1 2

You can also remove from the pane:

remove find gob1 gob2

As well as use indexing refinements:

gob1/1: gob4
gob1/2/image: new-image

All Valid Actions

Here's a full list of all the action functions that operate on the GOB datatype:

Action Description
append Inserts a value at tail of series and returns the series at head. (Modifies)
at Returns the series at the specified index.
back Returns the series at its previous position.
clear Removes all values. For series, removes from current index to tail and returns tail. (Modifies)
find Finds a value in a series and returns the series at the start of it.
head Returns the series at its head.
head? Returns TRUE if a series is at its head.
index? Returns the index number of the current position in the series.
insert Inserts into a series and returns the series after the insert. (Modifies)
length? Returns the length of the series from the current position.
next Returns the series at its next position.
past? Returns TRUE if a series index is past its tail.
pick Returns the value at the specified position in a series.
poke Returns value after changing its data at the given index. (Modifies)
remove Removes value(s) from a series and returns after the remove. (Modifies)
reverse Reverses a series and similar types. (Modifies)
skip Returns the series forward or backward from the current position.
tail Returns the series at the position after the last value.
tail? Returns TRUE if empty, or for series, if index is at or beyond its tail.
take Copies and removes from series. (Typically, removes last GOB.)

Coordinate Mapping

Each GOB pane provides it's own coordinate system. That is, all of it's sub-gobs are located relative to the origin of their parent.

Often you will need to take a position at the top level and map it to a position within a sub-gob, or within even deeper sub-gobs. There are two functions to help perform this mapping:

Function Description
map-gob-offset Translates a gob and offset to the deepest gob and offset in it, returned as a block: the gob and offset. Also supports the reverse operation: given a GOB and offset, provide the GOB and offset within its top-most GOB.
map-event Within an event datatype that has a GOB and offset position, modify the event by mapping to its terminal (lowest) GOB and offset.

GOBs as Windows

The screen and its windows are controlled with GOBs. New windows are opened by adding a window GOB to the screen GOB pane. Windows are closed by removing the window GOB from the pane.

The Screen GOB

The screen-gob is a field in system/view object. The size field of the GOB is the size of the screen:

print system/view/screen-gob/size
1440x900

Each GOB within the screen-gob/pane is a window.

Creating a Window

Note: See r3/docs/view/windows.html for more information about windows.

Normally, windows are created by the view function. Internally, it creates a new GOB for the window. The offset provides the position of the window, and the size provides its width and height. If text is provided, it will become the window caption. (Window GOBs do not allow color, image, draw, or effect content types, only text for the caption.)

For example, if you create a GOB:

win: make gob! [text: "Test Window" offset: 100x100 size: 300x200]

You can use that for a window by calling view this way:

view/as-is win  ; use the argument as the window itself

Or, you could open the window on screen with this:

append system/view/screen-gob win
show win

However, this method should be avoided. You should use the view function, which handles many other features.

Window Flags

Window GOBs accept these special flags:

Flag Description
dropable allow drag and drop of files
hidden window is hidden
modal modal event handling (for requestors)
no-border do not draw window borders (or title)
no-title do not show window title
on-top keep window on top
popup a popup window (has owning parent window)
resize allow the window to be resized
transparent let the window be transparent

These flags can be set like this:

win/flags: [resize dropable]

or during the MAKE with:

win: make gob! [size: 100x200 flags: [resize]]

You can obtain the flags block with:

probe win/flags

Event Handling

Window events such as mouse moves and button clicks are mapped by the native system to an offset within a specific window gob. The higher level event system is responsible for locating the specific sub-gob target of the click, if that action is desired.

Typically, a GOB that requires interactivity, such as processing of button events will be part of a higher level face object, and the processing of the specific events will be done by functions of that face.

For more information see R3 View - Event Handling and r3/docs/view/windows.html sections.

Rendering Graphics

Graphics is rendered with the show function. This same function is used for both initial rendering as well as updates (refresh). The target GOB to render is specified as the argument.

The line:

show gob1

Render gob1 as well as all sub-gobs in its pane, if it has one. If the GOB is already being displayed, it's display would be refreshed.

This same function is true for window GOBs:

show win

renders all of the graphics in the window and redisplays it.

The show function also allows a block of GOBs:

show [gob1 gob2 gob3]

As you can see, if the gobs are words, their values will be used.

Here are a few important notes about rendering:

Transparency

GOBs support two levels of transparency.

  1. Images or colors may specify transparency. For example, an image with transparent rounded edges.
  2. The transparency of a GOB can be controlled with /alpha. This setting affects the entire GOB (and all subGOBs within it). The range is 0 to 255.

An example of setting the transparency of a GOB:

gob/alpha: 200

Note on speed optimization: if an image or color is found not to be transparent, and the /alpha field fully opaque, the compositing system will optimize the action (using a non-transparent blit). The speed difference is significantly faster, but should only matter in special cases, such as when moving or updating large areas of a window (e.g. playing a large animation or video, where alpha is not so important.)

Examples

The example below creates a window with a background image and an image on top of that background. Note, that setting gobb/image to back-img automatically sets gobb/size to the image's size - or, to state it differently, for image GOBs the size is always equal to that of the image.

;-- Load the images:
back-img: load %img/ukiah.jpg
tiny-img: load %img/dev.jpg

;-- Background image
gobb: make gob! [offset: 0x0]
gobb/image: back-img

;-- Top image:
gobi: make gob! [offset: 10x10]
gobi/image: tiny-img

;-- The window:
win: make gob! [text: "Test Window"]
win/size: gobb/size
append win gobb
append win gobi

view win
About | Contact | PrivacyREBOL Technologies 2024