libgweather r527 - in trunk: . doc doc/tmpl libgweather
- From: danw svn gnome org
- To: svn-commits-list gnome org
- Subject: libgweather r527 - in trunk: . doc doc/tmpl libgweather
- Date: Wed, 26 Nov 2008 04:04:08 +0000 (UTC)
Author: danw
Date: Wed Nov 26 04:04:08 2008
New Revision: 527
URL: http://svn.gnome.org/viewvc/libgweather?rev=527&view=rev
Log:
* libgweather/gweather-location.c:
(gweather_location_get_children)
(gweather_location_free_children): Make the memory-management here
less lame. #562274
* libgweather/gweather-timezone.c:
* libgweather/location-entry.c:
* libgweather/timezone-menu.c: Add some docs. #562261
* doc/Makefile.am (IGNORE_HFILES): set this
* doc/libgweather-sections.txt: update
* doc/libgweather-docs.sgml: fix (some)
Modified:
trunk/ChangeLog
trunk/doc/Makefile.am
trunk/doc/libgweather-docs.sgml
trunk/doc/libgweather-sections.txt
trunk/doc/tmpl/gweather-enum-types.sgml
trunk/doc/tmpl/gweather-gconf.sgml
trunk/doc/tmpl/gweather-location.sgml
trunk/doc/tmpl/gweather-prefs.sgml
trunk/doc/tmpl/gweather-timezone.sgml
trunk/doc/tmpl/gweather-xml.sgml
trunk/doc/tmpl/libgweather-unused.sgml
trunk/doc/tmpl/location-entry.sgml
trunk/doc/tmpl/parser.sgml
trunk/doc/tmpl/timezone-menu.sgml
trunk/doc/tmpl/weather-priv.sgml
trunk/doc/tmpl/weather.sgml
trunk/libgweather/gweather-location.c
trunk/libgweather/gweather-timezone.c
trunk/libgweather/location-entry.c
trunk/libgweather/timezone-menu.c
Modified: trunk/doc/Makefile.am
==============================================================================
--- trunk/doc/Makefile.am (original)
+++ trunk/doc/Makefile.am Wed Nov 26 04:04:08 2008
@@ -48,7 +48,7 @@
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES=
+IGNORE_HFILES=gweather-enum-types.h parser.h weather-priv.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
Modified: trunk/doc/libgweather-docs.sgml
==============================================================================
--- trunk/doc/libgweather-docs.sgml (original)
+++ trunk/doc/libgweather-docs.sgml Wed Nov 26 04:04:08 2008
@@ -1,10 +1,7 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
-[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
-]>
-<book id="index">
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";>
+<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude";>
<bookinfo>
<title>libgweather Reference Manual</title>
<releaseinfo>
@@ -16,16 +13,13 @@
<chapter>
<title>[Insert title here]</title>
- <xi:include href="xml/timezone-menu.xml"/>
+ <xi:include href="xml/gweather-location.xml"/>
<xi:include href="xml/location-entry.xml"/>
- <xi:include href="xml/gweather-enum-types.xml"/>
<xi:include href="xml/gweather-timezone.xml"/>
- <xi:include href="xml/parser.xml"/>
+ <xi:include href="xml/timezone-menu.xml"/>
+ <xi:include href="xml/weather.xml"/>
<xi:include href="xml/gweather-xml.xml"/>
<xi:include href="xml/gweather-gconf.xml"/>
<xi:include href="xml/gweather-prefs.xml"/>
- <xi:include href="xml/weather-priv.xml"/>
- <xi:include href="xml/gweather-location.xml"/>
- <xi:include href="xml/weather.xml"/>
</chapter>
</book>
Modified: trunk/doc/libgweather-sections.txt
==============================================================================
--- trunk/doc/libgweather-sections.txt (original)
+++ trunk/doc/libgweather-sections.txt Wed Nov 26 04:04:08 2008
@@ -34,16 +34,8 @@
</SECTION>
<SECTION>
-<FILE>gweather-enum-types</FILE>
-gweather_location_level_get_type
-GWEATHER_TYPE_LOCATION_LEVEL
-</SECTION>
-
-<SECTION>
<FILE>gweather-timezone</FILE>
GWeatherTimezone
-gweather_timezone_get_type
-GWEATHER_TYPE_TIMEZONE
gweather_timezone_get_name
gweather_timezone_get_tzid
gweather_timezone_get_offset
@@ -51,16 +43,9 @@
gweather_timezone_get_dst_offset
gweather_timezone_ref
gweather_timezone_unref
-</SECTION>
-
-<SECTION>
-<FILE>parser</FILE>
-GWeatherParser
-gweather_parser_new
-gweather_parser_free
-gweather_parser_get_value
-gweather_parser_get_localized_value
-gweather_timezones_parse_xml
+<SUBSECTION Standard>
+gweather_timezone_get_type
+GWEATHER_TYPE_TIMEZONE
</SECTION>
<SECTION>
@@ -105,63 +90,9 @@
</SECTION>
<SECTION>
-<FILE>weather-priv</FILE>
-gweather_gettext
-_
-N_
-WEATHER_LOCATION_CODE_LEN
-gweather_location_to_weather_location
-WeatherConditions
-WeatherTemperature
-WeatherHumidity
-WeatherWindSpeed
-WeatherPressure
-WeatherVisibility
-WeatherUpdate
-WeatherInfo
-weather_wind_direction_string
-weather_sky_string
-weather_conditions_string
-DATA_SIZE
-CONST_DIGITS
-CONST_ALPHABET
-TEMP_F_TO_C
-TEMP_F_TO_K
-TEMP_C_TO_F
-WINDSPEED_KNOTS_TO_KPH
-WINDSPEED_KNOTS_TO_MPH
-WINDSPEED_KNOTS_TO_MS
-WINDSPEED_MS_TO_KNOTS
-WINDSPEED_KNOTS_TO_BFT
-PRESSURE_INCH_TO_KPA
-PRESSURE_INCH_TO_HPA
-PRESSURE_INCH_TO_MM
-PRESSURE_INCH_TO_MB
-PRESSURE_INCH_TO_ATM
-PRESSURE_MBAR_TO_INCH
-VISIBILITY_SM_TO_KM
-VISIBILITY_SM_TO_M
-DEGREES_TO_RADIANS
-RADIANS_TO_DEGREES
-RADIANS_TO_HOURS
-metar_start_open
-iwin_start_open
-metoffice_start_open
-bom_start_open
-wx_start_open
-metar_parse
-requests_init
-request_done
-calc_sun
-free_forecast_list
-</SECTION>
-
-<SECTION>
<FILE>gweather-location</FILE>
GWeatherLocation
GWeatherLocationLevel
-gweather_location_get_type
-GWEATHER_TYPE_LOCATION
gweather_location_new_world
gweather_location_ref
gweather_location_unref
@@ -181,6 +112,9 @@
gweather_location_get_code
gweather_location_get_city_name
gweather_location_get_weather
+<SUBSECTION Standard>
+gweather_location_get_type
+GWEATHER_TYPE_LOCATION
</SECTION>
<SECTION>
Modified: trunk/doc/tmpl/gweather-enum-types.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-enum-types.sgml (original)
+++ trunk/doc/tmpl/gweather-enum-types.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/gweather-gconf.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-gconf.sgml (original)
+++ trunk/doc/tmpl/gweather-gconf.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/gweather-location.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-location.sgml (original)
+++ trunk/doc/tmpl/gweather-location.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
@@ -38,21 +36,6 @@
@GWEATHER_LOCATION_CITY:
@GWEATHER_LOCATION_WEATHER_STATION:
-<!-- ##### FUNCTION gweather_location_get_type ##### -->
-<para>
-
-</para>
-
- Returns:
-
-
-<!-- ##### MACRO GWEATHER_TYPE_LOCATION ##### -->
-<para>
-
-</para>
-
-
-
<!-- ##### FUNCTION gweather_location_new_world ##### -->
<para>
Modified: trunk/doc/tmpl/gweather-prefs.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-prefs.sgml (original)
+++ trunk/doc/tmpl/gweather-prefs.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/gweather-timezone.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-timezone.sgml (original)
+++ trunk/doc/tmpl/gweather-timezone.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
@@ -25,21 +23,6 @@
</para>
-<!-- ##### FUNCTION gweather_timezone_get_type ##### -->
-<para>
-
-</para>
-
- Returns:
-
-
-<!-- ##### MACRO GWEATHER_TYPE_TIMEZONE ##### -->
-<para>
-
-</para>
-
-
-
<!-- ##### FUNCTION gweather_timezone_get_name ##### -->
<para>
Modified: trunk/doc/tmpl/gweather-xml.sgml
==============================================================================
--- trunk/doc/tmpl/gweather-xml.sgml (original)
+++ trunk/doc/tmpl/gweather-xml.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/libgweather-unused.sgml
==============================================================================
--- trunk/doc/tmpl/libgweather-unused.sgml (original)
+++ trunk/doc/tmpl/libgweather-unused.sgml Wed Nov 26 04:04:08 2008
@@ -0,0 +1,493 @@
+<!-- ##### SECTION ./tmpl/gweather-enum-types.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gweather-enum-types.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gweather-enum-types.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gweather-enum-types.sgml:Stability_Level ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gweather-enum-types.sgml:Title ##### -->
+gweather-enum-types
+
+
+<!-- ##### SECTION ./tmpl/parser.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/parser.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/parser.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/parser.sgml:Stability_Level ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/parser.sgml:Title ##### -->
+parser
+
+
+<!-- ##### SECTION ./tmpl/weather-priv.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/weather-priv.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/weather-priv.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/weather-priv.sgml:Stability_Level ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/weather-priv.sgml:Title ##### -->
+weather-priv
+
+
+<!-- ##### MACRO CONST_ALPHABET ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO CONST_DIGITS ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO DATA_SIZE ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO DEGREES_TO_RADIANS ##### -->
+<para>
+
+</para>
+
+ deg:
+
+<!-- ##### MACRO GWEATHER_TYPE_LOCATION ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO GWEATHER_TYPE_LOCATION_LEVEL ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO GWEATHER_TYPE_TIMEZONE ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT GWeatherParser ##### -->
+<para>
+
+</para>
+
+ xml:
+ locales:
+ use_regions:
+ year_start:
+ year_end:
+
+<!-- ##### MACRO N_ ##### -->
+<para>
+
+</para>
+
+ str:
+
+<!-- ##### MACRO PRESSURE_INCH_TO_ATM ##### -->
+<para>
+
+</para>
+
+ inch:
+
+<!-- ##### MACRO PRESSURE_INCH_TO_HPA ##### -->
+<para>
+
+</para>
+
+ inch:
+
+<!-- ##### MACRO PRESSURE_INCH_TO_KPA ##### -->
+<para>
+
+</para>
+
+ inch:
+
+<!-- ##### MACRO PRESSURE_INCH_TO_MB ##### -->
+<para>
+
+</para>
+
+ inch:
+
+<!-- ##### MACRO PRESSURE_INCH_TO_MM ##### -->
+<para>
+
+</para>
+
+ inch:
+
+<!-- ##### MACRO PRESSURE_MBAR_TO_INCH ##### -->
+<para>
+
+</para>
+
+ mbar:
+
+<!-- ##### MACRO RADIANS_TO_DEGREES ##### -->
+<para>
+
+</para>
+
+ rad:
+
+<!-- ##### MACRO RADIANS_TO_HOURS ##### -->
+<para>
+
+</para>
+
+ rad:
+
+<!-- ##### MACRO TEMP_C_TO_F ##### -->
+<para>
+
+</para>
+
+ c:
+
+<!-- ##### MACRO TEMP_F_TO_C ##### -->
+<para>
+
+</para>
+
+ f:
+
+<!-- ##### MACRO TEMP_F_TO_K ##### -->
+<para>
+
+</para>
+
+ f:
+
+<!-- ##### MACRO VISIBILITY_SM_TO_KM ##### -->
+<para>
+
+</para>
+
+ sm:
+
+<!-- ##### MACRO VISIBILITY_SM_TO_M ##### -->
+<para>
+
+</para>
+
+ sm:
+
+<!-- ##### MACRO WEATHER_LOCATION_CODE_LEN ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO WINDSPEED_KNOTS_TO_BFT ##### -->
+<para>
+
+</para>
+
+ knots:
+
+<!-- ##### MACRO WINDSPEED_KNOTS_TO_KPH ##### -->
+<para>
+
+</para>
+
+ knots:
+
+<!-- ##### MACRO WINDSPEED_KNOTS_TO_MPH ##### -->
+<para>
+
+</para>
+
+ knots:
+
+<!-- ##### MACRO WINDSPEED_KNOTS_TO_MS ##### -->
+<para>
+
+</para>
+
+ knots:
+
+<!-- ##### MACRO WINDSPEED_MS_TO_KNOTS ##### -->
+<para>
+
+</para>
+
+ ms:
+
+<!-- ##### STRUCT WeatherConditions ##### -->
+<para>
+
+</para>
+
+ significant:
+ phenomenon:
+ qualifier:
+
+<!-- ##### TYPEDEF WeatherHumidity ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### TYPEDEF WeatherPressure ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### TYPEDEF WeatherTemperature ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### TYPEDEF WeatherUpdate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### TYPEDEF WeatherVisibility ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### TYPEDEF WeatherWindSpeed ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO _ ##### -->
+<para>
+
+</para>
+
+ str:
+
+<!-- ##### FUNCTION bom_start_open ##### -->
+<para>
+
+</para>
+
+ info:
+
+<!-- ##### FUNCTION calc_sun ##### -->
+<para>
+
+</para>
+
+ info:
+ Returns:
+
+<!-- ##### FUNCTION free_forecast_list ##### -->
+<para>
+
+</para>
+
+ info:
+
+<!-- ##### FUNCTION gweather_gettext ##### -->
+<para>
+
+</para>
+
+ str:
+ Returns:
+
+<!-- ##### FUNCTION gweather_location_get_type ##### -->
+<para>
+
+</para>
+
+ Returns:
+
+<!-- ##### FUNCTION gweather_location_level_get_type ##### -->
+<para>
+
+</para>
+
+ Returns:
+
+<!-- ##### FUNCTION gweather_location_to_weather_location ##### -->
+<para>
+
+</para>
+
+ gloc:
+ name:
+ Returns:
+
+<!-- ##### FUNCTION gweather_parser_free ##### -->
+<para>
+
+</para>
+
+ parser:
+
+<!-- ##### FUNCTION gweather_parser_get_localized_value ##### -->
+<para>
+
+</para>
+
+ parser:
+ Returns:
+
+<!-- ##### FUNCTION gweather_parser_get_value ##### -->
+<para>
+
+</para>
+
+ parser:
+ Returns:
+
+<!-- ##### FUNCTION gweather_parser_new ##### -->
+<para>
+
+</para>
+
+ use_regions:
+ Returns:
+
+<!-- ##### FUNCTION gweather_timezone_get_type ##### -->
+<para>
+
+</para>
+
+ Returns:
+
+<!-- ##### FUNCTION gweather_timezones_parse_xml ##### -->
+<para>
+
+</para>
+
+ parser:
+ Returns:
+
+<!-- ##### FUNCTION iwin_start_open ##### -->
+<para>
+
+</para>
+
+ info:
+
+<!-- ##### FUNCTION metar_parse ##### -->
+<para>
+
+</para>
+
+ metar:
+ info:
+ Returns:
+
+<!-- ##### FUNCTION metar_start_open ##### -->
+<para>
+
+</para>
+
+ info:
+
+<!-- ##### FUNCTION metoffice_start_open ##### -->
+<para>
+
+</para>
+
+ info:
+
+<!-- ##### FUNCTION request_done ##### -->
+<para>
+
+</para>
+
+ info:
+ ok:
+
+<!-- ##### FUNCTION requests_init ##### -->
+<para>
+
+</para>
+
+ info:
+ Returns:
+
+<!-- ##### FUNCTION weather_conditions_string ##### -->
+<para>
+
+</para>
+
+ cond:
+ Returns:
+
+<!-- ##### FUNCTION weather_sky_string ##### -->
+<para>
+
+</para>
+
+ sky:
+ Returns:
+
+<!-- ##### FUNCTION weather_wind_direction_string ##### -->
+<para>
+
+</para>
+
+ wind:
+ Returns:
+
+<!-- ##### FUNCTION wx_start_open ##### -->
+<para>
+
+</para>
+
+ info:
+
Modified: trunk/doc/tmpl/location-entry.sgml
==============================================================================
--- trunk/doc/tmpl/location-entry.sgml (original)
+++ trunk/doc/tmpl/location-entry.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/parser.sgml
==============================================================================
--- trunk/doc/tmpl/parser.sgml (original)
+++ trunk/doc/tmpl/parser.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/timezone-menu.sgml
==============================================================================
--- trunk/doc/tmpl/timezone-menu.sgml (original)
+++ trunk/doc/tmpl/timezone-menu.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/weather-priv.sgml
==============================================================================
--- trunk/doc/tmpl/weather-priv.sgml (original)
+++ trunk/doc/tmpl/weather-priv.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
Modified: trunk/doc/tmpl/weather.sgml
==============================================================================
--- trunk/doc/tmpl/weather.sgml (original)
+++ trunk/doc/tmpl/weather.sgml Wed Nov 26 04:04:08 2008
@@ -9,13 +9,11 @@
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
@@ -154,39 +152,6 @@
</para>
- forecast_type:
- temperature_unit:
- speed_unit:
- pressure_unit:
- distance_unit:
- valid:
- network_error:
- sunValid:
- tempMinMaxValid:
- location:
- update:
- sky:
- cond:
- temp:
- temp_min:
- temp_max:
- dew:
- wind:
- windspeed:
- pressure:
- visibility:
- sunrise:
- sunset:
- forecast:
- forecast_list:
- radar_buffer:
- radar_url:
- radar_loader:
- radar:
- session:
- requests_pending:
- finish_cb:
- cb_data:
<!-- ##### USER_FUNCTION WeatherInfoFunc ##### -->
<para>
Modified: trunk/libgweather/gweather-location.c
==============================================================================
--- trunk/libgweather/gweather-location.c (original)
+++ trunk/libgweather/gweather-location.c Wed Nov 26 04:04:08 2008
@@ -34,6 +34,15 @@
#include "parser.h"
#include "weather-priv.h"
+/**
+ * GWeatherLocation:
+ *
+ * A #GWeatherLocation represents a "location" of some type known to
+ * libgweather; anything from a single weather station to the entire
+ * world. See #GWeatherLocationLevel for information about how the
+ * hierarchy of locations works.
+ **/
+
struct _GWeatherLocation {
char *name, *sort_name;
GWeatherLocation *parent, **children;
@@ -47,6 +56,32 @@
int ref_count;
};
+/**
+ * GWeatherLocationLevel:
+ * @GWEATHER_LOCATION_WORLD: A location representing the entire world.
+ * @GWEATHER_LOCATION_REGION: A location representing a continent or
+ * other top-level region.
+ * @GWEATHER_LOCATION_COUNTRY: A location representing a "country" (or
+ * other geographic unit that has an ISO-3166 country code)
+ * @GWEATHER_LOCATION_ADM1: A location representing a "first-level
+ * administrative division"; ie, a state, province, or similar
+ * division.
+ * @GWEATHER_LOCATION_ADM2: A location representing a subdivision of a
+ * %GWEATHER_LOCATION_ADM1 location. (Not currently used.)
+ * @GWEATHER_LOCATION_CITY: A location representing a city
+ * @GWEATHER_LOCATION_WEATHER_STATION: A location representing a
+ * weather station.
+ *
+ * The size/scope of a particular #GWeatherLocation.
+ *
+ * Locations form a hierarchy, with a %GWEATHER_LOCATION_WORLD
+ * location at the top, divided into regions or countries, and so on.
+ * Countries may or may not be divided into "adm1"s, and "adm1"s may
+ * or may not be divided into "adm2"s. A city will have at least one,
+ * and possibly several, weather stations inside it. Weather stations
+ * will never appear outside of cities.
+ **/
+
static int
sort_locations_by_name (gconstpointer a, gconstpointer b)
{
@@ -265,6 +300,25 @@
return NULL;
}
+/**
+ * gweather_location_new_world:
+ * @use_regions: whether or not to divide the world into regions
+ *
+ * Creates a new #GWeatherLocation of type %GWEATHER_LOCATION_WORLD,
+ * representing a hierarchy containing all of the locations from
+ * Locations.xml.
+ *
+ * If @use_regions is %TRUE, the immediate children of the returned
+ * location will be %GWEATHER_LOCATION_REGION nodes, representing the
+ * top-level "regions" of Locations.xml (the continents and a few
+ * other divisions), and the country-level nodes will be the children
+ * of the regions. If @use_regions is %FALSE, the regions will be
+ * skipped, and the children of the returned location will be the
+ * %GWEATHER_LOCATION_COUNTRY nodes.
+ *
+ * Return value: (allow-none): a %GWEATHER_LOCATION_WORLD location, or
+ * %NULL if Locations.xml could not be found or could not be parsed.
+ **/
GWeatherLocation *
gweather_location_new_world (gboolean use_regions)
{
@@ -281,6 +335,14 @@
return world;
}
+/**
+ * gweather_location_ref:
+ * @loc: a #GWeatherLocation
+ *
+ * Adds 1 to @loc's reference count.
+ *
+ * Return value: @loc
+ **/
GWeatherLocation *
gweather_location_ref (GWeatherLocation *loc)
{
@@ -290,6 +352,13 @@
return loc;
}
+/**
+ * gweather_location_unref:
+ * @loc: a #GWeatherLocation
+ *
+ * Subtracts 1 from @loc's reference count, and frees it if the
+ * reference count reaches 0.
+ **/
void
gweather_location_unref (GWeatherLocation *loc)
{
@@ -340,6 +409,19 @@
return type_volatile;
}
+/**
+ * gweather_location_get_name:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets @loc's name, localized into the current language.
+ *
+ * Note that %GWEATHER_LOCATION_WEATHER_STATION nodes are not
+ * localized, and so the name returned for those nodes will always be
+ * in English, and should therefore not be displayed to the user.
+ * (FIXME: should we just not return a name?)
+ *
+ * Return value: @loc's name
+ **/
const char *
gweather_location_get_name (GWeatherLocation *loc)
{
@@ -347,6 +429,17 @@
return loc->name;
}
+/**
+ * gweather_location_get_sort_name:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets @loc's "sort name", which is the name after having
+ * g_utf8_normalize() (with %G_NORMALIZE_ALL) and g_utf8_casefold()
+ * called on it. You can use this to sort locations, or to comparing
+ * user input against a location name.
+ *
+ * Return value: @loc's sort name
+ **/
const char *
gweather_location_get_sort_name (GWeatherLocation *loc)
{
@@ -354,6 +447,15 @@
return loc->sort_name;
}
+/**
+ * gweather_location_get_level:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets @loc's level, from %GWEATHER_LOCATION_WORLD, to
+ * %GWEATHER_LOCATION_WEATHER_STATION.
+ *
+ * Return value: @loc's level
+ **/
GWeatherLocationLevel
gweather_location_get_level (GWeatherLocation *loc)
{
@@ -361,6 +463,15 @@
return loc->level;
}
+/**
+ * gweather_location_get_parent:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets @loc's parent location.
+ *
+ * Return value: (transfer none) (allow-none): @loc's parent, or %NULL
+ * if @loc is a %GWEATHER_LOCATION_WORLD node.
+ **/
GWeatherLocation *
gweather_location_get_parent (GWeatherLocation *loc)
{
@@ -368,29 +479,54 @@
return loc->parent;
}
+/**
+ * gweather_location_get_children:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets an array of @loc's children; this is owned by @loc and will
+ * not remain valid if @loc is freed.
+ *
+ * Return value: (transfer none) (array zero-terminated=1): @loc's
+ * children. (May be empty, but will not be %NULL.)
+ **/
GWeatherLocation **
gweather_location_get_children (GWeatherLocation *loc)
{
+ static GWeatherLocation *no_children = NULL;
+
g_return_val_if_fail (loc != NULL, NULL);
- gweather_location_ref (loc);
if (loc->children)
return loc->children;
else
- return g_new0 (GWeatherLocation *, 1);
+ return &no_children;
}
+
+/**
+ * gweather_location_free_children:
+ * @loc: a #GWeatherLocation
+ * @children: an array of @loc's children
+ *
+ * This is a no-op. Do not use it.
+ *
+ * Deprecated: This is a no-op.
+ **/
void
gweather_location_free_children (GWeatherLocation *loc,
GWeatherLocation **children)
{
- g_return_if_fail (loc != NULL);
-
- if (!loc->children)
- g_free (children);
- gweather_location_unref (loc);
+ ;
}
+/**
+ * gweather_location_has_coords:
+ * @loc: a #GWeatherLocation
+ *
+ * Checks if @loc has valid latitude and longitude.
+ *
+ * Return value: %TRUE if @loc has valid latitude and longitude.
+ **/
gboolean
gweather_location_has_coords (GWeatherLocation *loc)
{
@@ -398,6 +534,15 @@
return loc->latlon_valid;
}
+/**
+ * gweather_location_get_coords:
+ * @loc: a #GWeatherLocation
+ * @latitude: (out): on return will contain @loc's latitude
+ * @longitude: (out): on return will contain @loc's longitude
+ *
+ * Gets @loc's coordinates; you must check
+ * gweather_location_has_coords() before calling this.
+ **/
void
gweather_location_get_coords (GWeatherLocation *loc,
double *latitude, double *longitude)
@@ -411,6 +556,15 @@
*longitude = loc->longitude / M_PI * 180.0;
}
+/**
+ * gweather_location_get_distance:
+ * @loc: a #GWeatherLocation
+ * @loc2: a second #GWeatherLocation
+ *
+ * Determines the distance in kilometers between @loc and @loc2.
+ *
+ * Return value: the distance between @loc and @loc2.
+ **/
double
gweather_location_get_distance (GWeatherLocation *loc, GWeatherLocation *loc2)
{
@@ -427,6 +581,16 @@
sin (loc->latitude) * sin (loc2->latitude)) * radius;
}
+/**
+ * gweather_location_get_country:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets the ISO 3166 country code of @loc (or %NULL if @loc is a
+ * region- or world-level location)
+ *
+ * Return value: (allow-none): @loc's country code (or %NULL if @loc
+ * is a region- or world-level location)
+ **/
const char *
gweather_location_get_country (GWeatherLocation *loc)
{
@@ -437,6 +601,18 @@
return loc->country_code;
}
+/**
+ * gweather_location_get_timezone:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets the timezone associated with @loc, if known.
+ *
+ * The timezone is owned either by @loc or by one of its parents.
+ * FIXME.
+ *
+ * Return value: (transfer none) (allow-none): @loc's timezone, or
+ * %NULL
+ **/
GWeatherTimezone *
gweather_location_get_timezone (GWeatherLocation *loc)
{
@@ -481,6 +657,17 @@
}
}
+/**
+ * gweather_location_get_timezones:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets an array of all timezones associated with any location under
+ * @loc. You can use gweather_location_free_timezones() to free this
+ * array.
+ *
+ * Return value: (transfer full) (array zero-terminated=1): an array
+ * of timezones. May be empty but will not be %NULL.
+ **/
GWeatherTimezone **
gweather_location_get_timezones (GWeatherLocation *loc)
{
@@ -494,6 +681,14 @@
return (GWeatherTimezone **)g_ptr_array_free (zones, FALSE);
}
+/**
+ * gweather_location_free_timezones:
+ * @loc: a #GWeatherLocation
+ * @zones: an array returned from gweather_location_get_timezones()
+ *
+ * Frees the array of timezones returned by
+ * gweather_location_get_timezones().
+ **/
void
gweather_location_free_timezones (GWeatherLocation *loc,
GWeatherTimezone **zones)
@@ -508,6 +703,15 @@
g_free (zones);
}
+/**
+ * gweather_location_get_code:
+ * @loc: a #GWeatherLocation
+ *
+ * Gets the METAR station code associated with a
+ * %GWEATHER_LOCATION_WEATHER_STATION location.
+ *
+ * Return value: (allow-none): @loc's METAR station code, or %NULL
+ **/
const char *
gweather_location_get_code (GWeatherLocation *loc)
{
@@ -515,6 +719,18 @@
return loc->station_code;
}
+/**
+ * gweather_location_get_city_name:
+ * @loc: a #GWeatherLocation
+ *
+ * For a %GWEATHER_LOCATION_CITY location, this is equivalent to
+ * gweather_location_get_name(). For a
+ * %GWEATHER_LOCATION_WEATHER_STATION location, it is equivalent to
+ * calling gweather_location_get_name() on the location's parent. For
+ * other locations it will return %NULL.
+ *
+ * Return value: (allow-none) @loc's city name, or %NULL
+ **/
char *
gweather_location_get_city_name (GWeatherLocation *loc)
{
@@ -573,6 +789,16 @@
return wloc;
}
+/**
+ * gweather_location_get_weather:
+ * @loc: a %GWeatherLocation
+ *
+ * Creates a #WeatherInfo corresponding to @loc; you can use
+ * weather_info_update() to fill it in.
+ *
+ * Return value: (transfer full): a #WeatherInfo corresponding to
+ * @loc.
+ **/
WeatherInfo *
gweather_location_get_weather (GWeatherLocation *loc)
{
Modified: trunk/libgweather/gweather-timezone.c
==============================================================================
--- trunk/libgweather/gweather-timezone.c (original)
+++ trunk/libgweather/gweather-timezone.c Wed Nov 26 04:04:08 2008
@@ -28,6 +28,16 @@
#include "gweather-timezone.h"
#include "parser.h"
+/**
+ * GWeatherTimezone:
+ *
+ * A timezone.
+ *
+ * There are no public methods for creating timezones; they can only
+ * be created by calling gweather_location_new_world() to parse
+ * Locations.xml, and then calling various #GWeatherLocation methods
+ * to extract relevant timezones from the location hierarchy.
+ **/
struct _GWeatherTimezone {
char *id, *name;
int offset, dst_offset;
@@ -235,6 +245,14 @@
return NULL;
}
+/**
+ * gweather_timezone_ref:
+ * @zone: a #GWeatherTimezone
+ *
+ * Adds 1 to @zone's reference count.
+ *
+ * Return value: @zone
+ **/
GWeatherTimezone *
gweather_timezone_ref (GWeatherTimezone *zone)
{
@@ -244,6 +262,12 @@
return zone;
}
+/**
+ * gweather_timezone_unref:
+ * @zone: a #GWeatherTimezone
+ *
+ * Subtracts 1 from @zone's reference count and frees it if it reaches 0.
+ **/
void
gweather_timezone_unref (GWeatherTimezone *zone)
{
@@ -271,6 +295,19 @@
return type_volatile;
}
+/**
+ * gweather_timezone_get_name:
+ * @zone: a #GWeatherTimezone
+ *
+ * Gets @zone's name; a translated, user-presentable string.
+ *
+ * Note that the returned name might not be unique among timezones,
+ * and may not make sense to the user unless it is presented along
+ * with the timezone's country's name (or in some context where the
+ * country is obvious).
+ *
+ * Return value: @zone's name
+ **/
const char *
gweather_timezone_get_name (GWeatherTimezone *zone)
{
@@ -278,6 +315,14 @@
return zone->name;
}
+/**
+ * gweather_timezone_get_tzid:
+ * @zone: a #GWeatherTimezone
+ *
+ * Gets @zone's tzdata identifier, eg "America/New_York".
+ *
+ * Return value: @zone's tzid
+ **/
const char *
gweather_timezone_get_tzid (GWeatherTimezone *zone)
{
@@ -285,6 +330,15 @@
return zone->id;
}
+/**
+ * gweather_timezone_get_offset:
+ * @zone: a #GWeatherTimezone
+ *
+ * Gets @zone's standard offset from UTC, in minutes. Eg, a value of
+ * %120 would indicate "GMT+2".
+ *
+ * Return value: @zone's standard offset, in minutes
+ **/
int
gweather_timezone_get_offset (GWeatherTimezone *zone)
{
@@ -292,6 +346,14 @@
return zone->offset;
}
+/**
+ * gweather_timezone_has_dst:
+ * @zone: a #GWeatherTimezone
+ *
+ * Checks if @zone observes daylight/summer time for part of the year.
+ *
+ * Return value: %TRUE if @zone observes daylight/summer time.
+ **/
gboolean
gweather_timezone_has_dst (GWeatherTimezone *zone)
{
@@ -299,6 +361,16 @@
return zone->has_dst;
}
+/**
+ * gweather_timezone_get_dst_offset:
+ * @zone: a #GWeatherTimezone
+ *
+ * Gets @zone's daylight/summer time offset from UTC, in minutes. Eg,
+ * a value of %120 would indicate "GMT+2". This is only meaningful if
+ * gweather_timezone_has_dst() returns %TRUE.
+ *
+ * Return value: @zone's daylight/summer time offset, in minutes
+ **/
int
gweather_timezone_get_dst_offset (GWeatherTimezone *zone)
{
Modified: trunk/libgweather/location-entry.c
==============================================================================
--- trunk/libgweather/location-entry.c (original)
+++ trunk/libgweather/location-entry.c Wed Nov 26 04:04:08 2008
@@ -27,6 +27,13 @@
#include <string.h>
+/**
+ * GWeatherLocationEntry:
+ *
+ * A subclass of #GtkEntry that provides autocompletion on
+ * #GWeatherLocation<!-- -->s
+ **/
+
G_DEFINE_TYPE (GWeatherLocationEntry, gweather_location_entry, GTK_TYPE_ENTRY)
enum {
@@ -179,6 +186,15 @@
g_object_notify (G_OBJECT (entry), "location");
}
+/**
+ * gweather_location_entry_set_location:
+ * @entry: a #GWeatherLocationEntry
+ * @loc: (allow-none): a #GWeatherLocation in @entry, or %NULL to
+ * clear @entry
+ *
+ * Sets @entry's location to @loc, and updates the text of the
+ * entry accordingly.
+ **/
void
gweather_location_entry_set_location (GWeatherLocationEntry *entry,
GWeatherLocation *loc)
@@ -207,6 +223,17 @@
set_location_internal (entry, model, NULL);
}
+/**
+ * gweather_location_entry_get_location:
+ * @entry: a #GWeatherLocationEntry
+ *
+ * Gets the location that was set by a previous call to
+ * gweather_location_entry_set_location() or was selected by the user.
+ *
+ * Return value: (transfer full) (allow-none): the selected location
+ * (which you must unref when you are done with it), or %NULL if no
+ * location is selected.
+ **/
GWeatherLocation *
gweather_location_entry_get_location (GWeatherLocationEntry *entry)
{
@@ -218,6 +245,16 @@
return NULL;
}
+/**
+ * gweather_location_entry_set_city:
+ * @entry: a #GWeatherLocationEntry
+ * @city_name: (allow-none): the city name, or %NULL
+ * @code: the METAR station code
+ *
+ * Sets @entry's location to a city with the given @code, and given
+ * @city_name, if non-%NULL. If there is no matching city, sets
+ * @entry's location to %NULL.
+ **/
void
gweather_location_entry_set_city (GWeatherLocationEntry *entry,
const char *city_name,
@@ -452,6 +489,18 @@
return TRUE;
}
+/**
+ * gweather_location_entry_new:
+ * @top: the top-level location for the entry.
+ *
+ * Creates a new #GWeatherLocationEntry.
+ *
+ * @top will normally be a location returned from
+ * gweather_location_new_world(), but you can create an entry that
+ * only accepts a smaller set of locations if you want.
+ *
+ * Return value: the new #GWeatherLocationEntry
+ **/
GtkWidget *
gweather_location_entry_new (GWeatherLocation *top)
{
Modified: trunk/libgweather/timezone-menu.c
==============================================================================
--- trunk/libgweather/timezone-menu.c (original)
+++ trunk/libgweather/timezone-menu.c Wed Nov 26 04:04:08 2008
@@ -27,6 +27,12 @@
#include <string.h>
+/**
+ * GWeatherTimezoneMenu:
+ *
+ * A #GtkComboBox subclass for choosing a #GWeatherTimezone
+ **/
+
G_DEFINE_TYPE (GWeatherTimezoneMenu, gweather_timezone_menu, GTK_TYPE_COMBO_BOX)
enum {
@@ -304,6 +310,18 @@
g_object_set (cell, "sensitive", sensitive, NULL);
}
+/**
+ * gweather_timezone_menu_new:
+ * @top: the top-level location for the menu.
+ *
+ * Creates a new #GWeatherTimezoneMenu.
+ *
+ * @top will normally be a location returned from
+ * gweather_location_new_world(), but you can create a menu that
+ * contains the timezones from a smaller set of locations if you want.
+ *
+ * Return value: the new #GWeatherTimezoneMenu
+ **/
GtkWidget *
gweather_timezone_menu_new (GWeatherLocation *top)
{
@@ -337,6 +355,14 @@
return FALSE;
}
+/**
+ * gweather_timezone_menu_set_tzid:
+ * @menu: a #GWeatherTimezoneMenu
+ * @tzid: (allow-none): a tzdata id (eg, "America/New_York")
+ *
+ * Sets @menu to the given @tzid. If @tzid is %NULL, sets @menu to
+ * "Unknown".
+ **/
void
gweather_timezone_menu_set_tzid (GWeatherTimezoneMenu *menu,
const char *tzid)
@@ -356,6 +382,15 @@
check_tzid, &tzd);
}
+/**
+ * gweather_timezone_menu_get_tzid:
+ * @menu: a #GWeatherTimezoneMenu
+ *
+ * Gets @menu's timezone id.
+ *
+ * Return value: (allow-none): @menu's tzid, or %NULL if no timezone
+ * is selected.
+ **/
const char *
gweather_timezone_menu_get_tzid (GWeatherTimezoneMenu *menu)
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
