VID Extension Kit - Actors
Actors are an easy-access way to perform a task on a specific event, such as doing something on a button click or when a list face refreshes its content.
Basically there is just a list of actors and each one does something differently at different times.
Actors are primarily used in FEEL objects and in styles, but you can call any actor in any face at any time.
There are no fixed rules on when to call an actor, so this document also serves as a list of rules on when to use particular actors as a style writer.
To use an actor in your layout, simply add the actor word with a block:
view make-window [ button on-click [print "Hello World"] ]
Which actors you can use, is listed in the reference section below.
When creating your own styles or when using actors, you call actors by the ACT-FACE function:
act-face face 'on-click
Each face has an actor object in FACE/ACTORS. This provides a complete list of functions that are attached to this face.
Each actor in the object contains a block, where all functions reside. When ACT-FACE is called on this actor, all functions in that block are run in sequence. Any actor can contain any number of functions.
To insert a new actor function for a face, you use the INSERT-ACTOR-FUNC function:
my-func: func [face value event actor] [now] insert-actor-func face 'on-click :my-func
The function can support up to 4 arguments. You don't have to use them all, but the arguments will be served in the following order:
|face||The face for which the actor is called.|
|value||The value passed to the function via GET-FACE.|
|event||The event object that was present, when ACT-FACE was called. Sometimes, there can be no event object, if ACT-FACE is run outside a FEEL object, so the value will then be NONE.|
|actor||The name of the actor that is called by ACT-FACE.|
When attempting to insert the same function multiple times, INSERT-ACTOR-FUNC first investigates, if the function already exists in the block. If it does, the insertion is skipped.
You can remove actor functions by using the REMOVE-ACTOR-FUNC function:
remove-actor-func face 'on-click :my-func
Normally, when assigining actor functions, the functions are assigned to a single face.
Some compound faces will require the use of the same actors, such as when a DATA-LIST needs to pass an ON-CLICK actor to the LIST style that is used inside it.
This is done by passing the actor functions between faces, using the actors object. Each actor stores actor functions in a block that is then performed in sequence. The functions are stored along with the face that was originally assigned using INSERT-ACTOR-FUNC.
pass-actor face1 face2 'on-click
Actors can be debugged, as in you can see which actors are called in the console, if inserting the 'actors flag in CTX-VID-DEBUG:
insert ctx-vid-debug/debug 'actors
This is run when left clicking on a button, a field or other item.
This is run when right clicking on a button, a field
This is run when double clicking a button or a list item.
This actor is called during SETUP-FACE.
This is run on SET-FACE.
This is run on CLEAR-FACE.
This is run on RESET-FACE.
This actor is called, whenever a face needs to be scrolled using SCROLL-FACE.
This is run on SEARCH-FACE.
This is run on QUERY-FACE.
This is run on EDIT-FACE.
This is run on SELECT-FACE, when a range is specified.
This is run on SELECT-FACE, when the specified range is NONE.
This is run on ENABLE-FACE.
This is run on DISABLE-FACE.
This is run on FREEZE-FACE.
This is run on THAW-FACE.
This is run on REFRESH-FACE, whenever the data source of the face has changed.
This actor is called whenever you press a key, when the face is focused.
This actor is called whenever you press the TAB key, when the face is focused.
This actor is called whenever you press the RETURN key, when the face is focused.
This actor is called whenever you press the ESCAPE key, when the face is focused.
This actor is called whenever a face goes into focus, i.e. gets the focus ring.
This actor is called whenever a face loses its focus, i.e. has the focus ring removed, such as when pressing the TAB key.
This actor is called, whenever the window resizes.
This actor is called, whenever the window is aligned, which usually only is directly after layout.
This is run on validation.
This is run on initial validation.
When the window is initialized.
This is run, when the window is activated.
When the window is deactivated.
When the window is maximized.
When the window is minimized.
When the window is restored from minimization.
When the title of the window changes.
When the window moves.
This actor is called when a FACE/RATE event has occurred.
When a data element (table row, text part, etc.) in the face is highlighted.