Template 2: Applet Manual For GNOME 2.x
Prev | A. Document Templates |

## Template 2: Applet Manual For GNOME 2.x

The following templates should be used for all applet manuals in GNOME 2.x releases. You can always get the latest copy of these templates from GDP Documentation Templates.

Note that this template consists of two files. The first file is an introductory chapter. You should not modify this chapter. The second file is the actual applet document, which you should modify to describe the applet you are documenting. You can name the first file whatever you like, such as `gnome-applets.sgml`. Name the second file according to the applet's name: ``appletname`-applet.sgml`. Make sure you update the entity at the top of the shell document to reflect the new name of the applet document.

    <!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
    <!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">

    ]>

    <book id="gnome-applets">

     <bookinfo>
      <title>GNOME Applets</title>
      <authorgroup>
       <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
       <author><firstname>John</firstname><surname>Fleck</surname></author>
       <author><firstname>David</firstname><surname>Mason</surname>
          <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
        </author>
        <author><firstname>Dan</firstname><surname>Mueth</surname></author>
        <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
      </authorgroup>
      <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
      <pubdate>2000</pubdate>
      <copyright>
       <year>2000</year>
       <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
        Alexander Kirillov</holder>
      </copyright>
      <legalnotice>
       <para>
        Permission is granted to make and distribute verbatim copies of this
        manual provided the copyright notice and this permission notice are
        preserved on all copies.
       </para>
       <para>
        Permission is granted to copy and distribute modified versions of
        this manual under the conditions for verbatim copying, provided that
        the entire resulting derived work is distributed under the terms of a
        permission notice identical to this one.
       </para>
       <para>
        Permission is granted to copy and distribute translations of this
        manual into another language, under the above conditions for modified
        versions, except that this permission notice may be stated in a
        translation approved by the Free Software Foundation.
       </para>
       <para>
        Many of the names used by companies to distinguish their products and
        services are claimed as trademarks. Where those names appear in any
        GNOME documentation, and those trademarks are made aware to the members
        of the GNOME Documentation Project, the names have been printed in caps
        or initial caps.
       </para>
      </legalnotice>
     </bookinfo>

     <!-- #### Introduction ###### -->
     <chapter id="applets-intro">
      <title>Introduction</title>

      <!-- #### Intro | What Are Applets? ###### -->
      <sect1 id="applets-what-are">
       <title>What Are Applets?</title>
       <para>
        Applets are one of the most popular and useful objects you can add
        to your <interface>Panel</interface> to customize your desktop.
        An applet is a small application which runs inside a small area of
        your <interface>Panel</interface>. Applets have been written for
        a wide range of purposes.  Some are very powerful interactive
        tools, such as the <application>Tasklist</application> Applet
        which allows you to easily
        control all of your main applications.  Others are simple system
        monitors, displaying information such as the amount of power left
        in the battery on your laptop (see <application>Battery Charge
        Monitor</application>) or weather
        information(see <application>GNOME Weather</application>).  Some
        are simply for amusement(see <application>Fish</application>).
       </para>

       <para>
        Applets are similar to swallowed applications in that both of them
        reside within the <interface>Panel</interface>. However,
        swallowed applications are generally applications which were
        not designed to run within the <interface>Panel</interface>.
        Typically one will swallow an application which already exists in
        the main <interface>desktop</interface> area, putting it into your
        <interface>Panel</interface>.  The application will continue to
        run in the <interface>Panel</interface> until you end the
        application or  unswallow it,  placing it back onto the main part of
        your desktop when you need to.
       </para>

       <para>
        <figure id="example-applets-fig">
         <title>Example Applets</title>
         <screenshot>
          <screeninfo>Example Applets</screeninfo>
           <graphic fileref="example_applets" format="png"
           srccredit="muet">
           </graphic>
         </screenshot>
        </figure>
        Several example applets are shown in <xref
        linkend="example-applets-fig">.  From left to right, they are: (1)
        <application>Mixer Applet</application>, which allows you to turn
        on/off sound and control its volume by clicking on the applet.  (2)
        <application>Sound Monitor</application> Applet, which displays
        the current volume of sound being played and allows you to control
        various sound features.  (3) <application>GTCD</application>
        Applet, a CD player which has all its controls
        available in the applet and displays the track and time. (4)
        <application>Drive Mount</application> Applet, used to mount and
        unmount drives with a single click of the mouse. (5)
        <application>Desk Guide</application> which allows you to view
        and control multiple virtual screens. (6)
        <application>Tasklist</application> Applet which allows you to
        control your various windows and applications.
       </para>
       <para>
        There are many other applets to choose from.  The rest of this
        chapter will explain the basic information to get you started
        adding, moving, and removing applets from your
        <interface>Panels</interface> and using them. The following
        chapters go through each of the standard GNOME applets describing
        them in detail.  There are also additional applets which can be
        downloaded off the Web.   See <ulink type="http"
         url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
        Software Map</ulink> for lists of additional GNOME applications
        and applets.
       </para>
       <para>
        As you read through the the rest of this chapter, you should try
        adding and removing applets from your <interface>Panel</interface> and
        experiment with them freely.
       </para>
      </sect1>

      <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
      <sect1 id="applet-add-move-replace">
       <title>Adding, Moving, and Removing Applets</title>

       <sect2 id="adding-applets">
        <title>Adding Applets to a Panel</title>
        <para>
         To add an applet to a <interface>Panel</interface>, right-click
         on the <interface>Panel</interface> and select
         <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
         <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
         the menu of all the applets on your system, divided into
         categories. Choosing any applet from this menu will add it to the
         <interface>Panel</interface>.
        </para>
       </sect2>

       <sect2 id="moving-applets">
        <title>Moving Applets In or Between Panels</title>
        <para>
         It is easy to move applets in a <interface>Panel</interface> or
         between two <interface>Panels</interface>. If you have a
         three-button mouse, just move the mouse over the applet, depress
         the middle mouse button and drag the applet to its new location,
         releasing the middle mouse button when you are finished.  Note
         that you can drag applets within a <interface>Panel</interface>
         or between two <interface>Panels</interface> this way. If you
         don't have a three-button mouse, just
         right-click on the applet and choose
         <guimenuitem>Move</guimenuitem>. The cursor will turn into a
         cross and the applet will move with your mouse until you press
         any mouse button to indicate you are finished moving it.
         If, in the course of this movement, it hits
         other objects, the behavior depends on the global preferences
         you have set for your <interface>Panels</interface> in the
         <application>GNOME Control Center</application>: the applet you are
         moving can switch places with other objects, "push" all objects
         it meets, or "jump" over all other objects without disturbing
         them. You can also override the default behavior by holding
         <keycap>Shift</keycap> button (for "push" mode),
         <keycap>Ctrl</keycap> (for "switched" mode), or
         <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
         objects without disturbing them) button while dragging.
        </para>
        <para>
         To change the global Panel preferences, right-click on any applet
         or <interface>Panel</interface> and select
         <menuchoice>
          <guimenu>Panel</guimenu>
          <guimenuitem>Global Preferences...</guimenuitem>
         </menuchoice>.
         The <guilabel>Default movement mode</guilabel> is set under the
         <guilabel>Applets</guilabel> tab.
        </para>
       </sect2>

       <sect2 id="removing-applets">
        <title>Removing Applets from a Panel</title>
        <para>
         To remove an applet from a <interface>Panel</interface>,
         right-click on the applet and select <guimenuitem>Remove from
         panel...</guimenuitem>.
        </para>
       </sect2>
      </sect1>

      <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
      <sect1 id="right-click-pop-up-menu">
       <title>The Right-Click Pop-Up Menu</title>
       <para>
        Clicking the right mouse button on any applet brings up
        a <guimenu>pop-up menu</guimenu>. This
        menu always has certain standard menu items in it and
        often has additional items which vary depending on the particular
        applet.
       </para>
       <sect2 id="standard-right-click-items">
        <title>Standard Pop-Up Items</title>
        <para>
         All applets should have the following items in their right-click
         <guimenu>pop-up menu</guimenu>:
         <variablelist>
          <varlistentry>
           <term>Remove from panel</term>
           <listitem>
            <para>
             The <guimenuitem>Remove from panel</guimenuitem> menu item
             removes the applet from the <interface>Panel</interface>.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>Move</term>
           <listitem>
            <para>
             After selecting <guimenuitem>Move</guimenuitem>, your mouse
             pointer will change appearance (typically to a cross with
             arrows in each direction). As you move your mouse, the applet
             will move with it.  When you have finished moving the applet,
             click any mouse button and the applet will anchor in its
             current position.  Note that applets can be moved between two
             <interface>Panels</interface> this way.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>Panel</term>
           <listitem>
            <para>
             The <guisubmenu>Panel</guisubmenu> submenu contains various
             items and submenus for adding and removing
             <interface>Panels</interface> and applets and for changing
             the configuration.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>About</term>
           <listitem>
            <para>
             The <guimenuitem>About...</guimenuitem> menu item brings up a
             dialogue box containing various information about the applet,
             typically including the applet's  name, version, author,
             copyright, license and desciption.
            </para>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>Help</term>
           <listitem>
            <para>
             The <guimenuitem>Help</guimenuitem> menu item brings up the help
             manual for the applet.
            </para>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </sect2>

       <sect2 id="applet-properties-dialog">
        <title>The Applet Properties Dialog</title>
        <para>
         Many applets have customizable properties.  These applets will
         have a <guimenuitem>Properties...</guimenuitem> menu item in their
         right-click <guimenu>pop-up menu</guimenu> which brings up the
         <interface>Properties</interface> dialog where you can alter the
         appearance or behaviour of the applet.
         <figure id="example-props-dialog-fig">
          <title>An Example Applet Properties Dialog</title>
          <screenshot>
           <screeninfo>An Example Applets Properties Dialog</screeninfo>
           <graphic fileref="applet_props_dialog" format="png"
            srccredit="muet">
           </graphic>
          </screenshot>
         </figure>
         All <interface>Properties</interface> dialogs have the following
         buttons at the bottom of the dialog:
         <itemizedlist>
          <listitem>
           <para>
            <guibutton>OK</guibutton> &mdash;
            Pressing <guibutton>OK</guibutton> will activate any changes
            in the properties you have made and close the
            <interface>Properties</interface> dialog.
           </para>
          </listitem>
          <listitem>
           <para>
            <guibutton>Apply</guibutton> &mdash;
            Pressing <guibutton>Apply</guibutton> at any time will
            make your changes active without closing the
            <interface>Properties</interface> dialog.  This is helpful if
            you would like to test the effects of the changes you have
            made but may want to continue changing the properties.
           </para>
          </listitem>
          <listitem>
           <para>
            <guibutton>Close</guibutton> &mdash;
            Pressing <guibutton>Close</guibutton> will close the
            <interface>Properties</interface> dialog.  Only changes in the
            configuration which were previously applied with the
            <guibutton>Apply</guibutton> button will persist.  Other
            changes will not be made active.
           </para>
          </listitem>
          <listitem>
           <para>
            <guibutton>Help</guibutton> &mdash;
            Pressing <guibutton>Help</guibutton> brings up the manual for
            the application, opening it to the page describing the
            <interface>Properties</interface> dialog.
           </para>
          </listitem>
         </itemizedlist>
        </para>
       </sect2>

       <sect2 id="common-right-click-items">
        <title>Other Common Pop-Up Items</title>
        <para>
         Many applets also have one or more of the following items in their
         right-click pop-up menu:
         <variablelist>
          <varlistentry>
           <term>Run...</term>
           <listitem>
            <para>
             The <guimenuitem>Run...</guimenuitem> menu item generally
             invokes a program  which is related to the applet in some way
             but which runs in its own window rather than in the
             panel. For example:
            </para>
            <orderedlist>
             <listitem>
              <para>
               The <application>CPU Load</application> applet, which monitors
               what programs are running, has a <guimenuitem>Run
               gtop...</guimenuitem>  menu item. Selecting this menu item
               starts <application>GTop</application>, which allows you to
               view and control programs which are running.
              </para>
             </listitem>
             <listitem>
              <para>
               The <application>CD Player</application> applet has a
               <guimenuitem>Run gtcd...</guimenuitem> menu item which
               starts the GNOME <application>CD Player</application> when
               selected, which has more capabilities than the applet.
              </para>
             </listitem>
            </orderedlist>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </sect2>
      </sect1>

      <sect1 id="feedback">
       <title>Feedback</title>
       <sect2 id="reporting-bugs">
        <title>Reporting Applet Bugs</title>
        <para>
         GNOME users are encouraged to report bugs to <ulink type="http"
         url="http://bugs.gnome.org">The GNOME Bug Tracking
         System</ulink>.  The easiest way to submit bugs is to use the
         <application>Bug Report Tool</application> program by selecting
         <menuchoice>
          <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
          <guimenuitem>Bug Report Tool</guimenuitem>
         </menuchoice>.
         Be sure to be complete in describing what you did to cause the
         bug to surface and, if possible, describe how the developer can
         reproduce the the scenario.
        </para>
       </sect2>
       <sect2 id="documentation-feedback">
        <title>Providing Feedback</title>
        <para>
         GNOME users are welcome to provide suggestions for how
         applications and documentation can be improved.  Suggestions for
         application changes should be submitted using the
         <application>Bug Report Tool</application> discussed above.
         Suggestions for documentation changes can be emailed directly to
         the documentation author (whose email should be included in the
         "Authors" section of the document) or by sending an email to
         <email>docs@gnome.org</email>.
        </para>
       </sect2>
       <sect2 id="joining-gnome">
        <title>Joining GNOME</title>
        <para>
         GNOME is a community project, created by hundreds of programmers,
         documentation writers, icon design artists, web masters, and
         other people, most of whom work on a volunteer basis.  New GNOME
         contributors are always welcome. To join the GNOME team, visit
         these web sites: developers &mdash; <ulink type="http"
         url="http://developer.gnome.org">The GNOME Development
         Site</ulink>, documentation writers &mdash; <ulink type="http"
         url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
         Project</ulink>, icon design artists &mdash; <ulink type="http"
         url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
         general &mdash; <ulink type="http"
         url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
         or just join the gnome-list email list (see <ulink type="http"
         url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
         Lists</ulink>) to discuss what you are interested in doing.
        </para>
       </sect2>
      </sect1>
     </chapter>

     <!-- ############### Template Applets ##################### -->
     <chapter id="template-applets">
      <title>Template Applets</title>

      &TEMPLATE-APPLET

     </chapter>

    </book>

      <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
      <!-- your applet. Most importantly, all id attributes should start -->
      <!-- with the name of your applet - this is necessary to avoid name -->
      <!-- conflict among different applets -->
      <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
      <!-- Please replace HACKER-NAME with the applet author's name and -->
      <!-- HACKER-EMAIL with the applet author's email -->

      <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
      <!-- Screenshots should be in PNG format and placed in the -->
      <!-- same directory as GNOMEAPPLET-applet.sgml -->

      <!-- Applet docs will be merged into <chapter>'s inside a -->
      <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
      <!-- correct.-->

      <!-- Permission is granted to make and distribute verbatim copies of -->
      <!-- this manual provided the copyright notice and this permission -->
      <!-- notice are  preserved on all copies. -->
      <!-- -->
      <!-- Permission is granted to copy and distribute modified versions of -->
      <!-- this manual under the conditions for verbatim copying, provided -->
      <!-- that the entire resulting derived work is distributed under the -->
      <!-- terms of a permission notice identical to this one. -->
      <!-- -->
      <!-- Permission is granted to copy and distribute translations of this -->
      <!-- manual into another language, under the above conditions for -->
      <!-- modified versions, except that this permission notice may be -->
      <!-- stated in a translation approved by the Foundation. -->

      <!-- ###############   GNOMEAPPLET   ############### -->
      <sect1 id="GNOMEAPPLET">
       <title>GNOMEAPPLET Applet</title>

       <para>
        <application>GNOMEAPPLET</application> applet, shown in <xref
        linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
        add this applet to a <interface>Panel</interface>, see <xref
        linkend="adding-applets">.
       </para>

       <figure id="GNOMEAPPLET-fig">
       <title>GNOMEAPPLET</title>
       <screenshot>
        <screeninfo>GNOMEAPPLET</screeninfo>
        <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
        </graphic>
       </screenshot>
       </figure>

       <sect2 id="GNOMEAPPLET-usage">
        <title>Usage</title>
        <para>
         This applet does nothing. To use it, just
         left-click on it and it will instantly do nothing.
        </para>
       </sect2>

       <sect2 id="GNOMEAPPLET-right-click">
        <title>Right-Click Pop-Up Menu Items</title>
        <para>
         In addition to the standard menu items (see <xref
         linkend="standard-right-click-items">), the right-click pop-up menu has
         the following items:
         <itemizedlist>
          <listitem>
           <para>
            <guimenuitem>Properties...</guimenuitem> &mdash; This menu
            item opens the <interface>Properties</interface> dialog (see
            <xref linkend="GNOMEAPPLET-properties">) which allows you to
            customize the appearance and behavior of this applet.
           </para>
          </listitem>
          <listitem>
           <para>
            <guimenuitem>Run Hello World...</guimenuitem> &mdash; This
            menu item starts the program <application>Hello
            World</application>, used to say "hello" to the world.
           </para>
          </listitem>
         </itemizedlist>
        </para>
       </sect2>

       <sect2 id="GNOMEAPPLET-properties">
        <title>Properties</title>
        <para>
         You can configure <application>GNOMEAPPLET</application> applet by
         right-clicking on the applet and choosing the
         <guimenuitem>Properties...</guimenuitem> menu item. This will open the
         <interface>Properties</interface> dialog, shown in <xref
         linkend="GNOMEAPPLET-properties-fig">.
        </para>
        <figure id="GNOMEAPPLET-properties-fig">
         <title>Properties Dialog</title>
         <screenshot>
          <screeninfo>Properties Dialog</screeninfo>
          <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
          </graphic>
         </screenshot>
        </figure>

        <para>
         To change the color of the applet, click on the
         <guibutton>color</guibutton> button. To change other properties,
         click on other buttons.
        </para>

        <para>
         For more information on the <interface>Properties</interface>
         dialog, including descriptions of the <guibutton>OK</guibutton>,
         <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
         <guibutton>Help</guibutton> buttons, see <xref
         linkend="applet-properties-dialog">.
        </para>
       </sect2>

       <sect2 id="GNOMEAPPLET-bugs">
        <title> Known Bugs and Limitations</title>
        <para>
         There are no known bugs in the
         <application>GNOMEAPPLET</application> applet.
        </para>
       </sect2>

       <sect2 id="GNOMEAPPLET-authors">
        <title>Authors</title>
        <para>
         This applet was writen by HACKER-NAME
         <email>HACKER-EMAIL</email>.  The documentation for this applet
         which you are reading now was written by
         YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
         bug reports and suggestions for improvements, see <xref
         linkend="feedback">.
        </para>
       </sect2>

      </sect1>

Prev | Home |
Template 2: Applet Manual For GNOME 1.x | Up |