Recent Changes - Search:

WikiDoc

Categories

The [action] command

This file documents the new [action] command introduced in version 8.1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.


Introduction

The [action] command lets you define and manipulate actions in Alpha. The notion of action is a proposed abstraction introduced to unify the notion of commands triggered by a key binding (keyboard equivalents) and commands invoked by the selection of a menu item.

The [action create] command is used to declare new actions: it returns a token which uniquely determines the newly defined action. This token can then be used in various subcommands of the [action] command or as the value of the -action option in commands such as the [binding] command (see the BindingCommand page on this wiki) or the [menuItem] command (see the MenuRefCommand page): a same action can thus be associated either with a key combination or with a menu item.

The purpose of this new approach is to resolve the conflictual situations caused, in the previous model, by key combinations defined directly by menu definitions or by an explicit call to the [bind] command.

Synopsis

The formal syntax of the [action] command is:

action subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be additionnally specified.

The [create] subcommand

This subcommand creates a new action or redefines an already existing action. It accepts a few options. The complete syntax is:

 
     action create ?-attributes value? ?-help string? ?-script string?

The options have the following signification:

  • the -attributes option lets you specify some attributes of the action. It is currently unused. The default value is 0.

  • the -forceNew option concerns duplicate definitions. By default, if [action create] is invoked with a -script argument corresponding to an already existing action, AlphaX will just return the token of the already existing action in order not to create duplicates. Setting the -forceNew option's value to 1 forces the [action create] command to create a new action. On the contrary, if the -forceNew option is set to 0 and if an already existing action is found, the -attributes and -help options (if any) are ignored. The default value is 0.

  • the -help option lets you specify a human description of the action

  • the -script option lets you specify a piece of Tcl code to execute when the action is invoked. The value of this option can be either the name of a Tcl proc or a Tcl snippet. !! !! If no script is specified, the action::unknown Tcl proc will be invoked.

The [action create] command returns a unique token identifying this action.

Note: the attributes field is currently not used by the core and could be removed in a future version. It could theoretically be used by AlphaTcl to store flags related to the action.

The [delete] subcommand

This subcommand lets you delete an action. The syntax is:

 
     action delete token

After the action is deleted, the token is not valid anymore. Note that a command can be deleted only if there is no more reference to it from menu items. If the action is attached to a menu item, it cannot be deleted: you must first detach it from this menu item. This can be done with an instruction like this

 
     menuItem set $menu $index -action ""

If the action is attached to a key binding, its deletion implies the deletion of this key binding: all the bindings pointing to this action will be deleted.

The [invoke] subcommand

This subcommand lets you execute the script of an action. The syntax is:

 
     action invoke token

If the action is attached to a menu item, it is automatically invoked when the item is selected. Similarly, if the action is attached to a binding, it is automatically invoked when the binding is entered. The [action invoke] command can be useful to simulate one of the preceding circumstances.

The [list] subcommand

This subcommand returns a list of the tokens of all the currently existing actions. The syntax is:

 
     action list

The [set] subcommand

This subcommand lets you get or set several properties attached to an action. The syntax can take two forms:

 
     action set token option
     action set token option value ?option value...?

In the first form, the command returns the current value of the specified option. In the second form, it lets you set the value of one or several options. The available options are exactly the same as with the '''[action create]''' command.

Attaching an action...

An action can be attached to a menu item or to a keyboard shortcut.

to a menu item

To attach an action to a menu item, one must use the [menuItem] command like this:

 
     menuItem set menuToken itemIndex -action actionToken

The action can later be detached passing an empty string like this:

 
     menuItem set menuToken itemIndex -action ""

to a keyboard shortcut

To define a key binding pointing to an action, one must use the [binding create] command and pas the action's token as the last argument, like this:

 
     binding create ?options? commandKey actionToken

The key binding can be undefined later using the [binding delete] command: this has no consequence for the action itself which can continue to exist and be reused.

Examples

Here are a few basic examples which can be executed one by one in the Tcl shell in AlphaX:

 
     # Define an action
     set act1 [action create -script {alertnote "Roll up!"} -help "some help about it"]

     # Get the list of all actions
     action list

     # Get or set the value of the Tcl script
     action set $act1 -script
     action set $act1 -script test::testActionProc

     # Get or set the value of the help string
     action set $act1 -help
     action set $act1 -help "another useful help string"

     # Get or set the value of the attributes (currently unused)
     action set $act1 -attributes
     action set $act1 -attributes 5

     # Invoke the action
     action invoke $act1

     # Delete the action
     action delete $act1


(add your comments here...)

Page last modified on July 16, 2008, at 01:07 PM
Hosted on SourceForge.net Logo