By default, an action will execute in any context in GPS. The user just selects the menu or key, and GPS tries to execute the action.
It is possible to restrict when an action should be considered as valid. If the current context is incorrect for the action, GPS will not attempt to run anything, and will display an error message for the user.
Actions can be restricted in several ways:
For instance, if you have specified %F
as a parameter to one of the
commands, GPS will check prior to running the action that there is a current
file. This can be either a currently selected file editor, or for instance that
the project view is selected, and a file node inside it is also selected.
You do not have to specify anything else, this filtering is automatic
Note however that the current context might contain more information than you
expect. For instance, if you click on a file name in the Project View, then
the current context contains a file (thus satisfies %F
), but also
contains a project (and thus satisfies %p
and similar macros).
<filter>
, <filter_and>
and <filter_or>
tags, see below.
These tags can be used to further restrict when the command is valid. For instance, you can use them to specify that the command only applies to Ada files, or only if a source editor is currently selected.
Such filters can be defined in one of two places in the customization files:
<action>
, <menu>
or
<button>
tags, you can define named filters. These are general filters,
that can be referenced elsewhere without requiring code duplication.
<action>
tag.
Such filters are anonymous, although they provide exactly the same capabilities
as the ones above. These are mostly meant for simple filters, or filters that
you use only once.
There are three different kinds of tags:
<filter>
<filter_and>
<filter>
, <filter_and>
and <filter_or>
.
<filter_or>
<filter>
,
<filter_and>
and <filter_or>
.
If several such tags are found following one another under an <action>
tag, they are combined through "or", i.e. any of the filters may match for the
action to be executed.
The <filter>
, <filter_and>
and <filter_or>
tags accept the
following set of common attributes:
name (optional)
id
attribute. The name can
take any form.
error (optional)
<filter_and>
and <filter_or>
, only the error message of
the top-level filter will be printed.
In addition, the <filter>
has the following specific attributes:
id (optional)
<?xml version="1.0" ?> <test_filter> <filter name="Test filter" language="ada" /> <action name="Test action" > <filter id="Test filter" /> <shell>pwd</shell> </action> </test_filter>
A number of filters are predefined by GPS itself.
Source editor
Explorer_Project_Node
Explorer_Directory_Node
Explorer_File_Node
Explorer_Entity_Node
File
language (optional)
ada
,
you must have an Ada file selected, or the action won't execute. The language
for a file is found by GPS following several algorithms (file extensions, and
via the naming scheme defined in the project files).
shell_cmd (optional)
Macro arguments (%f, %p, ...) are fully supported in the text of the
command to execute.
shell_lang (optional)
module (optional)
The list of module names can be obtained by typing lsmod
in the shell
console at the bottom of the GPS window.
This attribute is mostly useful when creating new contextual menus.
When several attributes are specified for a <filter>
node (which is not
possible with id
), they must all match for the action to be executed.
<?xml version="1.0" ?> <!-- The following filter will only match if the currently selected window is a text editor editing an Ada source file --> <ada_editor> <filter_and name="Source editor in Ada" > <filter language="ada" /> <filter id="Source editor" /> </filter_and> <!-- The following action will only be executed for such an editor --> <action name="Test Ada action" > <filter id="Source editor in Ada" /> <shell>pwd</shell> </action> <!-- An action with an anonymous filter. It will be executed if the selected file is in Ada, even if the file was selected through the project view --> <action name="Test for Ada files" > <filter language="ada" /> <shell>pwd</shell> </action> </ada_editor>