Next: Macro arguments, Previous: Customization files and plugins, Up: Customizing through XML and Python files
This facility distinguishes the actions from their associated menus or key bindings. Actions can take several forms: external commands, shell commands and predefined commands, as will be explained in more details below.
The general form to define new actions is to use the <action>
tag.
This tag accepts the following attributes:
name (mandatory)
output (optional)
<shell>
and <external>
tags,
See Redirecting the command output.
show-command (optional, default true)
show-task-manager (optional, default false)
category (optional, default "General")
Edit/Key bindings
) in which
the action should be shown to the user. If you specify an empty string, the
action is considered as an implementation detail, and not displayed in the
editor. The user will thus not be able to assign it a keybinding through the
graphical user interface (although this is still doable through XML commands).
If you are defining the same action multiple times, the last definition will be kept. However, existing menus, buttons, ... that already reference that action will keep their existing semantic. The new definition will only be used for all new menus created from that point on.
The <action>
can have one or
several children, all of which define a particular command to execute. All
of these commands are executed one after the other, unless one of them
fails in which case the following commands are not executed.
The following XML tags are valid children for <action>
.
<external>
Note for Windows users: like under UNIX, scripts can be called
from custom menu. In order to do that, you need to write your script in a
.bat or .cmd file, and call this file as usual.
The external
tag would e.g. look like:
<?xml version="1.0" ?> <external_example> <action name="my_command"> <external>c:\.gps\my_scripts\my_cmd.cmd</external> </action> </external_example>
This tag accepts the following attributes:
server (optional)
"gps_server"
(default),
"build_server"
, "execution_server"
, "debug_server"
and
"tools_server"
.
See Remote operations, for explanation of what these servers are.
check-password (optional)
"false"
(default)
and "true"
.
show-command (optional)
<action>
tag.
output (optional)
<action>
tag.
progress-regexp (optional)
The name of the action is printed in the progress bar while the action is executing.
<?xml version="1.0" ?> <progress_action> <action name="progress" > <external progress-regexp="(\d+) out of (\d+).*$" progress-current="1" progress-final="2" progress-hide="true">gnatmake foo.adb </external> </action> </progress_action>
progress-current (optional, default is 1)
progress-regexp
that contains the current step.
progress-final (optional, default is 2)
progress-regexp
that contains the current last step. This last index can grow as
needed. For example, gnatmake will output the number of
the file it is currently examining, and the total number of files to be
examined. However, that last number may grow up, since parsing a new file
might generate a list of additional files to parse later on.
progress-hide (optional, default is true)
progress-regexp
and are used to compute the progress will
not be displayed in the output console. For any other value of this
attribute, these lines are displayed along will the rest of the output.
show-task-manager (optional, default inherited from <action>)
If you have set a value for progress-regexp
, this will automatically
be set to true by default so that the progress bar is indeed displayed in
the task manager. You can still override it explicitly for that
<external>
element to force hiding the progress bar.
<on-failure>
For instance, the following action spawn an external tool, and parses its output to the location window and the automatic fixing tool if the external tool happens to fail.
In this group of commands the %... and $... macros can be used (see Macro arguments).
<?xml version="1.0" ?> <action_launch_to_location> <action name="launch tool to location" > <external>tool-path</external> <on-failure> <shell>Locations.parse "%1" category<shell> <external>echo the error message is "%2"</external> </on-failure> <external>echo the tool succeeded with message %1</external> </action> </action_launch_to_location>
<shell>
shell
tag. These are command written in one of the
shell scripts supported by GPS.
This tag supports the same show-command
and output
attributes
as the <action>
tag.
The following example shows how to
create two actions to invoke the help
interactive command and to open
the file main.c.
<?xml version="1.0" ?> <help> <action name="help"> <shell>help</shell> </action> <action name="edit"> <shell>edit main.c</shell> </action> </help>
By default, commands are expected to be written in the GPS shell language.
However, you can specify the language through the lang
attribute. Its
default value is "shell"
.
The value of this attribute could also be "python".
When programming with the GPS shell, you can execute multiple commands by separating them with semicolons. Therefore, the following example adds a menu which lists all the files used by the current file, in a project browser.
<?xml version="1.0" ?> <current_file_uses> <action name="current file uses"> <shell lang="shell">File %f</shell> <shell lang="shell">File.uses %1</shell> </action> </current_file_uses>
<description>
<filter>, <filter_and>, <filter_or>
It is possible to mix both shell commands and external commands. For instance, the following command opens an xterm (on Unix systems only) in the current directory, which depends on the context.
<?xml version="1.0" ?> <xterm_directory> <action "xterm in current directory"> <shell lang="shell">cd %d</shell> <external>xterm</external> </action> </xterm_directory>
As seen in some of the examples above, some special strings are expanded by GPS just prior to executing the command. These are the "%f", "%d",.. See below for a full list.
More information on chaining commands is provided in See Chaining commands.
Some actions are also predefined in GPS itself. This include for instance
aliases expansion, manipulating MDI windows, ...;
All known actions (predefined
and the ones you have defined in your own customization files) can be
discovered by opening the key shortcut editor (Edit->Key shortcuts
menu).