On Wed, 2010-09-15 at 22:13 +0200, Jean Bréfort wrote: > You might add that libgoffice_init and libgoffice_shutdown can be called > several times. Any code calling libgoffice_init should call > libgoffice_shutdown when done. init increments a counter and shutdown > decremen,ts it. When the counter reaches 0, the created structures are > released/freed/whatever is appropriate to get rid of them. > > I was wrong earlier today, documentation should go to .c files, not .h. > Sorry. > Attached is a patch that adresses this. I also squashed in the GogText change, and added brief info about GOGraphWidget.
My email client might add a leading > to the first line of the patch. Remove and it will apply with git am. Sorry for the inconvinience. -- Regards Jon Nordby - www.jonnor.com Openismus GmbH - www.openismus.com
>From eac1a539cec0d54cb97ee6f623fc9e8a3dde2d4b Mon Sep 17 00:00:00 2001 From: Jon Nordby <[email protected]> Date: Wed, 15 Sep 2010 16:43:41 +0200 Subject: [PATCH] Docs: Introduction to GOffice and graphs Adds documentation about GOffice in general, and descriptions to the most relevant objects in the graph API. Move GogText from objects to abstract base classes. --- docs/reference/goffice-docs.sgml | 9 +++--- goffice/goffice.c | 55 ++++++++++++++++++++++++++++++++++++++ goffice/graph/gog-axis.c | 10 +++++++ goffice/graph/gog-chart.c | 9 ++++++ goffice/graph/gog-graph.c | 14 +++++++++ goffice/graph/gog-label.c | 8 +++++ goffice/graph/gog-legend.c | 8 +++++ goffice/graph/gog-object.c | 17 +++++++++++ goffice/graph/gog-plot.c | 15 ++++++++++ goffice/graph/gog-renderer.c | 8 +++++ goffice/graph/gog-series.c | 7 +++++ goffice/gtk/go-graph-widget.c | 7 +++++ 12 files changed, 163 insertions(+), 4 deletions(-) diff --git a/docs/reference/goffice-docs.sgml b/docs/reference/goffice-docs.sgml index e3384fe..632ee0d 100644 --- a/docs/reference/goffice-docs.sgml +++ b/docs/reference/goffice-docs.sgml @@ -9,7 +9,9 @@ <title>Goffice Reference Manual</title> <releaseinfo>For goffice &version;</releaseinfo> </bookinfo> - + <chapter> + <xi:include href="xml/goffice.xml"/> + </chapter> <part> <title>Graphs</title> <chapter> @@ -25,7 +27,6 @@ <xi:include href="xml/gog-label.xml"/> <xi:include href="xml/gog-reg-eqn.xml"/> <xi:include href="xml/gog-series-lines.xml"/> - <xi:include href="xml/gog-text.xml"/> </chapter> <chapter> <title>Abstract Base Classes</title> @@ -40,6 +41,7 @@ <xi:include href="xml/gog-view.xml"/> <xi:include href="xml/gog-data-allocator.xml"/> <xi:include href="xml/gog-data-set.xml"/> + <xi:include href="xml/gog-text.xml"/> </chapter> <chapter> <title>Utilities</title> @@ -84,6 +86,7 @@ </part> <part> <title>Widgets</title> + <xi:include href="xml/go-graph-widget.xml"/> <chapter> <title>Base widgets</title> <xi:include href="xml/go-combo-box.xml"/> @@ -195,7 +198,6 @@ <xi:include href="xml/go-dock-item.xml"/> <xi:include href="xml/go-dock-item-grip.xml"/> </chapter> -<xi:include href="xml/goffice.xml"/> <xi:include href="xml/goffice-priv.xml"/> <xi:include href="xml/error-info.xml"/> <xi:include href="xml/file-priv.xml"/> @@ -209,7 +211,6 @@ <xi:include href="xml/go-action-combo-stack.xml"/> <xi:include href="xml/go-action-combo-text.xml"/> <xi:include href="xml/go-color-palette.xml"/> -<xi:include href="xml/go-graph-widget.xml"/> <xi:include href="xml/go-marshal.xml"/> <xi:include href="xml/goffice-gtk.xml"/> <xi:include href="xml/go-ms-parser.xml"/> diff --git a/goffice/goffice.c b/goffice/goffice.c index 01addbd..67bfecb 100644 --- a/goffice/goffice.c +++ b/goffice/goffice.c @@ -68,6 +68,45 @@ static char const *libgoffice_icon_dir = GOFFICE_ICONDIR; static char const *libgoffice_locale_dir = GOFFICE_LOCALEDIR; static char const *libgoffice_lib_dir = GOFFICE_LIBDIR; +/** + * SECTION: goffice + * @Title: GOffice + * + * GOffice is a #GObject based C library. It provides easy API access to + * creating and manipulating graphs and canvases. See #GogGraph and #GocCanvas. + * It also includes a number of utilities and widgets that might be useful in + * office productivity software and similar. + * + * The GOffice code was originally a part of Gnumeric, but was split into a + * separate library in 2005. Today it is being used by projects such as + * Gnumeric, Gnucash, Abiword (optional), GChemUtils and more. + * + * GOffice is cross platform, with support for Windows, OSX, GNU/Linux, + * and other Unix-like systems. It can be built with or without GTK+ + * integration support. + * + * To include GOffice use: + * <informalexample> + * <programlisting> + * #include <goffice/goffice.h> + * </programlisting> + * </informalexample> + * GOffice provides a pkg-config metadata file named + * "libgoffice-$major.$minor.pc", where $major and $minor denote which version + * GOffice is. So to link against GOffice 0.8 series, use: + * <informalexample> + * <programlisting> + * pkg-config --libs libgoffice-0.8 + * </programlisting> + * </informalexample> + * + * API and ABI compatability is maintained per minor release series, e.g: + * all 0.8.x releases are ABI/API compatible with previous 0.8.x releases. + * + * As of September 2010, there are no bindings for other languages + * than C available. + */ + gchar const * go_sys_data_dir (void) { @@ -86,6 +125,16 @@ go_sys_lib_dir (void) return libgoffice_lib_dir; } + +/** + * libgoffice_init: + * + * Initialize GOffice. + * + * This function can be called several times; each call will + * increment a reference counter. Code that calls this function should call + * libgoffice_shutdown() when done to decrement the counter. + */ static int initialized = 0; void libgoffice_init (void) @@ -161,6 +210,12 @@ libgoffice_init (void) initialized = TRUE; } +/** + * libgoffice_shutdown: + * + * Decrements the counter for data initialized by libgoffice_init(). + * When the counter reaches 0, the data is freed/cleaned up as appropriate. + */ void libgoffice_shutdown (void) { diff --git a/goffice/graph/gog-axis.c b/goffice/graph/gog-axis.c index 307192d..4762c67 100644 --- a/goffice/graph/gog-axis.c +++ b/goffice/graph/gog-axis.c @@ -33,6 +33,16 @@ /* this should be per model */ #define PAD_HACK 4 /* pts */ +/** + * SECTION: gog-axis + * @short_description: An axis. + * + * An axis of a #GogPlot. The axis handles things like the bounds, ticks, and + * tick value formats. + * When used in plots with X/Y/Z axes, it can optionally have one + * #GogLabel objects in the role "Label". + */ + static struct { GogAxisPolarUnit unit; const char *name; diff --git a/goffice/graph/gog-chart.c b/goffice/graph/gog-chart.c index adbd99d..2cd70ed 100644 --- a/goffice/graph/gog-chart.c +++ b/goffice/graph/gog-chart.c @@ -50,6 +50,15 @@ #include <goffice/gtk/goffice-gtk.h> #endif +/** + * SECTION: gog-chart + * @short_description: A chart. + * @See_also: #GogPlot + * + * #GogChart wraps one or more #GogPlot objects, so that you can superimpose + * them on top of each other. In addition, the chart can have a title and a legend. +*/ + static const struct { char const *name; GogAxisSet const axis_set; diff --git a/goffice/graph/gog-graph.c b/goffice/graph/gog-graph.c index 072af7d..a87fca6 100644 --- a/goffice/graph/gog-graph.c +++ b/goffice/graph/gog-graph.c @@ -44,6 +44,20 @@ #define GOG_GRAPH_DEFAULT_WIDTH GO_CM_TO_PT (12.0) #define GOG_GRAPH_DEFAULT_HEIGHT GO_CM_TO_PT (8.0) +/** + * SECTION: gog-graph + * @short_description: The graph object. + * + * A graph (in the abstract sense) in GOffice is an hierarical object model, + * with a #GogGraph object as the top-level object. + * Objects that can be part of a graph is a subclass of #GogObject. Those, and + * related objects have the prefix "Gog" in the class name. + * See #GogObject for how to manipulate the object model, and the individual + * classes for specifics. + * + * A #GogGraph can have 1 or more children in the roles "Chart" and "Title". + */ + enum { GRAPH_PROP_0, GRAPH_PROP_THEME, diff --git a/goffice/graph/gog-label.c b/goffice/graph/gog-label.c index a57461d..7c58595 100644 --- a/goffice/graph/gog-label.c +++ b/goffice/graph/gog-label.c @@ -26,6 +26,14 @@ #include <gsf/gsf-impl-utils.h> #include <glib/gi18n-lib.h> +/** + * SECTION: gog-label + * @short_description: A text label. + * + * A text label for use in a graph. + * Can for instance be used as a title of a #GogChart or #GogGraph. + */ + static GType gog_text_view_get_type (void); enum { diff --git a/goffice/graph/gog-legend.c b/goffice/graph/gog-legend.c index 41ad4fe..0b8a532 100644 --- a/goffice/graph/gog-legend.c +++ b/goffice/graph/gog-legend.c @@ -40,6 +40,14 @@ #include <math.h> +/** + * SECTION: gog-legend + * @short_description: A legend. + * + * A legend shows the name of each #GogSeries and which colors they + * have in the plot. To use, add in the role "Legend" of a #GogChart. + */ + struct _GogLegend { GogOutlinedObject base; diff --git a/goffice/graph/gog-object.c b/goffice/graph/gog-object.c index 5500f69..016397d 100644 --- a/goffice/graph/gog-object.c +++ b/goffice/graph/gog-object.c @@ -27,6 +27,23 @@ #include <string.h> #include <stdlib.h> +/** + * SECTION: gog-object + * @short_description: The base class for graph objects. + * @See_also: #GogGraph + * + * Abstract base class that objects in the graph hierarchy are based on. + * This class handles manipulation of the object hierarchy, and positioning of + * objects in the graph. + * + * Every object has a name that is unique in the graph. It can have a parent + * and a list of children in specific roles (see #GogObjectRole). + * There can generally be several children in each role. + * + * If built with GTK+ support, each object also knows how to populate a widget + * that allows one to manipulate the attributes of that object. This can be used + * by #GOEditor to present a widget that allows manipulation of the whole graph. + */ typedef struct { char const *label; diff --git a/goffice/graph/gog-plot.c b/goffice/graph/gog-plot.c index 8228c4e..1613c5e 100644 --- a/goffice/graph/gog-plot.c +++ b/goffice/graph/gog-plot.c @@ -45,6 +45,21 @@ #define GOG_PLOT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GOG_TYPE_PLOT, GogPlotClass)) +/** + * SECTION: gog-plot + * @short_description: A plot. + * @See_also: #GogChart, #GogSeries + * + * This is the object that visualizes data. + * To manipulate the data shown in the plot, use gog_plot_new_series() and + * gog_plot_clear_series() + * + * Plots are implemented as plug-ins, so make sure the plug-in system is + * initialized before trying to create one. See go_plugins_init() + * + * GOffice ships a number of common plot implementations by default. + */ + enum { PLOT_PROP_0, PLOT_PROP_VARY_STYLE_BY_ELEMENT, diff --git a/goffice/graph/gog-renderer.c b/goffice/graph/gog-renderer.c index 233b9dc..17a32ee 100644 --- a/goffice/graph/gog-renderer.c +++ b/goffice/graph/gog-renderer.c @@ -51,6 +51,14 @@ #include <math.h> +/** + * SECTION: gog-renderer + * @short_description: Rendering + * + * Note that #GogGraph has a functions for export/rendering, so you do not always + * need to use a #GogRenderer directly. +*/ + enum { RENDERER_PROP_0, RENDERER_PROP_MODEL, diff --git a/goffice/graph/gog-series.c b/goffice/graph/gog-series.c index 534744e..ccadb40 100644 --- a/goffice/graph/gog-series.c +++ b/goffice/graph/gog-series.c @@ -27,6 +27,13 @@ #include <string.h> +/** + * SECTION: gog-series + * @short_description: A single data series. + * + * A #GogSeries represents a data series that can be added to a #GogPlot. + */ + /* Keep in sync with GogSeriesFillType enum */ static struct { GogSeriesFillType type; diff --git a/goffice/gtk/go-graph-widget.c b/goffice/gtk/go-graph-widget.c index 5c12180..0c20d86 100644 --- a/goffice/gtk/go-graph-widget.c +++ b/goffice/gtk/go-graph-widget.c @@ -30,6 +30,13 @@ static void go_graph_widget_request_update (GOGraphWidget *w); +/** + * SECTION: go_graph_widget + * @short_description: Widget showing a #GogGraph. + * + * Utility widget for showing a #GogGraph. + */ + enum { GRAPH_WIDGET_PROP_0, GRAPH_WIDGET_PROP_ASPECT_RATIO, -- 1.7.2.2
_______________________________________________ gnumeric-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnumeric-list
