16.5.6 Adding contextual menus

The actions can also be used to contribute new entries in the contextual menus everywhere in GPS. These menus are displayed when the user presses the right mouse button, and should only show actions relevant to the current context.

Such contributions are done through the <contextual> tag, which takes the following attributes:

"action" (mandatory)

Name of the action to execute, and must be defined elsewhere in one of the customization files.

If this attribute is set to an empty string, a separator will be inserted in the contextual menu instead. If you specify a reference item with one of the "before" or "after" attribute, the separator will be visible only when the reference item is visible.

"before" (optional, default="")

If it is specified, this attribute should be the name of another contextual, before which the new menu should appear. The name of predefined contextual menus can be found by looking at the output of "Contextual.list" in the shell console. The name of the contextual menus you define yourself is the value of the <title> child.

There is no guarantee that the new menu will appear just before the referenced menu. In particular, it won't be the case if the new menu is created before the reference menu was created, or if another later contextual menu indicates that it must be displayed before the same reference item.

"after" (optional, default="")

Same as "before", except it indicates the new menu should appear after the reference item.

If both "after" and "before" are specified, only the latter is taken into account.

It accepts one child tag, <Title> which specifies the name of the menu entry. If this child is not specified, the menu entry will use the name of the action itself. The title is in fact the full path to the new menu entry. Therefore, you can create submenus by using a title of the form "Parent1/Parent2/Menu".

Special characters can be used in the title, and will be automatically expended based on the current context. These are exactly the ones described in the section for macros arguments, See Macro arguments.

The new contextual menu will only be shown if the filters associated with the action match the current context.

For instance, the following example inserts a new contextual menu which prints the name of the current file in the GPS console. This contextual menu is only displayed in source editors. This contextual menu entry is followed by a separator line, visible when the menu is visible

     <?xml version="1.0" ?>
     <print>
       <action name="print current file name" >
         <filter module="Source_Editor" />
         <shell>echo %f</shell>
       </action>
     
       <contextual action="print current file name" >
         <Title>Print Current File Name</Title>
       </contextual>
       <contextual action="" after="Print Current File Name" />
     </print>