Next: , Previous: Hooks, Up: gschem API Reference   [Contents][Index]

3.5 Actions

To use the functions described in this section, you will need to load the (gschem action) module.

3.5.1 Action objects

Usually, it is sufficient to use normal Scheme functions when extending gschem. However, when integrating an extension function with the gschem 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 gschem action. Actions can be called just like a normal Scheme function, but get executed via the gschem 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 ``''))

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 gschem 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 gschem’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 gschem 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:

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 to calls are equivalent and interchangeable:

(eval-action! &action)

Since 1.10.

3.5.3 Action positions

Often in gschem 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.

Next: , Previous: Hooks, Up: gschem API Reference   [Contents][Index]