18.7 Handling actions
Every Presentation can be configured to react to Actions. Actions represent commands that are to be triggered by the user.
Actions are described by three parameters: title
, key
, and icon
. An action with a title appears in the contextual menu of the presentation. If the action has an icon attached, it has the chance of appearing in the toolbar of a browser. An action with a key is mapped on a shortcut involving the platform modifier and the key (e.g., on Mac it is CMD+key).
The protocol to create actions has several selectors to accommodate the possible combinations. The most basic ones are as follows:
-
act:entitled:
sets the title; -
act:icon:entitled:
sets the icon and the title; -
act:on:
sets the shortcut.
The act:
expects a block with several optional parameters: the first parameter is given by the presentation object, and the rest are populated by the input entities.
By providing access to the presentation object, the Action also enable the population of the ports of the pane holding the presentation.
For example, if we want to implement the Evaluator pane from the Moose Finder (see Section 5.2) we can write an action that takes the selected text, evaluates it and populates the #selection
port with the result:
finder show: [ :a |
a text
"..."
act: [ :text :entity |
text selection:
(Compiler evaluate: text selectedText for: entity logged: false) ]
on: $o
entitled: 'Open script (o)' ].
The same action can also be written more succinctly:
finder show: [ :a |
a text
"..."
populate: #selection
on: $o
entitled: 'Open script (o)'
with: [ :text :entity |
Compiler evaluate: text selectedText for: entity logged: false ] ].
Given the access to the presentation object we have access to the entire browser, and thus we can also directly modify it. However, affecting directly the overall browser bypasses the mechanism of Glamour, breaks encapsulation and it makes the understanding and maintenance more difficult. Instead, it is preferred that each presentation affects only its own pane and let the propagation happen through explicit transmissions.
There are several kinds of actions supported by Glamour. First, there are actions that are supposed to work for the entire presentation, and actions that are meant to work only contextually when there is a selection. These are specified using the following messages:
- the
act:*
messages define actions for the entire presentation. These actions are typically rendered in the toolbar from the top-right of the presentation. - the
selectionAct:*
messages define actions that should be active only when there is a selection. These actions are typically mapped on the contextual menu.
The above messages define static actions. That means that regardless of what the values of the ports are, these actions will always be available. However, at times, we can also decide to provide actions dynamically depending on the port values. This can be achieved through dynamicActions:
and dynamicActionsOnSelection:
messages. These messages receive a block that will be evaluated on the presentation and should return a list of GLMAction objects.
These messages are meant to be used as a last resort because they work with the internals of Glamour.