Docs Blog Get-it

R3 GUI Reactors

Technical documentation for developers.
Part of the R3 Graphical User Interface (GUI).
New users should read the R3 GUI - User's Guide.


Events on GUI faces trigger reactors.

When a user pushes a button, something happens. The GUI reacts to user input. The result may be a common action such as opening or closing a window, or it may be a very specific action. A reactor is just a type of shortcut for a common action. They make the GUI easier to use by eliminating the need to write detailed code.

Reactors are attached to faces and are invoked by the actors of its style. A reactor can include a single argument value. If more than one argument is needed, they must be enclosed in a block.

Multiple reactors can be attached to the same face. Each reactor is processed in the order that it appears, so the consequences of a reactor's actions must be considered; it can impact the reactors that follow.

Using Reactors

Reactors are specified in the GUI dialect that is used to create a panels.

For example, here's a panel that opens a window and displays three buttons, each of which that specifies a reactor:

view [
    button "REBOL" browse
    button "Alert" alert "This is an alert."
    button "Close" close

The obvious actions occur when each button is pressed. The browse reactor opens a web browser, the alert opens a pop-up alert panel, and close will close the current window.

Standard Reactors

These reactor functions are provided as a standard part of the GUI:

Reactor Description
alert open an alert message box window
attach set a target value to our value
back return to prior panel (on panel stack)
browse open web browser to given URL
call run a shell script on local OS
clear clear face value (empty it)
close close the window
debug trace face operation
do evaluate a REBOL block, file, or URL
download opens download progress panel, starts download
dump probe the contents of the related face object
edit opens editor for specified content
halt halt the interpreter
link fetch reb content and evaluate it
launch run file or URL in a new instance of REBOL
open open a file using local OS methods
quit exit the application
play plays a sound
print print output
reset reset face to original value
scroll scroll a target face
send sends a message to a target
set set the state of another face
submit submit face (or panel) to service or website
undo undo last change
upload opens upload progress panel, starts upload
view view a new "page"

Here are a few examples:

button "Alert" alert "This is an alert."
button "Browse" browse
button "Close" close
button "Do" do [alert "It worked!"]
button "Dump" dump
button "Halt" halt
button "Launch" launch %test.r
button "Print" print "print to console"
button "Quit" quit
button "Run" run %explorer.exe
button "View" view [button "Close" close]

f1: field "Field 1"
button "Focus on 1" focus 'f1

Multiple Reactors

A face can have more than one reactor. Each reactor is processed in the order that it appears. The example below shows how two fields are reset using a single reset button:

user: field
pass: field
button "Reset" reset 'user reset 'pass

Reactors are processed from left to right, so be sure to consider that.

For example, this line works:

button "Submit" submit cgi-url clear 'user

But, in this line the field is cleared, so the submitted text is empty:

button "Submit" clear 'user submit cgi-url

So, that's not useful.

Creating Custom Reactors

The make-reactor function can be called to create custom reactors for your GUI. One or more new reactors can be defined. The format of a reactor definition is similar to that of a function, except the function creator such as func is not used.

Here's an example reactor definition:

make-reactor [
    my-browse: ["Open web browser." arg [url! file!]] [browse arg]

Calling Reactors

When implmenting a style actor, when a final result is known, it may be necessary to call one or more face reactors.

The do-face function calls reactors. This line calls all reactors:

do-face face

To call a specific reactor, you can write:

do-face/only face 'reactor

where reactor is its name.


Here's an example panel that uses a few different reactors:

view [
    panel 2 [
        button "Do" do [request "Got it!" "It worked."]
        button "Browse" browse
        button "Run" run %explorer
        button "Alert" alert "This is an alert."
    panel 2 [
        f1: field "Field 1"
        f2: field "Field 2"
        button "Focus on 1" focus 'f1
        button "Focus on 2" focus 'f2
    panel 2 [
        button "Close" close
        button "Halt" halt
        button "Quit" quit
        button "Print" print "print this message"
        button "Dump" dump
About | Contact | PrivacyREBOL Technologies 2021