Next: , Up: Customizing through XML and Python files


16.5.1 Customization files and plugins

You can customize lots of capabilities in GPS using files that are loaded by GPS at start up.

For example, you can add items in the menu and tool bars, as well as defining new key bindings, new languages, new tools, ...; Using Python as a programming language, you can also add brand new facilities and integrate your own tools in the GPS platform.

These customization files are searched for at startup in several different places. Depending on the location where they are found, these files will either be automatically loaded by GPS (and thus can immediately modify things in GPS), or will simply be made visible in the Plug-ins Editor (see The Plug-ins Editor).

These directories are searched for in the order given below. Any script loaded latter can override setups done by previously loaded scripts. For instance, they could override a key shortcut, remove a menu, redefining a GPS action, ...

In the directory names below, INSTALL is the name of the directory in which you have installed GPS. HOME is the user's home directory, either by default or as overriden by the GPS_HOME environment variable. If none of these exist, GPS will use the USERPROFILE environment variable.

In all these directories, only the files with .xml or .py extensions are taken into account. Other files are ignored, although for compatibility with future versions of GPS it is recommended not to keep other files in the same directory.

Any script loaded by GPS can contain customization for various aspects of GPS, mixing aliases, new languages or menus, ... in a single file. This is a convenient way to distribute your plug-ins to other users.

16.5.1.1 Python files

Although the format of the python plug-ins is free (as long as it can be executed by Python), the following organization is suggested. These plug-ins will be visible in the Plug-ins Editor, and therefore having a common format makes it easier for users to understand the goal of the plug-ins:

16.5.1.2 XML files

XML files must be utf8-encoded by default. In addition, you can specify any specific encoding through the standard <?xml encoding="..." ?> declaration, as in the following example:

     <?xml version="1.0" encoding="iso-8859-1"?>
     <!--  general description -->
     <submenu>
       <title>encoded text</title>
     </submenu>

These files must be valid XML files, i.e. must start with the <?xml?> tag, and contain a single root XML node, the name of which is left to your consideration. The general format is therefore

     <?xml version="1.0" ?>
     <root_node>
        ...
     </root_node>

It is also recommended that the first line after the <?xml?> tag contains a general comment describing the purpose and usage of the script. This comment will be made visible in the Plug-ins editor.

The list of valid XML nodes that can be specified under <root> is described in later sections. It includes:

<action>
(see Defining Actions)
<key>
(see Binding actions to keys)
<submenu>
(see Adding new menus)
<pref>
(see Preferences support in custom files)
<preference>
(see Preferences support in custom files)
<alias>
(see Defining text aliases)
<language>
(see Adding support for new languages)
<button>
(see Adding tool bar buttons)
<entry>
(see Adding tool bar buttons)
<vsearch-pattern>
(see Defining new search patterns)
<tool>
(see Adding support for new tools)
<filter>
(see Filtering actions)
<contextual>
(see Adding contextual menus)
<case_exceptions>
(see Adding casing exceptions)
<documentation_file>
(see Adding documentation)
<doc_path>
(see Adding documentation)
<stock>
(see Adding stock icons)
<project_attribute>
(see Defining project attributes)
<remote_machine_descriptor>
(see Defining a remote server)
<remote_path_config>
(see Defining a remote path translation)
<remote_connection_config>
(see Defining a remote connection tool)
<rsync_configuration>
(see Configuring rsync usage)