GOB stands for Grafical Object, before using this guide, remember to launch
ConceptA 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.
Usually 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 DatatypeA 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 GOBsNew GOBs are created with make and a specification block.
gob1: make gob! [text: "Example" size: 400x40]
logo-image: load %reb-logo.gif
gob2: make gob! [offset: 10x20 image: logo-image]
You may use also the Rebol 2 Draw commands, but at the moment you can't access directly, you have to use the stylize function:
about: "A circle style"
facets: [init-size: 100x100]
circle 50x50 40
view [a: circle]
If inspect a/gob/draw you you'll find the DRAW commands, but don't try to modify directly it!
>> ? a/gob
A/GOB is a gob of value: make gob! [
draw: [translate 0x0 clip 0x0 105x104 anti-alias false pen false line-width
pen 255.255.255 fill-pen false anti-alias true pen 0.0.0 line-width 2.7
variable fill-pen 128.0.0 circle 50x50 40x40
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 TypesEach 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.
|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.|
Access FieldsA GOB datatype allows access to the following fields:
|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|
In addition, these fields are used to access the content of a GOB, depending on its type:
|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|
agob/image: load %photo.jpg
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 SizeSpatial information about the GOB can be accessed with:
|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.|
Data ReferenceThe 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.
PanesThe 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.
Adding GOBS to PanesTo 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
Or, you can add several GOBs at the same time:
append gob1 [gob2 gob3]
Note that the block of words is not reduced, but words will be looked up.
Other Useful ActionsYou can use other series-like functions, such as getting the length:
Or clearing the pane, or specific parts of the pane:
clear at gob1 2
You can also remove from the pane:
remove find gob1 gob2
As well as use indexing refinements:
All Valid ActionsHere's a full list of all the action functions that operate on the GOB datatype:
|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 MappingEach 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:
|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 WindowsThe 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 GOBThe screen-gob is a field in system/view object. The size field of the GOB is the size of the screen:
Each GOB within the screen-gob/pane is a window.
Creating a WindowNote: See R3 View - Windowing System 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
However, this method should be avoided. You should use the view function, which handles many other features.
Window FlagsWindow GOBs accept these special flags:
|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|
win/flags: [resize dropable]
or during the MAKE with:
win: make gob! [size: 100x200 flags: [resize]]
You can obtain the flags block with:
Event HandlingWindow 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 View - Windowing System sections.
Rendering GraphicsGraphics 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.
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:
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:
- Rendering order is first to last
For GOB panes, each GOB is rendered in the order it appears in the pane, with each successive GOB on top of the others, with the last GOB on top.
- Background refresh
When a GOB offset is moved relative to its parent GOB, or when it changes size, any background behind the GOB is re-rendered. (Internally a GOB stores its old-offset and old-size information for use in this process.)
- Optimized show
If a gob appears more than once within a show block (and the panes of gobs in that block) the second case of the GOB will be ignored (an optimization).
- Delayed show
If you are changing several GOBs during a single event, it is more efficient to keep a list of changes then render all the changes together with a single call to show. In the R3 GUI, this is done by defining a show-later that queues the requests to a block, then calls show-now to refresh the display.
TransparencyGOBs support two levels of transparency.
- Images or colors may specify transparency. For example, an image with transparent rounded edges.
- 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.
gob1: make gob! [size: 200x100 text: "Example of transapency"]
gob2: make gob! [size: 180x50]
gob2/image: load %logo.gif
append gob1 gob2
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.)
ExamplesThe 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.
;-- Background image
gobb: make gob! [offset: 0x0]
gobb/image: load %rebol-3d.png
;-- Top image:
gobi: make gob! [offset: 10x10]
gobi/image: load %icon.png
;-- The window:
win: make gob!  ;[text: "Test Window"]
append win gobb
append win gobi