3.5.1 Action objects

Usually, it is sufficient to use normal Scheme functions when extending lepton-schematic. However, when integrating an extension function with the lepton-schematic GUI (e.g. via keybindings), it is often useful to couple a Scheme function with metadata such as the label and icon to show in menus, etc.

You can do this by creating a lepton-schematic action. Actions can be called just like a normal Scheme function, but get executed via the lepton-schematic action dispatcher eval-action! rather than being invoked directly. Normally, actions have names begining with an ‘&’ symbol.

Macro: define-action (name [keyword value ...]) body ¶

Create a new action, bound to the given name in the current module. The body is a sequence of Scheme expressions which are evaluated in order when the action is invoked. Any number of initial properties can be specified for the action by providing pairs of keywords and values.

(define-action (&report-bug #:label ``Report Bug'' #:icon ``web-browser'')
  (show-uri ``https://github.com/lepton-eda/lepton-eda/issues/new''))

Since 1.10.

Function: make-action thunk [keyword value ...] ¶

Create and return a new action wrapping thunk. Optionally, specify keyword-value pairs to set initial properties for the action.

Since 1.10.

Function: action? obj ¶

Returns ‘#t’ iff obj is a lepton-schematic action, and ‘#f’ otherwise.

Since 1.10.

Action properties are name-value pairs that are attached to an action.

Function: action-property action key ¶

Return the value of one of action’s properties. key is a symbol naming the property to retrieve.

Since 1.10.

Function: set-action-property! action key value ¶

Set the value of one of action’s properties. key is a symbol naming the property to set, and value is the new value.

Since 1.10.

3.5.2 Evaluating actions

All of lepton-schematic’s built-in actions are callable just like normal Scheme functions. However, it’s sometimes useful to explicitly evaluate an action in the same way that the lepton-schematic GUI (menus, toolbars or keybindings) would do so.

Function: eval-action! action ¶

Invoke action, returning ‘#t’ on success and raising an error on failure. There are a number of possible types for action that eval-action! will accept:

• A thunk.
• A lepton-schematic action.
• A symbol naming an action or a thunk in the current module.

The special symbol ‘repeat-last-command’ is interpreted as a request to repeat the last action evaluated via eval-action!.

Note: If you have an action object &action, then the following two calls are equivalent and interchangeable:

(eval-action! &action)
(&action)

Since 1.10.

3.5.3 Action positions

Often in lepton-schematic actions it may be useful not to use the actual current mouse pointer position but to use the mouse pointer position that was current when the action was invoked.

Function: eval-action-at-point! action [point] ¶

Evaluate action at a particular point on the schematic plane. If point is omitted, the action is evaluated at the current mouse pointer position.

Since 1.10.

Function: action-position ¶

Return the current action pointer position, as set when the action was invoked (via eval-action-at-point!). This only makes sense to call from inside an action.

Since 1.10.

Note: The pointer position can only be considered reliable when the user was actually clicking on or pointing at the schematic view area to invoke the action, rather than on a menu or toolbar button. At the moment this means that an action position is only set when a command is invoked by hotkey.