/usr/share/doc/gnat-gps/html/Adding-stock-icons.html

<html lang="en">
<head>
<title>Adding stock icons - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" title="Customizing through XML and Python files">
<link rel="prev" href="Adding-documentation.html#Adding-documentation" title="Adding documentation">
<link rel="next" href="Remote-programming-customization.html#Remote-programming-customization" title="Remote programming customization">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
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 3 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/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
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>
<div class="node">
<a name="Adding-stock-icons"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Remote-programming-customization.html#Remote-programming-customization">Remote programming customization</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Adding-documentation.html#Adding-documentation">Adding documentation</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files">Customizing through XML and Python files</a>
<hr>
</div>

<h4 class="subsection">16.5.18 Adding stock icons</h4>

<p><a name="index-stock_005ficons-841"></a><a name="index-g_t_003cstock_005ficons_003e-842"></a><!--  -->

<p class="noindent">XML files can be used to define &ldquo;stock icons&rdquo;. Stock icons are pictures
that are identified by their label, and which are used through GPS in various
places, such as buttons, menus, toolbars, and so on.

   <p>The stock icons must be declared using the tag <code>&lt;icon&gt;</code>, within the global
tag <code>&lt;stock&gt;</code>. The attribute <code>id</code> indicates the label used to identify
the stock icon, and the attribute <code>file</code> points to the file which contains
the actual picture, either in absolute format, or relative to the directory
which contains the XML file.

   <p>If the stock icon is to be used in a toolbar, use the attribute <code>label</code> to
specify the text to display in the toolbar, under the button, when the toolbar
is configured to show text.

   <p>For icons that are intended to be displayed at multiple sizes, you can specify
multiple files corresponding to these multiple sizes. This is done by adding
children to the main icon node, with the tag <code>alternate</code>, containing
a <code>file</code> attribute and a <code>size</code> attribute which correspond to the
size for which this alternate source should be used.

   <p>Possible sizes are:

     <dl>
<dt><code>1</code><dd>Menu item (ideal size: 16x16 pixels)

     <br><dt><code>2</code><dd>Button in a small toolbar (ideal size: 18x18 pixels)

     <br><dt><code>3</code><dd>Button in a large toolbar (ideal size: 24x24 pixels)

     <br><dt><code>4</code><dd>Image for a standard button (ideal size: 20x20 pixels)

     <br><dt><code>5</code><dd>Image used during drag-and-drop operation (ideal size: 32x32 pixels)

     <br><dt><code>6</code><dd>Main image in a dialog (ideal size: 48x48 pixels)

   </dl>

   <p>Here is an example:
<pre class="smallexample">     &lt;?xml version="1.0"?&gt;
     &lt;my_visual_preferences&gt;
       &lt;stock&gt;
         &lt;icon id="myproject-my-picture" file="icons/my-picture.png" /&gt;
     
         &lt;icon id="myproject-multipurpose-image"
                label="do something"
                file="icons/icon_default.png"&gt;
            &lt;alternate file"icons/icon_16.png" size="menu" /&gt;
            &lt;alternate file"icons/icon_24.png" size="large_toolbar" /&gt;
            &lt;alternate file"icons/icon_20.png" size="button" /&gt;
         &lt;/icon&gt;
     
       &lt;/stock&gt;
     &lt;/my_visual_preferences&gt;
</pre>
   <p>Note: as shown in the example above, it is a good practice to prefix the label
by a unique name (e.g. <code>myproject-</code>), in order to make sure that
predefined stock icons will not get overridden by your icons.

<!-- ??? Not available with docgen2, this needs to be implemented. -->
<!--  -->
<!-- @node Defining a documentation format -->
<!-- @subsection Defining a Documentation format -->
<!-- @cindex documentation -->
<!-- @cindex HTML -->
<!-- @cindex templates files -->
<!--  -->
<!-- GPS has support for textual (as opposed to binary format like PDF) -->
<!-- documentation format. A textual documentation format can be described -->
<!-- using external template files. This way, it is possible to add support -->
<!-- for new textual documentation format by providing a set of templates files. -->
<!-- The node name to define a new documentation format is @code{docgen_backend}. -->
<!-- The attributes for this node are: -->
<!-- @table @code -->
<!-- @item name (string) -->
<!-- The name of the documentation format (for example HTML). -->
<!-- @item format (string) -->
<!-- The format is either @b{text} or @b{binary}. Only @b{text} is -->
<!-- supported at the moment. -->
<!-- @end table -->
<!-- There are two categories of children. One is to describe the format -->
<!-- itself, the other is to specify the set of template to use. In the -->
<!-- latter case the children's name are ending with @code{_template}: -->
<!-- @table @code -->
<!-- @item extension -->
<!-- The extension to use for the generated files. This name is also used -->
<!-- as part of the directory name under which the documentation is generated. -->
<!-- @item description -->
<!-- A description about the documentation format. GPS uses this description -->
<!-- in the documentation selection dialog. -->
<!-- @item file_header_template -->
<!-- Point to a template file used as header for each generated files. -->
<!-- @item file_footer_template -->
<!-- Point to a template file used as footer for each generated files. -->
<!-- @item comment_template -->
<!-- Point to a template file used to output comment strings. -->
<!-- @item keyword_template -->
<!-- Point to a template file used to output keywords. -->
<!-- @item string_template -->
<!-- Point to a template file used to output strings. -->
<!-- @item char_template -->
<!-- Point to a template file used to output characters. -->
<!-- @item subtitle_template -->
<!-- Point to a template file used to output a subtitle give its name, size and -->
<!-- indentation level. -->
<!-- @item package_desc_template -->
<!-- Point to a template file used to output package's description. -->
<!-- @item package_template -->
<!-- Point to a template file used to output the package declaration or -->
<!-- ending. -->
<!-- @item with_template -->
<!-- Point to a template file used to output with clauses. -->
<!-- @item variable_template -->
<!-- Point to a template file used to output variables declarations. -->
<!-- @item exception_template -->
<!-- Point to a template file used to output exception declaration. -->
<!-- @item type_template -->
<!-- Point to a template file used to output type declarations. -->
<!-- @item tagged_type_template -->
<!-- Point to a template file used to output tagged types. -->
<!-- @item calls_references_template -->
<!-- Point to a template file used to output subprograms calls. -->
<!-- @item caller_references_template -->
<!-- Point to a template file used to output caller references. -->
<!-- @item entity_template -->
<!-- Point to a template file used to output entity. -->
<!-- @item subprogram_template -->
<!-- Point to a template file used to output subprograms. -->
<!-- @item header_template -->
<!-- Point to a template file used to output the start a package description. -->
<!-- @item footer_template -->
<!-- Point to a template file used to output the end of a package description. -->
<!-- @item private_header_template -->
<!-- Point to a template file used to output the start of package's private section. -->
<!-- @item main_frame_template -->
<!-- Point to a template file used to output the main file (the file -->
<!-- @file{index.html} in the HTML backend for example). -->
<!-- @item unit_index_header_template -->
<!-- Point to a template file used to output the units index header. -->
<!-- @item subprogram_index_header_template -->
<!-- Point to a template file used to output the subprograms index header. -->
<!-- @item type_index_header_template -->
<!-- Point to a template file used to output the types index header. -->
<!-- @item tagged_type_index_header_template -->
<!-- Point to a template file used to output the tagged types index header. -->
<!-- @item item_index_template -->
<!-- Point to a template file used to output an item index. -->
<!-- @item tagged_type_index_template -->
<!-- Point to a template file used to output the tagged types index. -->
<!-- @item private_index_header_template -->
<!-- Point to a template file used to output the private types index header. -->
<!-- @item public_index_header_template -->
<!-- Point to a template file used to output the public types index header. -->
<!-- @item index_footer_template -->
<!-- Point to a template file used to output the end of indexes. -->
<!-- @item block_template -->
<!-- Point to a template file used to output block of text with a reference. -->
<!-- @item link_template -->
<!-- Point to a template file used to output all cross references. -->
<!-- @item description_template -->
<!-- Point to a template file used to output subprograms description based -->
<!-- on comments found just below its spec. -->
<!-- @end table -->
<!-- All template files are given as relative path. GPS will first look for the -->
<!-- template file under @code{share/gps/docgen} and if not found it looks -->
<!-- under @code{$HOME/.gps/docgen}. -->
<!-- A template file is a file that contains tags and commands. Those files -->
<!-- are parsed by the @code{Templates Parser} module as found in -->
<!-- @code{AWS}. We give hereafter a short description of this format, for -->
<!-- a complete description see the Templates Parser User's Guide. -->
<!-- @table @code -->
<!-- @item simple tag -->
<!-- A simple tag is surrounded by @code{@@_} and @code{_@@} like in -->
<!-- @code{@@_NAME_@@}. The templates engine will replace @code{@@_NAME_@@} -->
<!-- with the value associated with the tag named @code{NAME}. -->
<!-- @item vector tag -->
<!-- A vector tag contains a set of values. Each value will be used in -->
<!-- sequence if the tag appears inside a @code{TABLE} command tag. -->
<!-- For example, if the vector tag COLOR contains the three values Red, -->
<!-- Green and Blue then: -->
<!-- @smallexample -->
<!-- @@@@TABLE@@@@ -->
<!-- > @@_COLOR_@@ -->
<!-- @@@@END_TABLE@@@@ -->
<!-- @end smallexample -->
<!-- Will be expanded as: -->
<!-- @smallexample -->
<!-- > Red -->
<!-- > Green -->
<!-- > Blue -->
<!-- @end smallexample -->
<!-- @item filter -->
<!-- Filters can be added to any tag. For example it is possible to output -->
<!-- all values in upper case by applying the @code{UPPER} filter in the previous -->
<!-- example. -->
<!-- @smallexample -->
<!-- @@@@TABLE@@@@ -->
<!-- > @@_UPPER:COLOR_@@ -->
<!-- @@@@END_TABLE@@@@ -->
<!-- @end smallexample -->
<!-- Will be expanded as: -->
<!-- @smallexample -->
<!-- > RED -->
<!-- > GREEN -->
<!-- > BLUE -->
<!-- @end smallexample -->
<!-- It exists many filters, see the Template Parser User's Guide for a -->
<!-- complete description. -->
<!-- @end table -->
<!-- Note that each HTML template files, provided with GPS, contains a -->
<!-- complete description of the usage of each tag in the header comments. -->
<!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / Adding-stock-icons.html
