1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Template 2: Applet Manual For GNOME 2.x</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"><link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation"><link rel="up" href="apa.html" title="A. Document Templates"><link rel="previous" href="apas02.html" title="Template 2: Applet Manual For GNOME 1.x"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Template 2: Applet Manual For GNOME 2.x</th></tr><tr><td width="20%" align="left"><a href="apas02.html">Prev</a>�</td><th width="60%" align="center">A. Document Templates</th><td width="20%" align="right">�</td></tr></table><hr></div><div class="sect1"><a name="template2-2x"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-2x"></a>Template 2: Applet Manual For GNOME 2.x</h2></div></div><p> 2 The following templates should be used for all applet 3 manuals in GNOME 2.x releases. You can always get the latest 4 copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP 5 Documentation Templates</a>. 6 </p><p> 7 Note that this template consists of two files. The first file 8 is an introductory chapter. You should not modify this 9 chapter. The second file is the actual applet document, which 10 you should modify to describe the applet you are documenting. 11 You can name the first file whatever you like, such as 12 <tt>gnome-applets.sgml</tt>. Name the second file 13 according to the applet's name: 14 <tt><i><tt>appletname</tt></i>-applet.sgml</tt>. 15 Make sure you update the entity 16 at the top of the shell document to reflect the new name of 17 the applet document. 18 </p><p> 19 <pre class="programlisting"> 20 21<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[ 22<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part"> 23 24]> 25 26<book id="gnome-applets"> 27 28 <bookinfo> 29 <title>GNOME Applets</title> 30 <authorgroup> 31 <author><firstname>Telsa</firstname><surname>Gwynne</surname></author> 32 <author><firstname>John</firstname><surname>Fleck</surname></author> 33 <author><firstname>David</firstname><surname>Mason</surname> 34 <affiliation><orgname>Red Hat, Inc.</orgname></affiliation> 35 </author> 36 <author><firstname>Dan</firstname><surname>Mueth</surname></author> 37 <author><firstname>Alexander</firstname><surname>Kirillov</surname></author> 38 </authorgroup> 39 <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition> 40 <pubdate>2000</pubdate> 41 <copyright> 42 <year>2000</year> 43 <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and 44 Alexander Kirillov</holder> 45 </copyright> 46 <legalnotice> 47 <para> 48 Permission is granted to make and distribute verbatim copies of this 49 manual provided the copyright notice and this permission notice are 50 preserved on all copies. 51 </para> 52 <para> 53 Permission is granted to copy and distribute modified versions of 54 this manual under the conditions for verbatim copying, provided that 55 the entire resulting derived work is distributed under the terms of a 56 permission notice identical to this one. 57 </para> 58 <para> 59 Permission is granted to copy and distribute translations of this 60 manual into another language, under the above conditions for modified 61 versions, except that this permission notice may be stated in a 62 translation approved by the Free Software Foundation. 63 </para> 64 <para> 65 Many of the names used by companies to distinguish their products and 66 services are claimed as trademarks. Where those names appear in any 67 GNOME documentation, and those trademarks are made aware to the members 68 of the GNOME Documentation Project, the names have been printed in caps 69 or initial caps. 70 </para> 71 </legalnotice> 72 </bookinfo> 73 74 <!-- #### Introduction ###### --> 75 <chapter id="applets-intro"> 76 <title>Introduction</title> 77 78 <!-- #### Intro | What Are Applets? ###### --> 79 <sect1 id="applets-what-are"> 80 <title>What Are Applets?</title> 81 <para> 82 Applets are one of the most popular and useful objects you can add 83 to your <interface>Panel</interface> to customize your desktop. 84 An applet is a small application which runs inside a small area of 85 your <interface>Panel</interface>. Applets have been written for 86 a wide range of purposes. Some are very powerful interactive 87 tools, such as the <application>Tasklist</application> Applet 88 which allows you to easily 89 control all of your main applications. Others are simple system 90 monitors, displaying information such as the amount of power left 91 in the battery on your laptop (see <application>Battery Charge 92 Monitor</application>) or weather 93 information(see <application>GNOME Weather</application>). Some 94 are simply for amusement(see <application>Fish</application>). 95 </para> 96 97 <para> 98 Applets are similar to swallowed applications in that both of them 99 reside within the <interface>Panel</interface>. However, 100 swallowed applications are generally applications which were 101 not designed to run within the <interface>Panel</interface>. 102 Typically one will swallow an application which already exists in 103 the main <interface>desktop</interface> area, putting it into your 104 <interface>Panel</interface>. The application will continue to 105 run in the <interface>Panel</interface> until you end the 106 application or unswallow it, placing it back onto the main part of 107 your desktop when you need to. 108 </para> 109 110 <para> 111 <figure id="example-applets-fig"> 112 <title>Example Applets</title> 113 <screenshot> 114 <screeninfo>Example Applets</screeninfo> 115 <graphic fileref="example_applets" format="png" 116 srccredit="muet"> 117 </graphic> 118 </screenshot> 119 </figure> 120 Several example applets are shown in <xref 121 linkend="example-applets-fig">. From left to right, they are: (1) 122 <application>Mixer Applet</application>, which allows you to turn 123 on/off sound and control its volume by clicking on the applet. (2) 124 <application>Sound Monitor</application> Applet, which displays 125 the current volume of sound being played and allows you to control 126 various sound features. (3) <application>GTCD</application> 127 Applet, a CD player which has all its controls 128 available in the applet and displays the track and time. (4) 129 <application>Drive Mount</application> Applet, used to mount and 130 unmount drives with a single click of the mouse. (5) 131 <application>Desk Guide</application> which allows you to view 132 and control multiple virtual screens. (6) 133 <application>Tasklist</application> Applet which allows you to 134 control your various windows and applications. 135 </para> 136 <para> 137 There are many other applets to choose from. The rest of this 138 chapter will explain the basic information to get you started 139 adding, moving, and removing applets from your 140 <interface>Panels</interface> and using them. The following 141 chapters go through each of the standard GNOME applets describing 142 them in detail. There are also additional applets which can be 143 downloaded off the Web. See <ulink type="http" 144 url="http://www.gnome.org/applist/list-martin.phtml">The GNOME 145 Software Map</ulink> for lists of additional GNOME applications 146 and applets. 147 </para> 148 <para> 149 As you read through the the rest of this chapter, you should try 150 adding and removing applets from your <interface>Panel</interface> and 151 experiment with them freely. 152 </para> 153 </sect1> 154 155 <!-- #### Intro | Adding, Moving, and Removing Applets ###### --> 156 <sect1 id="applet-add-move-replace"> 157 <title>Adding, Moving, and Removing Applets</title> 158 159 <sect2 id="adding-applets"> 160 <title>Adding Applets to a Panel</title> 161 <para> 162 To add an applet to a <interface>Panel</interface>, right-click 163 on the <interface>Panel</interface> and select 164 <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu> 165 <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you 166 the menu of all the applets on your system, divided into 167 categories. Choosing any applet from this menu will add it to the 168 <interface>Panel</interface>. 169 </para> 170 </sect2> 171 172 <sect2 id="moving-applets"> 173 <title>Moving Applets In or Between Panels</title> 174 <para> 175 It is easy to move applets in a <interface>Panel</interface> or 176 between two <interface>Panels</interface>. If you have a 177 three-button mouse, just move the mouse over the applet, depress 178 the middle mouse button and drag the applet to its new location, 179 releasing the middle mouse button when you are finished. Note 180 that you can drag applets within a <interface>Panel</interface> 181 or between two <interface>Panels</interface> this way. If you 182 don't have a three-button mouse, just 183 right-click on the applet and choose 184 <guimenuitem>Move</guimenuitem>. The cursor will turn into a 185 cross and the applet will move with your mouse until you press 186 any mouse button to indicate you are finished moving it. 187 If, in the course of this movement, it hits 188 other objects, the behavior depends on the global preferences 189 you have set for your <interface>Panels</interface> in the 190 <application>GNOME Control Center</application>: the applet you are 191 moving can switch places with other objects, "push" all objects 192 it meets, or "jump" over all other objects without disturbing 193 them. You can also override the default behavior by holding 194 <keycap>Shift</keycap> button (for "push" mode), 195 <keycap>Ctrl</keycap> (for "switched" mode), or 196 <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other 197 objects without disturbing them) button while dragging. 198 </para> 199 <para> 200 To change the global Panel preferences, right-click on any applet 201 or <interface>Panel</interface> and select 202 <menuchoice> 203 <guimenu>Panel</guimenu> 204 <guimenuitem>Global Preferences...</guimenuitem> 205 </menuchoice>. 206 The <guilabel>Default movement mode</guilabel> is set under the 207 <guilabel>Applets</guilabel> tab. 208 </para> 209 </sect2> 210 211 <sect2 id="removing-applets"> 212 <title>Removing Applets from a Panel</title> 213 <para> 214 To remove an applet from a <interface>Panel</interface>, 215 right-click on the applet and select <guimenuitem>Remove from 216 panel...</guimenuitem>. 217 </para> 218 </sect2> 219 </sect1> 220 221 222 <!-- #### Intro | The Right-Click Pop-Up Menu ###### --> 223 <sect1 id="right-click-pop-up-menu"> 224 <title>The Right-Click Pop-Up Menu</title> 225 <para> 226 Clicking the right mouse button on any applet brings up 227 a <guimenu>pop-up menu</guimenu>. This 228 menu always has certain standard menu items in it and 229 often has additional items which vary depending on the particular 230 applet. 231 </para> 232 <sect2 id="standard-right-click-items"> 233 <title>Standard Pop-Up Items</title> 234 <para> 235 All applets should have the following items in their right-click 236 <guimenu>pop-up menu</guimenu>: 237 <variablelist> 238 <varlistentry> 239 <term>Remove from panel</term> 240 <listitem> 241 <para> 242 The <guimenuitem>Remove from panel</guimenuitem> menu item 243 removes the applet from the <interface>Panel</interface>. 244 </para> 245 </listitem> 246 </varlistentry> 247 248 <varlistentry> 249 <term>Move</term> 250 <listitem> 251 <para> 252 After selecting <guimenuitem>Move</guimenuitem>, your mouse 253 pointer will change appearance (typically to a cross with 254 arrows in each direction). As you move your mouse, the applet 255 will move with it. When you have finished moving the applet, 256 click any mouse button and the applet will anchor in its 257 current position. Note that applets can be moved between two 258 <interface>Panels</interface> this way. 259 </para> 260 </listitem> 261 </varlistentry> 262 263 <varlistentry> 264 <term>Panel</term> 265 <listitem> 266 <para> 267 The <guisubmenu>Panel</guisubmenu> submenu contains various 268 items and submenus for adding and removing 269 <interface>Panels</interface> and applets and for changing 270 the configuration. 271 </para> 272 </listitem> 273 </varlistentry> 274 275 <varlistentry> 276 <term>About</term> 277 <listitem> 278 <para> 279 The <guimenuitem>About...</guimenuitem> menu item brings up a 280 dialogue box containing various information about the applet, 281 typically including the applet's name, version, author, 282 copyright, license and desciption. 283 </para> 284 </listitem> 285 </varlistentry> 286 287 <varlistentry> 288 <term>Help</term> 289 <listitem> 290 <para> 291 The <guimenuitem>Help</guimenuitem> menu item brings up the help 292 manual for the applet. 293 </para> 294 </listitem> 295 </varlistentry> 296 </variablelist> 297 </para> 298 </sect2> 299 300 <sect2 id="applet-properties-dialog"> 301 <title>The Applet Properties Dialog</title> 302 <para> 303 Many applets have customizable properties. These applets will 304 have a <guimenuitem>Properties...</guimenuitem> menu item in their 305 right-click <guimenu>pop-up menu</guimenu> which brings up the 306 <interface>Properties</interface> dialog where you can alter the 307 appearance or behaviour of the applet. 308 <figure id="example-props-dialog-fig"> 309 <title>An Example Applet Properties Dialog</title> 310 <screenshot> 311 <screeninfo>An Example Applets Properties Dialog</screeninfo> 312 <graphic fileref="applet_props_dialog" format="png" 313 srccredit="muet"> 314 </graphic> 315 </screenshot> 316 </figure> 317 All <interface>Properties</interface> dialogs have the following 318 buttons at the bottom of the dialog: 319 <itemizedlist> 320 <listitem> 321 <para> 322 <guibutton>OK</guibutton> &mdash; 323 Pressing <guibutton>OK</guibutton> will activate any changes 324 in the properties you have made and close the 325 <interface>Properties</interface> dialog. 326 </para> 327 </listitem> 328 <listitem> 329 <para> 330 <guibutton>Apply</guibutton> &mdash; 331 Pressing <guibutton>Apply</guibutton> at any time will 332 make your changes active without closing the 333 <interface>Properties</interface> dialog. This is helpful if 334 you would like to test the effects of the changes you have 335 made but may want to continue changing the properties. 336 </para> 337 </listitem> 338 <listitem> 339 <para> 340 <guibutton>Close</guibutton> &mdash; 341 Pressing <guibutton>Close</guibutton> will close the 342 <interface>Properties</interface> dialog. Only changes in the 343 configuration which were previously applied with the 344 <guibutton>Apply</guibutton> button will persist. Other 345 changes will not be made active. 346 </para> 347 </listitem> 348 <listitem> 349 <para> 350 <guibutton>Help</guibutton> &mdash; 351 Pressing <guibutton>Help</guibutton> brings up the manual for 352 the application, opening it to the page describing the 353 <interface>Properties</interface> dialog. 354 </para> 355 </listitem> 356 </itemizedlist> 357 </para> 358 </sect2> 359 360 <sect2 id="common-right-click-items"> 361 <title>Other Common Pop-Up Items</title> 362 <para> 363 Many applets also have one or more of the following items in their 364 right-click pop-up menu: 365 <variablelist> 366 <varlistentry> 367 <term>Run...</term> 368 <listitem> 369 <para> 370 The <guimenuitem>Run...</guimenuitem> menu item generally 371 invokes a program which is related to the applet in some way 372 but which runs in its own window rather than in the 373 panel. For example: 374 </para> 375 <orderedlist> 376 <listitem> 377 <para> 378 The <application>CPU Load</application> applet, which monitors 379 what programs are running, has a <guimenuitem>Run 380 gtop...</guimenuitem> menu item. Selecting this menu item 381 starts <application>GTop</application>, which allows you to 382 view and control programs which are running. 383 </para> 384 </listitem> 385 <listitem> 386 <para> 387 The <application>CD Player</application> applet has a 388 <guimenuitem>Run gtcd...</guimenuitem> menu item which 389 starts the GNOME <application>CD Player</application> when 390 selected, which has more capabilities than the applet. 391 </para> 392 </listitem> 393 </orderedlist> 394 </listitem> 395 </varlistentry> 396 </variablelist> 397 </para> 398 </sect2> 399 </sect1> 400 401 <sect1 id="feedback"> 402 <title>Feedback</title> 403 <sect2 id="reporting-bugs"> 404 <title>Reporting Applet Bugs</title> 405 <para> 406 GNOME users are encouraged to report bugs to <ulink type="http" 407 url="http://bugs.gnome.org">The GNOME Bug Tracking 408 System</ulink>. The easiest way to submit bugs is to use the 409 <application>Bug Report Tool</application> program by selecting 410 <menuchoice> 411 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu> 412 <guimenuitem>Bug Report Tool</guimenuitem> 413 </menuchoice>. 414 Be sure to be complete in describing what you did to cause the 415 bug to surface and, if possible, describe how the developer can 416 reproduce the the scenario. 417 </para> 418 </sect2> 419 <sect2 id="documentation-feedback"> 420 <title>Providing Feedback</title> 421 <para> 422 GNOME users are welcome to provide suggestions for how 423 applications and documentation can be improved. Suggestions for 424 application changes should be submitted using the 425 <application>Bug Report Tool</application> discussed above. 426 Suggestions for documentation changes can be emailed directly to 427 the documentation author (whose email should be included in the 428 "Authors" section of the document) or by sending an email to 429 <email>docs@gnome.org</email>. 430 </para> 431 </sect2> 432 <sect2 id="joining-gnome"> 433 <title>Joining GNOME</title> 434 <para> 435 GNOME is a community project, created by hundreds of programmers, 436 documentation writers, icon design artists, web masters, and 437 other people, most of whom work on a volunteer basis. New GNOME 438 contributors are always welcome. To join the GNOME team, visit 439 these web sites: developers &mdash; <ulink type="http" 440 url="http://developer.gnome.org">The GNOME Development 441 Site</ulink>, documentation writers &mdash; <ulink type="http" 442 url="http://developer.gnome.org/projects/gdp">The GNOME Documentation 443 Project</ulink>, icon design artists &mdash; <ulink type="http" 444 url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>, 445 general &mdash; <ulink type="http" 446 url="http://developer.gnome.org/helping/">Helping GNOME</ulink>, 447 or just join the gnome-list email list (see <ulink type="http" 448 url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing 449 Lists</ulink>) to discuss what you are interested in doing. 450 </para> 451 </sect2> 452 </sect1> 453 </chapter> 454 455 <!-- ############### Template Applets ##################### --> 456 <chapter id="template-applets"> 457 <title>Template Applets</title> 458 459 &TEMPLATE-APPLET 460 461 </chapter> 462 463</book> 464 465 466 467 468 469 470 471 472 </pre> 473 474 <pre class="programlisting"> 475 476 477 <!-- Please replace everywhere below GNOMEAPPLET with the name of --> 478 <!-- your applet. Most importantly, all id attributes should start --> 479 <!-- with the name of your applet - this is necessary to avoid name --> 480 <!-- conflict among different applets --> 481 <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email--> 482 <!-- Please replace HACKER-NAME with the applet author's name and --> 483 <!-- HACKER-EMAIL with the applet author's email --> 484 485 <!-- You should name your file: GNOMEAPPLET-applet.sgml --> 486 <!-- Screenshots should be in PNG format and placed in the --> 487 <!-- same directory as GNOMEAPPLET-applet.sgml --> 488 489 <!-- Applet docs will be merged into <chapter>'s inside a --> 490 <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is --> 491 <!-- correct.--> 492 493 <!-- Permission is granted to make and distribute verbatim copies of --> 494 <!-- this manual provided the copyright notice and this permission --> 495 <!-- notice are preserved on all copies. --> 496 <!-- --> 497 <!-- Permission is granted to copy and distribute modified versions of --> 498 <!-- this manual under the conditions for verbatim copying, provided --> 499 <!-- that the entire resulting derived work is distributed under the --> 500 <!-- terms of a permission notice identical to this one. --> 501 <!-- --> 502 <!-- Permission is granted to copy and distribute translations of this --> 503 <!-- manual into another language, under the above conditions for --> 504 <!-- modified versions, except that this permission notice may be --> 505 <!-- stated in a translation approved by the Foundation. --> 506 507 <!-- ############### GNOMEAPPLET ############### --> 508 <sect1 id="GNOMEAPPLET"> 509 <title>GNOMEAPPLET Applet</title> 510 511 <para> 512 <application>GNOMEAPPLET</application> applet, shown in <xref 513 linkend="GNOMEAPPLET-fig">, does this and that. To learn how to 514 add this applet to a <interface>Panel</interface>, see <xref 515 linkend="adding-applets">. 516 </para> 517 518 519 <figure id="GNOMEAPPLET-fig"> 520 <title>GNOMEAPPLET</title> 521 <screenshot> 522 <screeninfo>GNOMEAPPLET</screeninfo> 523 <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME"> 524 </graphic> 525 </screenshot> 526 </figure> 527 528 <sect2 id="GNOMEAPPLET-usage"> 529 <title>Usage</title> 530 <para> 531 This applet does nothing. To use it, just 532 left-click on it and it will instantly do nothing. 533 </para> 534 </sect2> 535 536 <sect2 id="GNOMEAPPLET-right-click"> 537 <title>Right-Click Pop-Up Menu Items</title> 538 <para> 539 In addition to the standard menu items (see <xref 540 linkend="standard-right-click-items">), the right-click pop-up menu has 541 the following items: 542 <itemizedlist> 543 <listitem> 544 <para> 545 <guimenuitem>Properties...</guimenuitem> &mdash; This menu 546 item opens the <interface>Properties</interface> dialog (see 547 <xref linkend="GNOMEAPPLET-properties">) which allows you to 548 customize the appearance and behavior of this applet. 549 </para> 550 </listitem> 551 <listitem> 552 <para> 553 <guimenuitem>Run Hello World...</guimenuitem> &mdash; This 554 menu item starts the program <application>Hello 555 World</application>, used to say "hello" to the world. 556 </para> 557 </listitem> 558 </itemizedlist> 559 </para> 560 </sect2> 561 562 <sect2 id="GNOMEAPPLET-properties"> 563 <title>Properties</title> 564 <para> 565 You can configure <application>GNOMEAPPLET</application> applet by 566 right-clicking on the applet and choosing the 567 <guimenuitem>Properties...</guimenuitem> menu item. This will open the 568 <interface>Properties</interface> dialog, shown in <xref 569 linkend="GNOMEAPPLET-properties-fig">. 570 </para> 571 <figure id="GNOMEAPPLET-properties-fig"> 572 <title>Properties Dialog</title> 573 <screenshot> 574 <screeninfo>Properties Dialog</screeninfo> 575 <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME"> 576 </graphic> 577 </screenshot> 578 </figure> 579 580 <para> 581 To change the color of the applet, click on the 582 <guibutton>color</guibutton> button. To change other properties, 583 click on other buttons. 584 </para> 585 586 <para> 587 For more information on the <interface>Properties</interface> 588 dialog, including descriptions of the <guibutton>OK</guibutton>, 589 <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and 590 <guibutton>Help</guibutton> buttons, see <xref 591 linkend="applet-properties-dialog">. 592 </para> 593 </sect2> 594 595 <sect2 id="GNOMEAPPLET-bugs"> 596 <title> Known Bugs and Limitations</title> 597 <para> 598 There are no known bugs in the 599 <application>GNOMEAPPLET</application> applet. 600 </para> 601 </sect2> 602 603 <sect2 id="GNOMEAPPLET-authors"> 604 <title>Authors</title> 605 <para> 606 This applet was writen by HACKER-NAME 607 <email>HACKER-EMAIL</email>. The documentation for this applet 608 which you are reading now was written by 609 YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting 610 bug reports and suggestions for improvements, see <xref 611 linkend="feedback">. 612 </para> 613 </sect2> 614 615 </sect1> 616 617 618 619 620 621 622 623 624</pre> 625 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a href="apas02.html">Prev</a>�</td><td width="20%" align="center"><a href="index.html">Home</a></td><td width="40%" align="right">�</td></tr><tr><td width="40%" align="left">Template 2: Applet Manual For GNOME 1.x�</td><td width="20%" align="center"><a href="apa.html">Up</a></td><td width="40%" align="right">�</td></tr></table></div></body></html> 626