/usr/share/doc/gnat-gps/html/Customization-files-and-plugins.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see http://www.gnu.org/licenses/.

A copy of the license is included in the section entitled
"GNU General Public License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNAT Programming Studio: Customization files and plugins</title>

<meta name="description" content="Using the GNAT Programming Studio: Customization files and plugins">
<meta name="keywords" content="Using the GNAT Programming Studio: Customization files and plugins">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-table.html#Index-table" rel="index" title="Index table">
<link href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" rel="up" title="Customizing through XML and Python files">
<link href="Defining-Actions.html#Defining-Actions" rel="next" title="Defining Actions">
<link href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" rel="previous" title="Customizing through XML and Python files">
<style type="text/css">
<!--
   

a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    

-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Customization-files-and-plugins"></a>
<div class="header">
<p>
Next: <a href="Defining-Actions.html#Defining-Actions" accesskey="n" rel="next">Defining Actions</a>, Up: <a href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" accesskey="u" rel="up">Customizing through XML and Python files</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Customization-files-and-plugins-1"></a>
<h4 class="subsection">16.5.1 Customization files and plugins</h4>

<p>You can customize lots of capabilities in GPS using files that are
loaded by GPS at start up.
</p>
<p>For example, you can add items in the menu and tool bars, as well as
defining new key bindings, new languages, new tools, &hellip;;
Using Python as a programming language, you can also add brand new facilities
and integrate your own tools in the GPS platform.
</p>
<p>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 <a href="The-Plug_002dins-Editor.html#The-Plug_002dins-Editor">The Plug-ins Editor</a>).
</p>
<p>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, &hellip;
</p>
<p>In the directory names below, <samp>INSTALL</samp> is the name of the directory in
which you have installed GPS. <samp>HOME</samp> is the user&rsquo;s home directory, either
by default or as overriden by the <code>GPS_HOME</code> environment variable. If none
of these exist, GPS will use the <code>USERPROFILE</code> environment variable.
</p>
<p>In all these directories, only the files with <samp>.xml</samp> or <samp>.py</samp>
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.
</p>
<ul>
<li> Automatically loaded system wide modules

<p>The <samp>INSTALL/share/gps/plug-ins</samp> 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.
</p>
</li><li> Not automatically loaded system wide modules

<p>The <samp>INSTALL/share/gps/library</samp> 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.
</p>
</li><li> <code>GPS_CUSTOM_PATH</code>

<p>This environment variable can be set before launching GPS. It should contain
a list of directories, separated by semicolons (&rsquo;;&rsquo;) on Windows systems and
colons (&rsquo;:&rsquo;) 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.
</p>
<p>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.
</p>
</li><li> Automatically loaded user directory

<p>The directory <samp>HOME/.gps/plug-ins</samp> is searched last. Any script
found in there will be automatically loaded unless overriden in the
Plug-ins Editor.
</p>
<p>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.
</p>
</li></ul>

<p>Any script loaded by GPS can contain customization for various aspects
of GPS, mixing aliases, new languages or menus, &hellip; in a single
file. This is a convenient way to distribute your plug-ins to other
users.
</p>
<a name="Python-files"></a>
<h4 class="subsubsection">16.5.1.1 Python files</h4>

<p>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:
</p>
<ul>
<li> Comment

<p>The first part of the script should be a general comment on the goal and
  usage of the script. This comment should use python&rsquo;s triple-quote
  convention, rather than start-of-line hash (&rsquo;#&rsquo;) signs.
</p>
<p>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.
</p>
<p>The rest of the comment is free-form.
</p>
</li><li> Customization variables

<p>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
</p>
</li><li> Implementation

<p>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.
</p>
<p>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.
</p>
<p>The solution is to connect to the <code>&quot;gps_started&quot;</code> hook, as in
</p>
<div class="smallexample">
<pre class="smallexample">  ^L
  ###########################################################
  ## No user customization below this line
  ###########################################################

  import GPS

  def on_gps_started (hook_name):
     ... launch the script

  GPS.Hook (&quot;gps_started&quot;).add (on_gps_started)
</pre></div>

</li></ul>

<a name="XML-files"></a>
<h4 class="subsubsection">16.5.1.2 XML files</h4>

<p>XML files must be utf8-encoded by default. In addition, you can
specify any specific encoding through the standard <code>&lt;?xml
encoding=&quot;...&quot; ?&gt;</code> declaration, as in the following example:
</p>
<div class="smallexample">
<pre class="smallexample">&lt;?xml version=&quot;1.0&quot; encoding=&quot;iso-8859-1&quot;?&gt;
&lt;!--  general description --&gt;
&lt;submenu&gt;
  &lt;title&gt;encoded text&lt;/title&gt;
&lt;/submenu&gt;
</pre></div>

<p>These files must be valid XML files, i.e. must start with the
<code>&lt;?xml?&gt;</code> tag, and contain a single root XML node, the name of which is
left to your consideration. The general format is therefore
</p>
<div class="smallexample">
<pre class="smallexample">&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;root_node&gt;
   ...
&lt;/root_node&gt;
</pre></div>

<p>It is also recommended that the first line after the <code>&lt;?xml?&gt;</code> tag
contains a general comment describing the purpose and usage of the script.
This comment will be made visible in the Plug-ins editor.
</p>
<p>The list of valid XML nodes that can be specified under &lt;root&gt; is
described in later sections. It includes:
</p>
<dl compact="compact">
<dt><code>&lt;action&gt;</code></dt>
<dd><p>(see <a href="Defining-Actions.html#Defining-Actions">Defining Actions</a>)
</p></dd>
<dt><code>&lt;key&gt;</code></dt>
<dd><p>(see <a href="Binding-actions-to-keys.html#Binding-actions-to-keys">Binding actions to keys</a>)
</p></dd>
<dt><code>&lt;submenu&gt;</code></dt>
<dd><p>(see <a href="Adding-new-menus.html#Adding-new-menus">Adding new menus</a>)
</p></dd>
<dt><code>&lt;pref&gt;</code></dt>
<dd><p>(see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
</p></dd>
<dt><code>&lt;preference&gt;</code></dt>
<dd><p>(see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
</p></dd>
<dt><code>&lt;alias&gt;</code></dt>
<dd><p>(see <a href="Defining-text-aliases.html#Defining-text-aliases">Defining text aliases</a>)
</p></dd>
<dt><code>&lt;language&gt;</code></dt>
<dd><p>(see <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages">Adding support for new languages</a>)
</p></dd>
<dt><code>&lt;button&gt;</code></dt>
<dd><p>(see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
</p></dd>
<dt><code>&lt;entry&gt;</code></dt>
<dd><p>(see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
</p></dd>
<dt><code>&lt;vsearch-pattern&gt;</code></dt>
<dd><p>(see <a href="Defining-new-search-patterns.html#Defining-new-search-patterns">Defining new search patterns</a>)
</p></dd>
<dt><code>&lt;tool&gt;</code></dt>
<dd><p>(see <a href="Adding-support-for-new-tools.html#Adding-support-for-new-tools">Adding support for new tools</a>)
</p></dd>
<dt><code>&lt;filter&gt;</code></dt>
<dd><p>(see <a href="Filtering-actions.html#Filtering-actions">Filtering actions</a>)
</p></dd>
<dt><code>&lt;contextual&gt;</code></dt>
<dd><p>(see <a href="Adding-contextual-menus.html#Adding-contextual-menus">Adding contextual menus</a>)
</p></dd>
<dt><code>&lt;case_exceptions&gt;</code></dt>
<dd><p>(see <a href="Adding-casing-exceptions.html#Adding-casing-exceptions">Adding casing exceptions</a>)
</p></dd>
<dt><code>&lt;documentation_file&gt;</code></dt>
<dd><p>(see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
</p></dd>
<dt><code>&lt;doc_path&gt;</code></dt>
<dd><p>(see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
</p></dd>
<dt><code>&lt;stock&gt;</code></dt>
<dd><p>(see <a href="Adding-stock-icons.html#Adding-stock-icons">Adding stock icons</a>)
</p></dd>
<dt><code>&lt;project_attribute&gt;</code></dt>
<dd><p>(see <a href="Defining-project-attributes.html#Defining-project-attributes">Defining project attributes</a>)
</p></dd>
<dt><code>&lt;remote_machine_descriptor&gt;</code></dt>
<dd><p>(see <a href="Defining-a-remote-server.html#Defining-a-remote-server">Defining a remote server</a>)
</p></dd>
<dt><code>&lt;remote_path_config&gt;</code></dt>
<dd><p>(see <a href="Defining-a-remote-path-translation.html#Defining-a-remote-path-translation">Defining a remote path translation</a>)
</p></dd>
<dt><code>&lt;remote_connection_config&gt;</code></dt>
<dd><p>(see <a href="Defining-a-remote-connection-tool.html#Defining-a-remote-connection-tool">Defining a remote connection tool</a>)
</p></dd>
<dt><code>&lt;rsync_configuration&gt;</code></dt>
<dd><p>(see <a href="Configuring-rsync-usage.html#Configuring-rsync-usage">Configuring rsync usage</a>)
</p></dd>
</dl>

<hr>
<div class="header">
<p>
Next: <a href="Defining-Actions.html#Defining-Actions" accesskey="n" rel="next">Defining Actions</a>, Up: <a href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" accesskey="u" rel="up">Customizing through XML and Python files</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnat-gps-doc 5.0-16 / usr / share / doc / gnat-gps / html / Customization-files-and-plugins.html
