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> —
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> —
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> —
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> —
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 — <ulink type="http"
url="http://developer.gnome.org">The GNOME Development
Site</ulink>, documentation writers — <ulink type="http"
url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
Project</ulink>, icon design artists — <ulink type="http"
url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
general — <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> — 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> — 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>