path: root/gnome-users-guide/gnome-users-guide-1.4/C/applets/gweather-ug.sgml

 <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> &mdash;
       refreshes the weather information and display.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
       opens the <link linkend="gweather-prefs">
       <guilabel>Properties</guilabel></link> dialog.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>Help</guimenuitem> &mdash;
       displays this document.
      </para>
     </listitem>

     <listitem>
      <para>
       <guimenuitem>About&hellip;</guimenuitem> &mdash;
       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&hellip;</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 &mdash; 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 &mdash; 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 &mdash; 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 &mdash; 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 &mdash; 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 &mdash; 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 &mdash; Enter your proxy host IP address here (if
        you are using a HTTP proxy).
       </para>
      </listitem>

      <listitem>
       <para>
        Username &mdash; Enter your username here.
       </para>
      </listitem>

      <listitem>
       <para>
        Password &mdash; 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>