diff options
Diffstat (limited to 'gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml')
| -rw-r--r-- | gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml | 580 |
1 files changed, 580 insertions, 0 deletions
diff --git a/gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml b/gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml new file mode 100644 index 0000000..04967d9 --- /dev/null +++ b/gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml @@ -0,0 +1,580 @@ + <sect2 id="gweather"> + <title>GNOME Weather Applet</title> + + <para> + <application>GNOME Weather</application> applet, shown in <xref + linkend="gweatherapplet-fig">, retrieves and displays various + weather information. To add this applet to a <interface>Panel</interface>, + right-click on the <interface>Panel</interface> and choose + <menuchoice> + <guimenu>Panel</guimenu> + <guisubmenu>Add to panel</guisubmenu> + <guisubmenu>Applet</guisubmenu> + <guisubmenu>Utility</guisubmenu> + <guimenuitem>GNOME Weather</guimenuitem> + </menuchoice>. + </para> + + <figure id="gweatherapplet-fig"> + <title>GNOME Weather Applet</title> + <screenshot> + <screeninfo>GNOME Weather Applet</screeninfo> + <graphic format="png" fileref="figures/gweather_applet" + srccredit="muet"> + </graphic> + </screenshot> + </figure> + + <!-- ============= Usage ================================ --> + <sect3 id="gweather-usage"> + <title>Usage</title> + <para> + <application>GNOME Weather</application> displays the current + temperature and weather conditions in numeric and iconified form + inside the applet. For further information, double-click on the + applet. This will open up the <interface>Weather Information + Window</interface>, shown in <xref + linkend="gweather-weather-fig">. This displays the current weather + information and either a one-day or five-day forecast. + </para> + + <figure id="gweather-weather-fig"> + <title>Weather Information Window</title> + <screenshot> + <screeninfo>Weather Information Window</screeninfo> + <graphic format="png" fileref="figures/gweather_weather" + srccredit="muet"> + </graphic> + </screenshot> + </figure> + + <para> + Right-clicking on the applet brings up a menu containing the + following items: + <itemizedlist> + + <listitem> + <para> + <guimenuitem>Update</guimenuitem> — + refreshes the weather information and display. + </para> + </listitem> + + <listitem> + <para> + <guimenuitem>Properties…</guimenuitem> — + opens the <link linkend="gweather-prefs"> + <guilabel>Properties</guilabel></link> dialog. + </para> + </listitem> + + <listitem> + <para> + <guimenuitem>Help</guimenuitem> — + displays this document. + </para> + </listitem> + + <listitem> + <para> + <guimenuitem>About…</guimenuitem> — + shows basic information about <application>GNOME Weather + Applet</application>, inluding the applet's version and the + author's name. + </para> + </listitem> + + </itemizedlist> + </para> + </sect3> + + + <!-- ============= Customization ============================= --> + <sect3 id="gweather-prefs"> + <title>Customization</title> + <para> + You can customize <application>GNOME Weather</application> + applet by right-clicking on it and choosing + <guimenuitem>Properties…</guimenuitem>. This will open the + <interface>Properties</interface> dialog(shown in <xref + linkend="gweather-settings-fig">), which allows you to + change various settings. + </para> + + <figure id="gweather-settings-fig"> + <title>Properties dialog</title> + <screenshot> + <screeninfo>Properties dialog</screeninfo> + <graphic format="png" fileref="figures/gweather_settings" + srccredit="mueth"> + </graphic> + </screenshot> + </figure> + + <para> + The properties in the <guilabel>Basic</guilabel> tab are: + <itemizedlist> + + <listitem> + <para> + Update Interval — This option determines how often + <application>GNOME Weather</application> will connect + to the server(s) and retrieve weather information. Current + conditions, forecast and radar map (if enabled) will be + downloaded + </para> + <note> + <title>Note About Server Updates</title> + <para> + Note that the <guilabel>Update Interval</guilabel> only + determines how often your computer downloads information from + the server(s). The update time shown in the + <interface>Current Conditions</interface> tab (viewed by + double-clicking on the applet) indicates when those + measurements were renewed on the server, rather than when + they were last retrieved. + </para> + </note> + <note> + <title>Disabling Automatic Updates and Using Manual Updates</title> + <para> + You can disable automatic updates by unchecking the + <guilabel>Update enabled</guilabel> box. On the other hand, you can + also force <application>GNOME Weather</application> to + perform an update by choosing the corresponding option in the + popup menu. These two options are very useful if you have an + intermitant internet connection, such as a laptop or modem + provides. + </para> + </note> + </listitem> + + <listitem> + <para> + Update enabled — Select this if you would like + <application>GNOME Weather</application> to automatically + download the latest weather information at the time interval + specified by <guilabel>Update</guilabel>. Deselect this if + you would only like weather updates to be done manually, by + right-clicking on the applet and selecting + <guimenuitem>Update</guimenuitem>. + </para> + </listitem> + + <listitem> + <para> + Use metric — By default <application>GNOME + Weather</application> uses the imperial system of + units. Select this box to use metric units. The units used are shown in + <xref linkend="tab-units">. + </para> + + <table id="tab-units"> + <title>Measurement Units</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Quantity</entry> + <entry>Metric</entry> + <entry>Imperial</entry> + </row> + </thead> + <tbody> + <row> + <entry>Temperature</entry> + <entry>deg Celsius</entry> + <entry>deg Farenheit</entry> + </row> + <row> + <entry>Windspeed</entry> + <entry>km/h</entry> + <entry>mph</entry> + </row> + <row> + <entry>Pressure</entry> + <entry>mmHg</entry> + <entry>inHg</entry> + </row> + <row> + <entry>Visibility</entry> + <entry>km</entry> + <entry>miles</entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + + <listitem> + <para> + Detailed Forecast — Select this if you would like + <application>GNOME Weather</application> to retrieve the + full five day forecast for your particular area. Note that + these forecasts may not be + available for some locations. + </para> + <para> + The forecast retrieved when this + button is not selected is a brief + forecast for the broader area containing the selected location + (usually the entire state) and typically is a 5-day forecast. + </para> + <note> + <title>Forecast Availability</title> + <para> + Note that the detailed forecasts downloaded from IWIN are + available only for US cities. + </para> + </note> + </listitem> + +<!-- + <listitem> + <para> + Enable radar maps — this allows you to retrieve radar + maps, if these are available. These may be retrieved from the + Web, as long as a valid URL pointing to the image (in + practically any format) is provided. Check the <quote>Enable + radar maps</quote> if you want to enable this option. If a + radar image URL is not provided in the + <filename>Locations</filename> file of the standard + distribution, you can always add one using the location editor + (see <xref linkend="location-editor">). + </para> + </listitem> +--> + + </itemizedlist> + </para> + + <para> + The properties in the <guilabel>Network</guilabel> tab should be + used if your computer is located behind a firewall. These + properties are: + <itemizedlist> + + <listitem> + <para> + Use proxy — Select this button if your computer is + behind a firewall and you must use an HTTP proxy to access the + Web. + </para> + </listitem> + + <listitem> + <para> + Proxy host — Enter your proxy host IP address here (if + you are using a HTTP proxy). + </para> + </listitem> + + <listitem> + <para> + Username — Enter your username here. + </para> + </listitem> + + <listitem> + <para> + Password — Enter your password here. (Note that this + password will be saved in a private configuration file but + will not be encrypted.) + </para> + </listitem> + + </itemizedlist> + </para> + + <para> + The <guilabel>Location</guilabel> tab allows you to specify the + geographic location that you would like <application>GNOME + Weather</application> applet to display the weather information + for. Click on any plus (+) symbol to expand the tree or any minus + (-) symbol to collapse a tree branch. Select the city or region + by clicking with the first mouse button. + </para> + + <para> + Locations are organized in a three-level hierarchy. The top + level contains broader geographical areas, the second contains + sub-regions of these areas and the last contains the particular + locations. This hierarchy is essentially based on the way + information is organized in the US NWS (National Weather + Service), and that is the reason that the US and Canada appear on + the topmost level. + </para> + + <para> After you have made all the changes you want, click on + <guibutton>OK</guibutton> to apply the changes and close the + <interface>Properties</interface> dialog. To cancel the changes + and return to previous values, click the + <guibutton>Cancel</guibutton> button. + </para> + </sect3> + + <!-- ============= Further Information ==================== --> + <!-- This section should describe known bugs and limitations of the + program if there are any - please be frank and list all problems you + know of --> + <sect3 id="gweather-furtherinfo"> + <title>Further Information</title> + <para> + <application>GNOME Weather</application> has a homepage at <ulink + url="http://gweather.dhs.org/">http://gweather.dhs.org/</ulink>. + Here you can find the latest <ulink + url="http://gweather.dhs.org/Locations">Locations</ulink> file, + which is periodically updated with new cities, as sent in by + users. If your city is not included in the distribution, please + send an email to Spiros Papadimitriou + (<email>spapadim+@cs.cmu.edu</email>) with the necessary + information and it will be included in the next release. + </para> + + <para> + You may also want to visit the homepage if you are curious to see + <ulink url="http://gweather.dhs.org/news.html">what's new</ulink>. + </para> + </sect3> + + + <!-- ============= Bugs ================================== --> <!-- + This section should describe known bugs and limitations of the + program if there are any - please be frank and list all problems you + know of --> + <sect3 id="gweather-bugs"> + <title>Known Bugs and Limitations</title> + <sect4 id="blocking-io"> + <title>Blocking Input/Output</title> + <para> + Even though <application>GNOME Weather</application> now uses + non-blocking I/O to retrieve data from the network, there are + still some steps that block execution. Most notably, + establishing a TCP connection to remote hosts is a blocking + operation. Because the NWS and IWIN web servers are often + heavily loaded, this step may take a significant amount of time. + While that happens, the application is unable to respond to CORBA + requests from the <interface>Panel</interface>. In its current + implementation, the <interface>Panel</interface> iterates through + all applications and sends frequent CORBA requests (eg. for + saving state). If an applet cannot respond for any reason, then + the <interface>Panel</interface> will block waiting for a + response. + </para> + + <para> + While the <interface>Panel</interface> is blocked, it will not + respond to any user (or application) requests. For instance, + <interface>Panel</interface> movement and + <interface>Panel</interface> menus (the ones that appear upon a + right click) will not work. However, other applets in the + <interface>Panel</interface> should work (unless they have made a + CORBA request to the <interface>Panel</interface>, eg. for + querying <interface>Panel</interface> size). As soon as the + blocking operation in <application>GNOME Weather</application> + completes, things should return to normal (and user interface + requests that were buffered will be executed). + </para> + + <para> + There is an experimental version of <application>GNOME + Weather</application> that uses a separate thread for HTTP + processing, which may be incorporated (temporarily) in the next + release. However, the final solution is + <application>gnome-vfs</application> which will be part of GNOME + 2.0 and will offer cross-platform support for fully asynchronous + I/O. + </para> + + </sect4> + </sect3> + + + <!-- ============= FAQ ================================== --> + <!-- This section should describe known bugs and limitations of the + program if there are any - please be frank and list all problems you + know of --> + + <sect3 id="gweather-faq"> + <title>Frequently Asked Questions</title> + + <para> + This is a list of frequently asked questions about + <application>GNOME Weather</application>. For further information + and updates, please visit the <ulink + url="http://gweather.dhs.org/">GNOME Weather homepage</ulink>. If + your question is still unresolved, you can email the author at + <email>spapadim+gweather@cs.cmu.edu</email>. + </para> + + <sect4 id="unnamed1"> + <title>Why does GNOME Weather freezes my Panel?</title> + <para> + This is due to the blocking nature of certain network operations + (see also <xref linkend="blocking-io">) and due to the way the + <interface>Panel</interface> currently works. + </para> + </sect4> + + <sect4 id="unnamed2"> + <title>Why does location list appears empty?</title> + + <para> + This is probably because the <filename>Locations</filename> file + was not installed in the proper place. This is usually because + <application>GNOME Weather</application> and GNOME were not + configured in the same way. The file containing the locations + must be installed in the <filename>gweather</filename> + subdirectory, under the gnome data directory. You can find out + the latter with the <userinput>gnome-config --datadir</userinput> + command. + </para> + + <para> + If you have compiled gnome-applets yourself, make sure that you + have used <userinput>configure --prefix=`gnome-config --prefix` + --sysconfdir=`gnome-config --sysconfdir`</userinput>. Binary + RPMs assume a that the prefix and sysconfdir are + <filename>/usr</filename> and <filename>/etc</filename>, + respectively. If you have compiled GNOME yourself with different + options, you need to download and compile gnome-applets yourself. + </para> + </sect4> + + <sect4 id="unnamed3"> + <title>Why does GNOME Weather display a question mark and dashes + for current conditions?</title> + + <para> + This will happen if <application>GNOME Weather</application> + cannot access the NWS server for any reason. This may be + because your network connection is down, or the NWS server is + down, or maybe the NWS server does not currently have any + information about your location. + </para> + </sect4> + + <sect4 id="unnamed4"> + <title>Why does GNOME Weather say that a forecast is not + available?</title> + + <para> + If you have enabled detailed forecasts, then it is possible that + one may not be available for your location. In this case, try + disabling detailed forecasts. + </para> + + <para> + Another possible reason is that the IWIN server is down and + <application>GNOME Weather</application> cannot retrieve forecast + information. The problem should go away as soon as the IWIN + server is up again. + </para> + </sect4> + +<!-- + <sect4> + <title>Why is the radar map not displayed?</title> + + <para> + The most common reason is that the webserver containing the radar + image is down. You may also want to use the location editor (see + <xref linkend="location-editor">) to make sure that the radar + image URL for your location is valid. + </para> + + <para> + Also, if the image is in an uncommon format, <application>GNOME + Weather</application> may not be able to display it. Images are + displayed using the GNOME libraries, which supports practically + all available formats, so this problem should be very + rare. </para> + </sect4> +--> + + </sect3> + + <!-- ============= Authors ================================ --> + + <sect3 id="gweather-authors"> + <title>Authors</title> + <para> + <application>GNOME Weather</application> was written by Spiros + Papadimitriou + (<email>spapadim+@cs.cmu.edu</email>). Please send all comments, + suggestions, and bug + reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME + bug tracking database</ulink>. (Instructions for submitting bug + reports can be found <ulink + url="http://bugs.gnome.org/Reporting.html" type="http"> + on-line</ulink>. If you are using + GNOME 1.1 or later, you can also use <application>Bug Report + Tool</application> (<command>bug-buddy</command>), available in the + <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main + Menu</guimenu>, for submitting bug reports. + </para> + + <para> + This manual was written by Spiros Papadimitriou + (<email>spapadim+@cs.cmu.edu</email>) and Dan Mueth + (<email>d-mueth@uchicago.edu</email>). Please send all comments and + suggestions regarding this manual to the <ulink type="http" + url="http://www.gnome.org/gdp">GNOME Documentation Project</ulink> + by sending an email to <email>docs@gnome.org</email>. You can also + submit comments online by using the <ulink type="http" + url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status + Table</ulink>. + </para> + + <!-- For translations: uncomment this: + + <para> + Latin translation was done by ME + (<email>MYNAME@MYADDRESS</email>). Please send all comments and + suggestions regarding this translation to SOMEWHERE. + </para> + + --> + + </sect3> + + + <!-- ============= Application License ============================= --> + + <!-- + <sect3 id="license"> + <title>License</title> + <para> + This program is free software; you can redistribute it and/or + modify it under the terms of the <citetitle>GNU General Public + License</citetitle> as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any later + version. + </para> + <para> + This program 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 + <citetitle>GNU General Public License</citetitle> for more details. + </para> + <para> + A copy of the <citetitle>GNU General Public License</citetitle> is + included as an appendix to the <citetitle>GNOME Users + Guide</citetitle>. You may also obtain a copy of the + <citetitle>GNU General Public License</citetitle> from the Free + Software Foundation by visiting <ulink type="http" + url="http://www.fsf.org">their Web site</ulink> or by writing to + <address> + Free Software Foundation, Inc. + <street>59 Temple Place</street> - Suite 330 + <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode> + <country>USA</country> + </address> + </para> + </sect3> + + --> + </sect2> + + + + |