USR Actors - GiuseppeChillemi/VID-Extension-Kit GitHub Wiki
VID Extension Kit - Actors
Actors are defined here https://github.com/GiuseppeChillemi/VID-Extension-Kit/blob/master/source/vid.r
Introduction
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.
Actors
Using Actors
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.
Calling Actors
When creating your own styles or when using actors, you call actors by the ACT-FACE function:
act-face face 'on-click
Attach Actor Functions
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.
Remove Actor Functions
You can remove actor functions by using the REMOVE-ACTOR-FUNC function:
remove-actor-func face 'on-click :my-func
Passing Actors
Normally, when assigning 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.
Example:
pass-actor face1 face2 'on-click
Debugging Actors
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
Reference
Mouse Input
ON-CLICK
This is run when left clicking on a button, a field or other item.
ON-ALT-CLICK
This is run when right clicking on a button, a field
ON-DOUBLE-CLICK
This is run when double clicking a button or a list item.
Accessor
ON-SETUP
This actor is called during SETUP-FACE.
ON-SET
This is run on SET-FACE.
ON-CLEAR
This is run on CLEAR-FACE.
ON-RESET
This is run on RESET-FACE.
ON-SCROLL
This actor is called, whenever a face needs to be scrolled using SCROLL-FACE.
ON-SEARCH
This is run on SEARCH-FACE.
ON-QUERY
This is run on QUERY-FACE.
ON-EDIT
This is run on EDIT-FACE.
ON-SELECT
This is run on SELECT-FACE, when a range is specified.
ON-UNSELECT
This is run on SELECT-FACE, when the specified range is NONE.
ON-ENABLE
This is run on ENABLE-FACE.
ON-DISABLE
This is run on DISABLE-FACE.
ON-FREEZE
This is run on FREEZE-FACE.
ON-THAW
This is run on THAW-FACE.
ON-REFRESH
This is run on REFRESH-FACE, whenever the data source of the face has changed.
Keyboard
ON-KEY
This actor is called whenever you press a key, when the face is focused.
ON-TAB
This actor is called whenever you press the TAB key, when the face is focused.
ON-RETURN
This actor is called whenever you press the RETURN key, when the face is focused.
ON-ESCAPE
This actor is called whenever you press the ESCAPE key, when the face is focused.
Focusing
ON-FOCUS
This actor is called whenever a face goes into focus, i.e. gets the focus ring.
ON-UNFOCUS
This actor is called whenever a face loses its focus, i.e. has the focus ring removed, such as when pressing the TAB key.
Resizing
ON-RESIZE
This actor is called, whenever the window resizes.
ON-ALIGN
This actor is called, whenever the window is aligned, which usually only is directly after layout.
Validation
ON-VALIDATE
This is run on validation.
ON-INIT-VALIDATE
This is run on initial validation.
Window Handling
ON-INIT-WINDOW
When the window is initialized.
ON-ACTIVATE
This is run, when the window is activated.
ON-DEACTIVATE
When the window is deactivated.
ON-MAXIMIZE
When the window is maximized.
ON-MINIMIZE
When the window is minimized.
ON-RESTORE
When the window is restored from minimization.
ON-TEXT
When the title of the window changes.
ON-OFFSET
When the window moves.
Other Events
ON-TIME
This actor is called when a FACE/RATE event has occurred.
ON-HIGHLIGHT
When a data element (table row, text part, etc.) in the face is highlighted.
UNDOCUMENTED: TBD:
on-drag
on-resize-window
on-move-window
on-close-window
on-change
on-redraw
ON-CLOSE-WINDOW
ON-RESIZE-WINDOW
ON-MOVE-WINDOW
ON-INIT-WINDOW
ON-RESIZE-WINDOW,
ON-MAXIMIZE
ON-MOVE-WINDOW
New and undocumented Accessors
GET-FACE-SETUP
SET-FACE-DEFAULT
GET-FACE-DEFAULT
CLEAR-FACE-DEFAULT
UNSELECT-FACE accessor to unselect rows in tables
GET-SELECT-FACE accessor to retrieve selection indexes from tables
alter behavior of SELECT-FACE when using MUTEX select mode, so that only one row is selected
SELECT-FACE now has an INVERT value option
Actors are defined here https://github.com/GiuseppeChillemi/VID-Extension-Kit/blob/master/source/vid.r