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.

• Automatically loaded system wide modules

  The INSTALL/share/gps/plug-ins directory should contain the files that GPS will automatically load by default (unless overriden by the user through the Plug-ins Editor). These plug-ins are visible to any user on the system that uses the same GPS installation. This directory should be reserved for critical plug-ins that almost every one should use.

• Not automatically loaded system wide modules

  The INSTALL/share/gps/library directory should contain the files that GPS should show in the Plug-ins Editor, but not load automatically. Typically, these would be files that add optional capabilities to GPS, for instance an emacs emulation mode, or additional editor capabilities that a lot of users would not generally use.

• GPS_CUSTOM_PATH

  This environment variable can be set before launching GPS. It should contain a list of directories, separated by semicolons (';') on Windows systems and colons (':') on Unix systems. All the files in these directories with the appropriate extensions will be automatically loaded by default by GPS, unless overriden by the user through the Plug-ins Editor.

  This is a convenient way to have project-specific customization files. You can for instance create scripts, or icons, that set the appropriate value for the variable and then start GPS. Depending on your project, this allows you to load specific aliases which do not make sense for other projects.

• Automatically loaded user directory

  The directory HOME/.gps/plug-ins is searched last. Any script found in there will be automatically loaded unless overriden in the Plug-ins Editor.

  This is a convenient way for users to create their own plug-ins, or test them before they are made available to the whole system by copying them to one of the other directories.

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:

• Comment

  The first part of the script should be a general comment on the goal and usage of the script. This comment should use python's triple-quote convention, rather than start-of-line hash ('#') signs.

  The first line of the comment should be a one liner explaining the goal of the script. It is separated by a blank line from the rest of the comment.

  The rest of the comment is free-form.

• Customization variables

  If your script can be configured by the user by changing some global variables, they should be listed in their own section, and fully documented. The user can then, through the /Tools/Plug-ins editor change the value of these variables

• Implementation

  The implementation should be separated from the initial comment by a form-feed (control-L) character. The startup scripts editor will know not to display the rest of the script on the first page of the editor.

  Generally speaking, scripts should avoid executing code as soon as they are loaded. This gives a chance to the user to change the value of global variables or even override functions before the script is actually launched.

  The solution is to connect to the "gps_started" hook, as in

              ^L
              ###########################################################
              ## No user customization below this line
              ###########################################################
            
              import GPS
            
              def on_gps_started (hook_name):
                 ... launch the script
            
              GPS.Hook ("gps_started").add (on_gps_started)
  

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)