>From eac1a539cec0d54cb97ee6f623fc9e8a3dde2d4b Mon Sep 17 00:00:00 2001 From: Jon Nordby 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 @@ Goffice Reference Manual For goffice &version; - + + + Graphs @@ -25,7 +27,6 @@ - Abstract Base Classes @@ -40,6 +41,7 @@ + Utilities @@ -84,6 +86,7 @@ Widgets + Base widgets @@ -195,7 +198,6 @@ - @@ -209,7 +211,6 @@ - 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: + * + * + * #include + * + * + * 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: + * + * + * pkg-config --libs libgoffice-0.8 + * + * + * + * 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 #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 #include +/** + * 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 +/** + * 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 #include +/** + * 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 +/** + * 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 +/** + * 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