RebGUI Widget Reference

Author : Ashley G Trüter
Updated: 19-Oct-2008
Purpose: Describes the use and operation of the various RebGUI widgets.

Contents:

Each of the following sections describes a widget in detail with one or more of the following:

• Usage: one or more code samples demonstrating an aspect of the widget's use.
• Description: brief description of what the widget is and any other points of interest.
• Options: allowable specification options.
• Attributes: rebface attributes with a value other than none! (the default).
• Predefined feels: feel function(s) that have already been defined.
• Predefined actions: action function(s) that have already been defined.
• Extended attributes: attributes, other than functions, not present in the standard rebface object.
• Accessor functions: functions specific to the widget.

1. anim

USAGE:
    anim data [%images/go-previous.png %images/go-next.png]
    anim data [img1 img2 img3] rate 2

DESCRIPTION:
    Cycles a set of images at a specified rate.

ATTRIBUTES:
    size            -1x-1
    effect          fit
    rate            1
    options         block!
    init            function!

PREDEFINED FEELS:
    engage

Source code: anim.r

2. area

USAGE:
    area
    area "Text" -1
    area "Text" 50x-1

DESCRIPTION:
    Editable text area with wrapping and scroller.

OPTIONS:
    'info specifies read-only

ATTRIBUTES:
    size            50x25
    text            ""
    color           255.255.240
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw
    engage

PREDEFINED ACTIONS:
    on-scroll

EXTENDED ATTRIBUTES:
    esc             none
    caret           none
    undo            block!
    text-y          none
    key-scroll?     false

Source code: area.r

3. arrow

USAGE:
    arrow
    arrow 10
    arrow data 'up
    arrow data 'down
    arrow data 'left
    arrow data 'right

DESCRIPTION:
    An arrow (default down) on a square button face with height set to width.

ATTRIBUTES:
    size            5x-1
    effect          block!
    data            down
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw
    engage

Source code: arrow.r

4. bar

USAGE:
    bar 100

DESCRIPTION:
    A thin 3D bar used to separate widgets.
    Defaults to maximum display width.

ATTRIBUTES:
    size            -1x1
    color           204.204.204
    edge            object!
    options         block!
    rebind          function!

Source code: bar.r

5. box

USAGE:
    box red

DESCRIPTION:
    The most basic of widgets, a rectangular area.

ATTRIBUTES:
    size            25x25
    options         block!

Source code: box.r

6. button

USAGE:
    button "Hello"
    button -1 "Go!"
    button "Click me!" [print "click"]

DESCRIPTION:
    Performs action when clicked.

OPTIONS:
    'info specifies read-only

ATTRIBUTES:
    size            15x5
    text            ""
    color           136.187.0
    effect          block!
    font            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw
    over
    engage

PREDEFINED ACTIONS:
    on-resize

EXTENDED ATTRIBUTES:
    pen             none

ACCESSOR FUNCTIONS:
    FILL

Source code: button.r

7. calendar

USAGE:
    calendar
    calendar data 1-Jan-2000

DESCRIPTION:
    Used to select a date, with face/data set to current selection.
    Default selection is now/date.

ATTRIBUTES:
    size            70x48
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

Source code: calendar.r

8. chat

USAGE:
    chat 120 data ["Bob" blue "My comment." yello 14-Apr-2007/10:58]

DESCRIPTION:
    Three column chat display as found in IM apps such as AltME.
    Messages are appended, with those exceeding 'limit not shown.

OPTIONS:
    [limit n] where n specifies number of messages to show (default 100)
    [id n] where n specifies id column width (default 10)
    [user n] where n specifies user column width (default 15)
    [date n] where n specifies date column width (default 25)

ATTRIBUTES:
    size            200x100
    pane            block!
    data            block!
    edge            object!
    options         block!
    init            function!

PREDEFINED ACTIONS:
    on-resize

EXTENDED ATTRIBUTES:
    height          0
    rows            0
    limit           none

ACCESSOR FUNCTIONS:
    APPEND-MESSAGE user user-color msg msg-color date /no-show row
    SET-USER-COLOR id color
    SET-MESSAGE-TEXT id string
    SET-MESSAGE-COLOR id color
    REDRAW /no-show

Source code: chat.r

9. check

USAGE:
    check "Option"
    check "Option" data true
    check "Option" data false

DESCRIPTION:
    Tristate check-box with a green tick for Yes, a red cross for No, and empty being Unknown.
    Left and right mouse clicks alternate between Yes/No and Unknown respectively.

OPTIONS:
    'info specifies read-only
    'bistate disables right-click state

ATTRIBUTES:
    size            -1x5
    text            ""
    effect          block!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw
    over
    engage

Source code: check.r

10. check-group

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

DESCRIPTION:
    Group of check boxes.
    Alignment is vertical unless height is specified as line height.
    At runtime face/data is a block of logic (or none) indicating state of each check box.

OPTIONS:
    'info specifies read-only
    'bistate disables right-click state

ATTRIBUTES:
    size            50x-1
    pane            block!
    options         block!
    init            function!

Source code: check-group.r

11. drop-list

USAGE:
    drop-list "1" data [1 2 3]
    drop-list data ["One" "Two" "Three"]
    drop-list data ctx-rebgui/locale*/colors

DESCRIPTION:
    Single column modal selection list.
    At runtime face/text contains current selection.

ATTRIBUTES:
    size            25x5
    text            ""
    color           204.204.204
    data            block!
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    engage

PREDEFINED ACTIONS:
    on-unfocus

EXTENDED ATTRIBUTES:
    hidden-caret    none
    hidden-text     none

ACCESSOR FUNCTIONS:
    PICKED

Source code: drop-list.r

12. edit-list

USAGE:
    edit-list "1" data [1 2 3]
    edit-list data ["One" "Two" "Three"]
    edit-list data ctx-rebgui/locale*/colors

DESCRIPTION:
    Editable single column modal selection list.
    At runtime face/text contains current selection.

ATTRIBUTES:
    size            25x5
    text            ""
    color           255.255.240
    data            block!
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    engage

PREDEFINED ACTIONS:
    on-unfocus

EXTENDED ATTRIBUTES:
    hidden-caret    none
    hidden-text     none
    caret           none

ACCESSOR FUNCTIONS:
    PICKED

Source code: edit-list.r

13. field

USAGE:
    field
    field -1 "String"

DESCRIPTION:
    Editable text field with no text wrapping.

OPTIONS:
    'info specifies read-only

ATTRIBUTES:
    size            50x5
    text            ""
    color           255.255.240
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    engage

EXTENDED ATTRIBUTES:
    esc             none
    caret           none
    undo            block!

Source code: field.r

14. group-box

USAGE:
    group-box "Title" data [field field]

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

ATTRIBUTES:
    size            -1x-1
    text            "Untitled"
    effect          block!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw

PREDEFINED ACTIONS:
    on-resize

Source code: group-box.r

15. heading

USAGE:
    heading "A text heading."

DESCRIPTION:
    Large text.

ATTRIBUTES:
    size            -1x-1
    text            ""
    font            object!
    para            object!
    options         block!
    init            function!

Source code: heading.r

16. image

USAGE:
    image %images/logo.png
    image logo
    image logo effect [crop 10x10 50x50]

DESCRIPTION:
    An image.

ATTRIBUTES:
    size            -1x-1
    effect          fit
    options         block!
    init            function!

Source code: image.r

17. label

USAGE:
    label "A text label."

DESCRIPTION:
    Bold text.

ATTRIBUTES:
    size            -1x-1
    text            ""
    font            object!
    para            object!
    options         block!
    init            function!

Source code: label.r

18. led

USAGE:
    led "Option"
    led "Option" data true
    led "Option" data false
    led "Option" data none

DESCRIPTION:
    Tristate indicator box with colors representing Yes & No, and empty being Unknown.

ATTRIBUTES:
    size            -1x5
    effect          block!
    font            object!
    para            object!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

Source code: led.r

19. led-group

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

DESCRIPTION:
    Group of LED indicators.
    Alignment is vertical unless height is specified as line height.
    At runtime face/data is a block of logic (or none) indicating state of each LED indicator.

ATTRIBUTES:
    size            50x-1
    pane            block!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

Source code: led-group.r

20. link

USAGE:
    link
    link http://www.dobeash.com
    link "RebGUI" http://www.dobeash.com/rebgui

DESCRIPTION:
    Hypertext link.

ATTRIBUTES:
    size            -1x5
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    over
    engage

Source code: link.r

21. menu

USAGE:
    menu data ["Item-1" ["Choice 1" [alert "1"] "Choice 2" [alert "2"] ] "Item-2" [] ]

DESCRIPTION:
    Simple one-level text-only menu system.

ATTRIBUTES:
    size            100x5
    pane            block!
    color           204.204.204
    options         block!
    rebind          function!
    init            function!

Source code: menu.r

22. panel

USAGE:
    panel sky data [after 1 field field]

DESCRIPTION:
    A static widget used to group widgets within a container.

ATTRIBUTES:
    size            -1x-1
    color           236.236.236
    effect          block!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw

PREDEFINED ACTIONS:
    on-resize

EXTENDED ATTRIBUTES:
    pen             none

ACCESSOR FUNCTIONS:
    FILL

Source code: panel.r

23. password

USAGE:
    password
    password "Secret"

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

ATTRIBUTES:
    size            50x5
    text            ""
    color           255.255.240
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    engage

EXTENDED ATTRIBUTES:
    esc             none
    caret           none
    undo            block!

Source code: password.r

24. pie-chart

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

DESCRIPTION:
    A pie-chart.

OPTIONS:
    'no-label to turn labels off
    [start n] where n is the degrees value
    [explode n] when n is the number of pixels

ATTRIBUTES:
    size            50x50
    effect          block!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

EXTENDED ATTRIBUTES:
    sum             0
    explode         0
    degrees         270

Source code: pie-chart.r

25. pill

USAGE:
    pill red

DESCRIPTION:
    A rectangular area with rounded corners.

ATTRIBUTES:
    size            10x10
    effect          block!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

PREDEFINED ACTIONS:
    on-resize

EXTENDED ATTRIBUTES:
    pen             none

ACCESSOR FUNCTIONS:
    FILL

Source code: pill.r

26. progress

USAGE:
    progress
    progress data .5

DESCRIPTION:
    A horizontal progress indicator.
    At runtime face/data ranges from 0 to 1 indicating percentage.

ATTRIBUTES:
    size            50x5
    effect          block!
    data            0
    edge            object!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw

PREDEFINED ACTIONS:
    on-resize

Source code: progress.r

27. radio-group

USAGE:
    radio-group data ["Option A" "Option B"]
    radio-group data [2 "On" "Off"]

DESCRIPTION:
    Group of mutually exclusive radio buttons.
    Alignment is vertical unless height is specified as line height.
    An integer provided as the first entry in the block indicates the default selection.

ATTRIBUTES:
    size            50x-1
    pane            block!
    options         block!
    init            function!

EXTENDED ATTRIBUTES:
    picked          none

ACCESSOR FUNCTIONS:
    SELECTED
    SELECT-ITEM item

Source code: radio-group.r

28. scroll-panel

USAGE:
    scroll-panel data [sheet]

DESCRIPTION:
    A panel used to group widgets within a scrollable container.

OPTIONS:
    'offset keeps the original offset

ATTRIBUTES:
    size            50x50
    pane            block!
    edge            object!
    options         block!
    init            function!

PREDEFINED ACTIONS:
    on-click
    on-resize
    on-scroll

EXTENDED ATTRIBUTES:
    p1              none
    p2              none
    p3              none
    p4              none
    sld-offset      0x0

Source code: scroll-panel.r

29. sheet

USAGE:
    sheet
    sheet options [size 3x3 width 2]
    sheet options [size 3x3 widths [2 3 4] ]
    sheet data [A1 1 A2 2 A3 "=A1 + A2"]

DESCRIPTION:
    Simple spreadsheet, based on rebocalc.r, with formulas calculated left to right, top to bottom.
    A cell is either a scalar value, string, or a formula starting with "=".
    Scalar values are automatically right-justified, series values left-justified.
    Remember to put spaces between each item in a formula and use () where needed.

OPTIONS:
    'size specifies number of columns and rows
    'width specifies cell width in relation to cell height
    'widths specifies n cell widths

ATTRIBUTES:
    size            -1x-1
    pane            block!
    color           204.204.204
    data            block!
    options         block!
    init            function!

EXTENDED ATTRIBUTES:
    cells           none

ACCESSOR FUNCTIONS:
    LOAD-DATA dat
    SAVE-DATA
    ENTER face
    COMPUTE

Source code: sheet.r

30. slider

USAGE:
    slider
    slider data .5 [print face/data]

DESCRIPTION:
    A slider control. Its size determines whether it is vertical or horizontal.
    At runtime face/data ranges from 0 to 1 indicating percentage.

OPTIONS:
    'arrows adds an arrow to each end of the slider creating a scroller
    'together forces the arrows to appear together
    [ratio n] where n indicates the initial dragger size

ATTRIBUTES:
    size            5x50
    color           204.204.204
    effect          block!
    data            0
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    redraw
    engage

EXTENDED ATTRIBUTES:
    ratio           0.1
    step            5E-2
    hold            none
    state           none
    flags           none

ACCESSOR FUNCTIONS:
    SET-DATA new

Source code: slider.r

31. spinner

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

DESCRIPTION:
    Similar to a field, with arrows to increment/decrement a value by a nominated step amount.

OPTIONS:
    [min max step] block of minimum, maximum and step amounts

ATTRIBUTES:
    size            20x5
    pane            block!
    text            ""
    color           255.255.240
    edge            object!
    font            object!
    para            object!
    options         block!
    rebind          function!
    init            function!

PREDEFINED FEELS:
    engage

PREDEFINED ACTIONS:
    on-scroll
    on-unfocus

EXTENDED ATTRIBUTES:
    esc             none
    caret           none
    undo            block!

Source code: spinner.r

32. splitter

USAGE:
    area splitter area

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

ATTRIBUTES:
    size            1x25
    color           204.204.204
    options         block!
    rebind          function!

PREDEFINED FEELS:
    redraw
    over
    engage

Source code: splitter.r

33. style

USAGE:
    style 20x20 data [btn "VID btn"]
    style data [btn 20x20] options [size]

DESCRIPTION:
    A container for a VID style.

OPTIONS:
    'size use VID style size.

ATTRIBUTES:
    size            5x5
    data            block!
    options         block!
    init            function!

Source code: style.r

34. symbol

USAGE:
    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 data 'up
    symbol data 'down
    symbol -1 "Some text"

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

ATTRIBUTES:
    size            5x-1
    text            ""
    edge            object!
    font            object!
    options         block!
    init            function!

PREDEFINED FEELS:
    redraw
    engage

PREDEFINED ACTIONS:
    on-resize

Source code: symbol.r

35. tab-panel

USAGE:
    tab-panel data ["A" [field] "B" [field] "C" [field] ]
    tab-panel data ["1" [field] action [face/color: red] "2" [field] ]

DESCRIPTION:
    A panel with a set of tabs.
    Each tab spec may be preceded by an action block spec.

OPTIONS:
    'action do action of initial tab (if any)
    [tab n] where n specifies tab to initially open with (default 1)
    no-tabs do not display tabs (overlay mode)

ATTRIBUTES:
    size            -1x-1
    pane            block!
    options         block!
    init            function!

EXTENDED ATTRIBUTES:
    tabs            0

ACCESSOR FUNCTIONS:
    SELECTED
    SELECT-TAB num
    REPLACE-TAB num block /title text

Source code: tab-panel.r

36. table

USAGE:
    table options ["Name" left .6 "Age" right .4] data ["Bob" 32 "Pete" 45 "Jack" 29]

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

OPTIONS:
    'multi allows multiple rows to be selected at once
    'no-dividers hides column dividers
    ["Title" align width] triplets for each column

ATTRIBUTES:
    size            50x25
    pane            block!
    color           255.255.240
    data            block!
    edge            object!
    options         block!
    rebind          function!
    init            function!

EXTENDED ATTRIBUTES:
    picked          block!
    widths          block!
    aligns          block!
    cols            none
    total-width     none

ACCESSOR FUNCTIONS:
    REDRAW
    SELECTED
    ROWS
    ADD-ROW row /position pos
    REMOVE-ROW row
    ALTER-ROW row values
    SELECT-ROW row /no-action
    SET-COLUMNS options /no-show /no-dividers

Source code: table.r

37. text

USAGE:
    text "A text string."
    text "Blue text" text-color blue
    text "Bold text" bold
    text "Italic text" italic
    text "Underline text" underline

DESCRIPTION:
    Normal text.

ATTRIBUTES:
    size            -1x-1
    text            ""
    font            object!
    para            object!
    options         block!
    init            function!

Source code: text.r

38. text-list

USAGE:
    text-list data ["One" "Two"]
    text-list data ctx-rebgui/locale*/colors
    text-list data [1 2]  [print face/selected]

DESCRIPTION:
    A single column list with a scroller.

OPTIONS:
    'multi allows multiple rows to be selected at once

ATTRIBUTES:
    size            50x25
    color           255.255.240
    data            block!
    edge            object!
    options         block!
    rebind          function!
    init            function!

EXTENDED ATTRIBUTES:
    picked          block!

ACCESSOR FUNCTIONS:
    REDRAW
    SELECTED
    ROWS
    SELECT-ROW row /no-action

Source code: text-list.r

39. title-group

USAGE:
    title-group %images/setup.png data "Title" "Body"

DESCRIPTION:
    A title and text with an optional image to the left.
    If an image is specified then height is set to image height.

ATTRIBUTES:
    size            100x100
    font            object!
    options         block!
    rebind          function!
    init            function!

Source code: title-group.r

40. tool-bar

USAGE:
    tool-bar silver data ["Open" %images/document-open.png [request-file] pad 2 none "Save" %images/document-save.png [] ]

DESCRIPTION:
    An iconic toolbar. Height is set to 30 pixels.
    [pad n none] sequence works as per 'pad in the display function.

ATTRIBUTES:
    size            100x-1
    pane            block!
    color           204.204.204
    options         block!
    rebind          function!
    init            function!

Source code: tool-bar.r

41. tooltip

USAGE:
    tooltip "Some text."

DESCRIPTION:
    Tooltip text.

ATTRIBUTES:
    size            -1x-1
    effect          block!
    font            object!
    para            object!
    rate            2
    options         block!
    init            function!

Source code: tooltip.r

42. tree

USAGE:
    tree data ["Pets" ["Cat" "Dog"] "Numbers" [1 2 3] ]

DESCRIPTION:
    Values arranged in a collapsible hierarchy.

OPTIONS:
    'expand starts with all nodes expanded
    'resize change face/size as tree is expanded / collapsed

ATTRIBUTES:
    size            50x25
    pane            block!
    color           255.255.240
    data            block!
    edge            object!
    options         block!
    rebind          function!
    init            function!

EXTENDED ATTRIBUTES:
    chain           none
    pos             none
    expand?         none
    p               none
    old-face        none
    width           0
    height          0

ACCESSOR FUNCTIONS:
    SHOW-NODE items /no-expand
    SHOW-TREE
    BUILD-TREE items

Source code: tree.r