RebGUI Function Reference

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

Contents:

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

• Usage: complete function syntax.
• Description: brief description of what the function does.
• Arguments: values, and optionally their type(s), expected by the function.
• Refinements: flags & optional arguments that control or modify the function's behavior.

1. alert

USAGE:
    ALERT message /title text

DESCRIPTION:
    Prompts to acknowledge a message.

ARGUMENTS:
    message [string!]               -- Message text

REFINEMENTS:
    /title text [string!]           -- Title text

Source code: alert.r

2. append-widget

USAGE:
    APPEND-WIDGET spec

DESCRIPTION:
    Append a custom widget to widgets context.

ARGUMENTS:
    spec [block!]                   -- Widget spec

Source code: append-widget.r

3. clear-text

USAGE:
    CLEAR-TEXT face /no-show /focus

DESCRIPTION:
    Clear text attribute of a widget or block of widgets.

ARGUMENTS:
    face [object! block!]

REFINEMENTS:
    /no-show                        -- Don't show
    /focus

Source code: clear-text.r

4. display

USAGE:
    DISPLAY title spec /dialog /maximize /parent /position offset /min-size size /close closer

DESCRIPTION:
    Displays widgets in a centered window with a title.

ARGUMENTS:
    title [string!]                 -- Window title
    spec [block!]                   -- Block of widgets, attributes and keywords

REFINEMENTS:
    /dialog                         -- Displays widgets in a modal popup window with /parent option
    /maximize                       -- Maximize window
    /parent                         -- Force parent to be last window (default is first)
    /position                       -- Use an alternative positioning scheme
        offset [pair! word! block!] -- Offset pair or one or more of 'left 'right 'top 'bottom 'first 'second
    /min-size                       -- Specify a minimum OS window resize size
        size [pair!]                -- Minimum display size (including window border/title)
    /close                          -- Handle window close event
        closer [block!]             -- The close handler block

Source code: display.r

5. examine

USAGE:
    EXAMINE widget /indent /no-print

DESCRIPTION:
    Prints information about widgets and attributes.

ARGUMENTS:
    'widget

REFINEMENTS:
    /indent                         -- Indent output as an MD2 ready string
    /no-print                       -- Do not print output to console

Source code: examine.r

6. get-values

USAGE:
    GET-VALUES face /type

DESCRIPTION:
    Gets values from input widgets within a display or grouping widget.

ARGUMENTS:
    face [object!]                  -- Display face

REFINEMENTS:
    /type                           -- Precede each value with its type

Source code: get-values.r

7. question

USAGE:
    QUESTION message /title text

DESCRIPTION:
    Requests a Yes/No answer to a question.

ARGUMENTS:
    message [string!]               -- Message text

REFINEMENTS:
    /title text [string!]           -- Title text

Source code: question.r

8. request-char

USAGE:
    REQUEST-CHAR /title text /font name

DESCRIPTION:
    Requests a character.

REFINEMENTS:
    /title text [string!]           -- Title text
    /font name [string!]            -- Font to use

Source code: request-char.r

9. request-color

USAGE:
    REQUEST-COLOR /title text /color clr /allow-none

DESCRIPTION:
    Requests a color.

REFINEMENTS:
    /title text [string!]           -- Title text
    /color clr [tuple!]             -- Default color
    /allow-none                     -- Allow none as a value

Source code: request-color.r

10. request-date

USAGE:
    REQUEST-DATE /title text /date dt

DESCRIPTION:
    Requests a date.

REFINEMENTS:
    /title text [string!]           -- Title text
    /date dt [date!]                -- Initial date to show (default is today)

Source code: request-date.r

11. request-dir

USAGE:
    REQUEST-DIR /title text /path dir /expand

DESCRIPTION:
    Requests a directory.

REFINEMENTS:
    /title text [string!]           -- Title text
    /path dir [file!]               -- Set starting directory
    /expand                         -- Start with all nodes expanded

Source code: request-dir.r

12. request-file

USAGE:
    REQUEST-FILE /title text /file path /filter name mask /only /save

DESCRIPTION:
    Requests a file using a popup list of files and directories.

REFINEMENTS:
    /title text [string!]           -- Title text
    /file path [file! block!]       -- Default file name or block of file names
    /filter name [string!] mask [string!]
    /only                           -- Return only a single file, not a block
    /save                           -- Request file for saving, otherwise loading

Source code: request-file.r

13. request-font

USAGE:
    REQUEST-FONT /title text /style /size /align

DESCRIPTION:
    Requests a font name, returning a string.

REFINEMENTS:
    /title text [string!]           -- Title text
    /style                          -- Adds a style selector (returns font! object!)
    /size                           -- Adds a size selector (returns font! object!)
    /align                          -- Adds an alignment selector (returns font! object!)

Source code: request-font.r

14. request-menu

USAGE:
    REQUEST-MENU face menu /width x /offset xy

DESCRIPTION:
    Requests a menu choice.

ARGUMENTS:
    face [object!]                  -- Widget to appear in relation to
    menu [block!]                   -- Label/Action block pairs

REFINEMENTS:
    /width x [integer!]             -- Width in pixels (defaults to 25 units)
    /offset xy [pair!]              -- Offset relative to widget (defaults to top right)

Source code: request-menu.r

15. request-password

USAGE:
    REQUEST-PASSWORD /title text /user username /pass password /check rules /only /verify

DESCRIPTION:
    Requests a username and password.

REFINEMENTS:
    /title text [string!]           -- Title text
    /user username [string!]        -- Default username
    /pass password [string!]        -- Default password
    /check rules [block!]           -- Rules to test password against (fails if string returned)
    /only                           -- Password only
    /verify                         -- Verify password

Source code: request-password.r

16. request-progress

USAGE:
    REQUEST-PROGRESS steps block /title text

DESCRIPTION:
    Requests a progress dialog for an action block.

ARGUMENTS:
    steps [integer!]                -- Number of iterations
    block [block!]                  -- Action block

REFINEMENTS:
    /title text [string!]           -- Title text

Source code: request-progress.r

17. request-spellcheck

USAGE:
    REQUEST-SPELLCHECK face /title text /anagram

DESCRIPTION:
    Requests spellcheck on a widget's text.

ARGUMENTS:
    face [object!]

REFINEMENTS:
    /title text [string!]           -- Title text
    /anagram                        -- Anagram option

Source code: request-spellcheck.r

18. request-ui

USAGE:
    REQUEST-UI /title text /file name

DESCRIPTION:
    Requests UI changes.

REFINEMENTS:
    /title text [string!]           -- Title text
    /file name [file!]              -- Set file to save changes (default is ui.dat)

Source code: request-ui.r

19. request-value

USAGE:
    REQUEST-VALUE prompt /title text /default value /type datatype

DESCRIPTION:
    Requests a value.

ARGUMENTS:
    prompt [string!]                -- Prompt text

REFINEMENTS:
    /title text [string!]           -- Title text
    /default value [any-type!]      -- Default value
    /type datatype [datatype!]      -- Return type

Source code: request-value.r

20. set-color

USAGE:
    SET-COLOR face color /no-show

DESCRIPTION:
    Set and show a widget's color attribute.

ARGUMENTS:
    face [object!]
    color [tuple! none!]

REFINEMENTS:
    /no-show                        -- Don't show

Source code: set-color.r

21. set-data

USAGE:
    SET-DATA face data /no-show

DESCRIPTION:
    Set and show a widget's data attribute.

ARGUMENTS:
    face [object!]
    data [any-type!]

REFINEMENTS:
    /no-show                        -- Don't show

Source code: set-data.r

22. set-focus

USAGE:
    SET-FOCUS face /caret

DESCRIPTION:
    Set and show widget focus.

ARGUMENTS:
    face [object!]

REFINEMENTS:
    /caret

Source code: set-focus.r

23. set-locale

USAGE:
    SET-LOCALE language

DESCRIPTION:
    Dynamically set/change locale.

ARGUMENTS:
    language [string! none!]

Source code: set-locale.r

24. set-state

USAGE:
    SET-STATE face /info /edit

DESCRIPTION:
    Toggle and show widget state.

ARGUMENTS:
    face [object!]

REFINEMENTS:
    /info                           -- Exit if already info.
    /edit                           -- Exit if already edit.

Source code: set-state.r

25. set-text

USAGE:
    SET-TEXT face text /caret /no-show /focus

DESCRIPTION:
    Set and show a widget's text attribute.

ARGUMENTS:
    face [object!]                  -- Widget
    text [any-type!]                -- Text

REFINEMENTS:
    /caret                          -- Insert at cursor position (tail if none)
    /no-show                        -- Don't show
    /focus

Source code: set-text.r

26. set-text-color

USAGE:
    SET-TEXT-COLOR face color /no-show

DESCRIPTION:
    Set and show a widget's font color attribute.

ARGUMENTS:
    face [object!]
    color [tuple! none!]

REFINEMENTS:
    /no-show                        -- Don't show

Source code: set-text-color.r

27. set-texts

USAGE:
    SET-TEXTS faces text /no-show

DESCRIPTION:
    Set and show text attribute of a block of widgets.

ARGUMENTS:
    faces [block!]                  -- Widgets
    text [any-type!]                -- Text or block of text

REFINEMENTS:
    /no-show                        -- Don't show

Source code: set-texts.r

28. set-title

USAGE:
    SET-TITLE face title

DESCRIPTION:
    Set and show window title.

ARGUMENTS:
    face [object!]                  -- Window dialog face
    title [string!]                 -- Window bar title

Source code: set-title.r

29. set-values

USAGE:
    SET-VALUES face blk /no-show

DESCRIPTION:
    Puts values into input widgets within a display or grouping widget.

ARGUMENTS:
    face [object!]                  -- Display face
    blk [block!]                    -- Block of values (or 'skip)

REFINEMENTS:
    /no-show                        -- Don't show

Source code: set-values.r

30. splash

USAGE:
    SPLASH spec

DESCRIPTION:
    Displays a centered splash screen for one or more seconds.

ARGUMENTS:
    spec [block! file! image!]      -- The face spec or image to display

Source code: splash.r

31. translate

USAGE:
    TRANSLATE text

DESCRIPTION:
    Dynamically translate a string or block of strings.

ARGUMENTS:
    text                            -- String (or block of strings) to translate

Source code: translate.r