Context Navigation

Widgets

Widgets are grouped in a single context named widgets. In the following descriptions each widget is described along with its common specification attributes (other than offset, size and span) and subsequent runtime accessors (attributes commonly used to change its appearance prior to show and/or referenced to determine its state).

RebGUI Beta 2 includes changes and enhancements to many of these widgets. Widgets marked with a single star after their name (*) have yet to be fully reviewed but are included in the base distribution. Widgets marked with a double star (**) need more work and are not included in the base distribution. Those marked with a triple star (***) are currently under development.

anim
area*
arrow
bar
box
button
calendar
chart**
check
chat*
check-group
drop-list*
drop-tree**
edit-list*
field
grid**
group-box
icon***
image
input-grid**
label
led
led-group
link
menu
panel
password
pie-chart*
progress
radio-group
slider*
spinner
splitter
symbol
table*
tab-panel
text
text-list*
title-group
tool-bar
tooltip

anim

Cycles a set of images.

anim data [%images/go-previous.png %images/go-next.png]
anim data [image-1 image-2] rate 2

Attribute	Note
data	`block` of `file` and/or `image` to cycle
rate	`integer` or `time` that controls the cycle (default 1)

source:widgets/anim.r

area*

Editable text area with text wrapping.

area

Attribute	Note
text	`string` to display
options	`[info]` specifies read-only

source:widgets/area.r

arrow

An arrow on a square face.

arrow
arrow data 'up
arrow data 'down
arrow data 'left
arrow data 'right

Attribute	Note
data	`word` specifying arrow orientation (default `'down`)

source:widgets/arrow.r

bar

A thin 3D bar used to separate widgets.

bar
bar 200

source:widgets/bar.r

box

The most basic of widgets, a rectangular area.

box red

source:widgets/box.r

button

Performs action when clicked.

button "Click me!" [print "Left"] [print "Right"]

Attribute	Note
text	`string` to display
options	`[info]` specifies read-only

source:widgets/button.r

calendar

Used to select a date.

calendar
calendar data 1-Jan-2000

Attribute	Note
data	`date` indicating current selection (default `now/date`)

source:widgets/calendar.r

chart**

New widget.

chart ???

source:widgets/chart.r

check

A tristate check-box with a green tick representing YES, a red cross NO, and empty being UNKNOWN. Left and right mouse clicks alternate between Yes/No and Unknown respectively.

check "Option"
check "Option" data true
check "Option" data false
check "Option" options [info]

Attribute	Note
text	`string` to appear to the right of the check-box
data	`logic` that indicates state of control (yes, no or unknown)
options	`[info]` specifies read-only

source:widgets/check.r

chat*

A 3-column multi-line scrollable widget similar to that found in AltME and designed for IM/chat applications.

chat data [
    "Bob" none "Comment." yello 1-May-2007/10:00:00
]

Attribute	Note
data	`block` of user/color/comment/color/date entries
options	`[limit n]` limits message display to n entries
options	`[id n]` set width of ID column
options	`[user n]` set width of USER column
options	`[date n]` set width of DATE column

check-group

A group of check boxes. Alignment is vertical unless height is specified as line height (5 units).

check-group data [
    "Option-1" true
    "Option-2" false
    "Option-3" none
]

Attribute	Note
data	`block` of label/state pairs (`string` & `logic`) specifying one or more check boxes
options	`[info]` specifies read-only
Runtime
data	`block` of `logic` (or `none`) indicating state of each check box

source:widgets/check-group.r

drop-list*

A single column selection list. Fires action only if a selection was made.

drop-list data ctx-rebgui/locale*/colors

Attribute	Note
text	`string` to display
data	`block` of values to appear in list
Runtime
text	`string` representing current selection

source:widgets/drop-list.r

drop-tree**

This widget is a combination of a menu and drop-down list that containes a tree. The idea is to use it as a very space optimized and fast menu system. If there is no action associated with a node and the node doesn't has any subnodes the node is grayed out.

- Supports fast-selection buttons to expand the tree to level 1-4 directly. Buttons give visual feedback.
- The tree lines are highlighted when the mouse moves over them.
- Expanding a node doesn't executed an ACTION block, only if the text is clicked on.
- Nodes expand only if the action block returns TRUE (in the same line like the on-un/focus triggers).
- The tree list is position automatically so that the selected node is the 2nd line from the top after a user selection to speed up useability.
- The selected path is shown in the field of the drop-tree giving you a visual feedback where you are.
- Supports alt-action block which can be used for the default code when node without ACTION block is selected.

drop-tree 100 data [
   "Node1" [
       "Node1-1" action [<code to execute if NODE1-1 clicked by user>]
       "Node1-2"
       "node1-3"
   ] action [<code to execute if NODE1 clicked by user>]
   "Node2" [
   ]
   "Node3"
   "Node4"
][print "Global action called!"][print "default 'EMPTY ACTION' block"]

Attribute	Note
data	nested `block` of nodes and actions to appear in tree
Runtime
expander-mode	'big (default) or 'small. When 'big the fast-selection buttons are left-to-right. When 'small the fast-selection buttons have quater size.
popup-mode	'inside (default) or 'outside, see drop-list
select-node [string!]	The string contains the path to the item you want to select in positional notation. Example: "1/2/1"
update	Required after SELECT-NODE or flag changes
text	The selection-path text
hide-tree	Closes the drop-list of the drop-tree

source:widgets/drop-tree.r

edit-list*

An editable single column selection list.

edit-list data ctx-rebgui/locale*/colors

Attribute	Note
text	`string` to display
data	`block` of values to appear in list
Runtime
text	`string` representing current selection

source:widgets/edit-list.r

field

Editable text field with no text wrapping.

field "String"

Attribute	Note
text	`string` to display
options	`[info]` specifies read-only

source:widgets/field.r

grid**

New widget.

grid ???

source:widgets/grid.r

group-box

A static widget used to group widgets within a bounded container.

group-box "Sample" data [
    field field
]

Attribute	Note
text	`string` title
data	`block` of sub-widgets

source:widgets/group-box.r

icon***

Similar to image, but SVG-based.

image

An image.

image %images/logo.png
image logo

Attribute	Note
image	`file` or `image` to render
effect	`word` or `block` of effects to apply to the image (default `'fit`)

source:widgets/image.r

input-grid**

A widget that can be used to get input from the user in a grid-form.
- supports headers for the different columns
- supports descriptions for the different rows (on the left side)
- counting starts at 1x1 for the non-header cells, header/description cells have index 0x... and ...x0
- columns can have different types like FIELD, LABEL
- each cell should be accessible through a PAIR key: input-grid/2x3 (like the image! datatype)
- optional auto cell-naming function to give every cell a unique, but pattern based name that can be used as word within the code

generated words are automatically added to the widget context

- Supports save/load input-grid data from/to the grid
- Supports default values either by column or by row

demo-values: copy []

repeat n 4 * 8 [
    insert demo-values form (random 100) / 10
]

display "test" [
    ig: input-grid data [
        row-title "1st Columns"
        columns ["Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" "Sunday" label "Sums"]
        rows ["1st Shift" "2nd Shift" "3rd Shift"]
        values demo-values
        auto-cell-naming
        row-names [monday tuesday wensday thursday friday saturday sunday sum]
        column-names [a b c]
        name-divider "-"
        cell-action [
            print ["cell action:" face/offset value]
        ]
    ] [print "input grid global action"]
]

DATA block specification dialect:
You have to specify all options in DATA block. The DATA block can contain:

Keyword	Type	Description
row-title	string!	This is the text in cell 0x0 with optional text align (center \| left \| right)
columns	block! or word!	block of the column header texts and column types(optional) and column widths(optional) text align center \| left \| right (optional). For example [label "column1" field "column2" 50] etc. If you don't specify the type it will use default FIELD type. If you don't specify the column width the default value of 22 units is used.
rows	block! or word!	block of rows description texts and text align (center \| left \| right - optional)
values	block! or word!	block of text values for all cells in the grid
auto-cell-naming		generates a context with words bounds to each cell. The word pattern is 'cell11 'cell12 'cell13 etc.
row-names	block!	specifies name part which is used for construction of cell names
column-names	block!	specifies name part which is used for construction of cell names
name-divider	string!	specifies part which is used for division of row-names and column-names parts
cell-action	block!	specifies code which is called when user presses enter key in any of the cell in grid

Widget accessors:

Function name	Parameters	Description
SET-CELL	pair! string!	using this method you can set any cell in the grid. Example: my-grid/set-cell 1x1 "test"
GET-CELL	pair!	using this method you can get any cell in the grid. Example: my-grid/get-cell 1x1 result = "test"
SET-GRID	block!	using this method you can set the content of grid cells providing block of string values per each cell.
GET-GRID	-	using this method you can get the content of grid cells. It returns block of string values per each cell.
MAKE-CELL-NAMES	row-names column-names name-divider	this method will create my-grid/ctx-cells context which contains generated words refering to each cell. (this is invoked also when you specify auto-cell-naming keyword in the DATA block). The word pattern is generated using the row-names + divider + column-names etc. so you can access the cells like: my-grid/make-cell-names [team lead] [name city] "_" show-text my-grid/ctx-cells/team_name "New text" or do bind [probe lead_city/text] in my-grid/ctx-cells 'self
GET-CELL-NAMES	-	returns a block of cell words ('cell11 'cell12 'cell13 etc.) which are bound to each cell in the grid. So you can do for example: cell-names: my-grid/get-cell-names cell-names/1==cell11 show-text get cell-names/1 "Test"

source:widgets/input-grid.r

label

Bold text.

label "A text label."

Attribute	Note
text	`string` to display

source:widgets/text.r

led

A tristate indicator box with a dark fill representing YES, a light fill NO, and empty being UNKNOWN.

led "Option"
led "Option" data true
led "Option" data false
led "Option" data none

Attribute	Note
text	`string` to appear to the right of the LED indicator
data	`logic` that indicates state of control (yes, no or unknown)

source:widgets/led.r

led-group

A group of LED indicators. Alignment is vertical unless height is specified as line height (5 units).

led-group data [
    "Option-1" true
    "Option-2" false
    "Option-3" none
]

Attribute	Note
data	`block` of label/state pairs (`string` and `logic`) specifying one or more LED indicators
Runtime
data	`block` of `logic` indicating state of each LED indicator

source:widgets/led-group.r

link

Hypertext widget.

link
link "www.dobeash.com"
link "http://www.dobeash.com"

Attribute	Note
text	`string` domain name or URL (default `"www.rebol.com"`)

source:widgets/link.r

Simple one-level text-only menu system.

menu data [
    "Item-1" [
        "Choice 1" [print "1"]
        "Choice 2" [print "2"]
    ]
    "Item-2" []
    "Item-3" []
]

Attribute	Note
data	`block` of `string`/`block` (spec) pairs further containing `string`/`block` action pairs

source:widgets/menu.r

panel

A static widget used to group widgets within a container.

panel sky data [
    after 1
    field
    field
    field
]

Attribute	Note
data	`block` of sub-widgets

source:widgets/panel.r

password

Editable password field with text displayed as a series of large dots.

password
password "Secret"

Attribute	Note
text	`string` to store

source:widgets/password.r

pie-chart*

A pie-chart.

pie-chart data [
    "Red" red 60
    "Green" green 30
    "Blue" blue 10
]

Attribute	Note
data	`block` of label/color/quantity values
options	`[no-label]` `[start n]` where n is the degrees value `[explode n]` when n is the number of pixels

source:widgets/pie-chart.r

progress

A horizontal progress indicator.

progress
progress data .5

Attribute	Note
data	`number` from 0 to 1 indicating percentage

source:widgets/progress.r

radio-group

A group of mutually exclusive radio buttons. Alignment is vertical unless height is specified as line height (5 units).

If you provide an integer as first entry in the block, this specifies the default selection. In this case the action of the radio-group won't be called.

Note from Robert: In my version of RebGUI radio-group uses IDs for each entry, so that storing the selection becomes position independend. The block looks like this in this case: [2 "Option-1" 1 "Option-2" 2 "Option-3" 3]

radio-group data ["Option-1" "Option-2" "Option-3"]
radio-group data [2 "Option-1" "Option-2" "Option-3"]

Attribute	Note
data	`block` with an optional `integer` indicating the default selection and one or more `string` radio labels
Runtime
picked	`integer` (or `none`) indicating current selection
selected	`string` value of currently selected option
select-item	`integer` position of item to select

source:widgets/radio-group.r

slider*

A slider control. Its size determines whether it is vertical or horizontal.

slider
slider silver data .5 [print face/data]

Attribute	Note
data	`decimal` from 0 to 1 indicating percentage
options	`[arrow]` arrows are to be added (creating a scroller) `[together]` arrows be placed together `[ratio n]` where n has the same value as above but indicates the initial dragger size

source:widgets/slider.r

spinner

Similar to a field, but with a left/right click button to increment/decrement a value by a nominated step amount.

spinner options [$1 $10 $1] data $5

Attribute	Note
options	`[min max step]` block `of min, max and step amounts (defaults` [1 10 1]`)
data	`any-type` amount (defaults to min)

source:widgets/spinner.r

splitter

Placed between two widgets on the same row or column, it allows both to be resized by dragging the splitter left/right or up/down respectively. Its size determines whether it is vertical or horizontal.

area
splitter black
area

source:widgets/splitter.r

symbol

Basic single-color shapes, such as those found on media players, on an "arrow" type button. Uses "Webdings" if available, otherwise simple ASCII equivalents.

symbol data 'start
symbol data 'rewind
symbol data 'left
symbol data 'pause
symbol data 'stop
symbol data 'record
symbol data 'right
symbol data 'forward
symbol data 'end
symbol -1 "Some text"

Attribute	Note
data	`word` specifying symbol to use
text	`string` to display

source:widgets/symbol.r

table*

Columns and rows of values formatted according to a header definition block.

table options ["Name" left .6 "Age" right .4] data [
    "Bob" 32
    "Pete" 45
    "Jack" 29
    "Mike" 25
    "Andy" 56
]

Attribute	Note
data	`block` of values
options	`[multi]` allows multiple rows to be selected at once `[no-dividers]` hides column dividers `[s w d]` `string`/`word`/`decimal` specifying column title/alignment & percentage width respectively
Runtime
data	`block` of values to display
picked	`block` of currently selected row number(s)
selected	`block` of currently selected data
redraw	`function` to redraw widget after data changes
add-row	Undocumented
remove-row	Undocumented
alter-row	Undocumented
select-row	Undocumented
set-columns	Undocumented

Important: When updating a table's data use insert clear face/data [...] instead of face/data: copy [...] as the data attribute is shared by the generic face-iterator function.

source:widgets/table.r

tab-panel

A panel with a set of tabs.

tab-panel data [
    "One" [field]
    "Two" [field field]
]

Attribute	Note
data	`block` of `string`/`block` (spec) pairs that specify each tab's layout (each spec may be preceded by an action `word`/`block` pair that is executed prior to the face being shown)
options	`[action]` do action of initial tab (if any) `[tab n]` where n specifies tab to initially open with (default 1)
Runtime
selected	Title `string` of currently selected tab

source:widgets/tab-panel.r

text

A box plus text.

text "A text string."

Attribute	Note
text	`string` to display