## GogPlot

GogPlot — A plot.

## Synopsis

                        GogPlot;
                        GogPlotClass;
                        GogPlotDesc;
                        GogPlotView;
                        GogPlotViewClass;
    #define             GOG_PLOT_GET_CLASS                  (o)
                        GogPlotBoundInfo;
    void                gog_plot_axis_clear                 (GogPlot *plot,
                                                             GogAxisSet filter);
    gboolean            gog_plot_axis_set_assign            (GogPlot *plot,
                                                             GogAxisSet type);
    gboolean            gog_plot_axis_set_is_valid          (GogPlot const *plot,
                                                             GogAxisSet type);
    GogAxisSet          gog_plot_axis_set_pref              (GogPlot const *plot);
    void                gog_plot_clear_series               (GogPlot *plot);
    GogPlotDesc const * gog_plot_description                (GogPlot const *plot);
    void                gog_plot_foreach_elem               (GogPlot *plot,
                                                             gboolean only_visible,
                                                             GogEnumFunc handler,
                                                             gpointer data);
    GogAxis *           gog_plot_get_axis                   (GogPlot const *plot,
                                                             GogAxisType type);
    GOData *            gog_plot_get_axis_bounds            (GogPlot *plot,
                                                             GogAxisType axis,
                                                             GogPlotBoundInfo *bounds);
    void                gog_plot_get_cardinality            (GogPlot *plot,
                                                             unsigned *full,
                                                             unsigned *visible);
    double              gog_plot_get_percent_value          (GogPlot *plot,
                                                             unsigned  series,
                                                             unsigned  index);
    GSList const *      gog_plot_get_series                 (GogPlot const *plot);
    void                gog_plot_guru_helper                (GogPlot *plot);
    GogPlot *           gog_plot_new_by_name                (char const *id);
    GogPlot *           gog_plot_new_by_type                (GogPlotType const *type);
    GogSeries *         gog_plot_new_series                 (GogPlot *plot);
    void                gog_plot_request_cardinality_update (GogPlot *plot);
    void                gog_plot_set_axis                   (GogPlot *plot,
                                                             GogAxis *axis);
    gboolean            gog_plot_supports_vary_style_by_element
                                                            (GogPlot const *plot);
    void                gog_plot_update_3d                  (GogPlot *plot);
    void                gog_plot_update_cardinality         (GogPlot *plot,
                                                             int index_num);
    int                 gog_plot_view_get_data_at_point     (GogPlotView *view,
                                                             double x,
                                                             double y,
                                                             GogSeries **series);

## Object Hierarchy

      GObject
       +----GogObject
             +----GogPlot

      GObject
       +----GogView
             +----GogPlotView

## Properties

      "bubble-axis"              guint                 : Read / Write
      "circ-axis"                guint                 : Read / Write
      "color-axis"               guint                 : Read / Write
      "guru-hints"               gchar*                : Read / Write
      "interpolation"            gchar*                : Read / Write
      "plot-group"               gchar*                : Read / Write
      "pseudo-3d-axis"           guint                 : Read / Write
      "radial-axis"              guint                 : Read / Write
      "vary-style-by-element"    gboolean              : Read / Write
      "x-axis"                   guint                 : Read / Write
      "y-axis"                   guint                 : Read / Write
      "z-axis"                   guint                 : Read / Write

## Description

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.

## Details

### GogPlot

    typedef struct _GogPlot GogPlot;

### GogPlotClass

    typedef struct {
    	GogObjectClass base;

    	GogPlotDesc desc;
    	GType		series_type;

    	GogAxisSet axis_set;

    	/* Virtuals */

    	GOData	  *(*axis_get_bounds) 	(GogPlot *plot, GogAxisType axis,
    					 GogPlotBoundInfo *bounds);

    	gboolean   (*supports_vary_style_by_element) (GogPlot const *plot);

    	/* %TRUE if the plot prefers to display series in reverse order for
    	 * legends (e.g. stacked plots want top element to be the last series) */
    	gboolean   (*enum_in_reverse) (GogPlot const *plot);

    	void       (*foreach_elem)    	(GogPlot *plot, gboolean only_visible,
    					 GogEnumFunc handler, gpointer data);

    	void       (*update_3d)		(GogPlot *plot);
    	void	   (*guru_helper) (GogPlot *plot, char const *hint);
    	double	   (*get_percent)       (GogPlot *plot, unsigned series, unsigned index);
    } GogPlotClass;

GogObjectClass `base`; |
GogPlotDesc `desc`; | GogPlotDesc
GType `series_type`; | series type.
GogAxisSet `axis_set`; | set of use axes.
`axis_get_bounds` () | requests the axis bounds
`supports_vary_style_by_element` () | `TRUE` if each element has its own style.
`enum_in_reverse` () | `TRUE` if the plot prefers to display series in reverse order for legends (e.g. stacked plots want top element to be the last series.
`foreach_elem` () | enumerates the elements visible in the legend.
`update_3d` () | updates 3D (and contour) plots.
`guru_helper` () | customizes a new plot in the graph editor dialog.
`get_percent` () | get the value as a percentage.

### GogPlotDesc

    typedef struct {
    	unsigned  num_series_max;
    	GogSeriesDesc series;
    } GogPlotDesc;

GogSeriesDesc `series`; | series description.

### GogPlotView

    typedef struct _GogPlotView GogPlotView;

### GogPlotViewClass

    typedef struct {
    	GogViewClass base;
    	int     (*get_data_at_point)    (GogPlotView *view, double x, double y, GogSeries **series);
    } GogPlotViewClass;

GogViewClass `base`; |
`get_data_at_point` () | returns the data index at the given position, -1 if none.

### GOG_PLOT_GET_CLASS()

    #define GOG_PLOT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GOG_TYPE_PLOT, GogPlotClass))

### GogPlotBoundInfo

    typedef struct {
    	struct _GogPlotBound {
    		double minima, maxima;
    	} val, logical;
    	gboolean is_discrete;
    	gboolean center_on_ticks;
    	GOFormat *fmt;

    	const GODateConventions *date_conv;
    } GogPlotBoundInfo;

Used by plots to give formating informations to each axis. GogPlotBoundInfo::val are the values limits, GogPlotBoundInfo::logical are the actual needed display limits.

gboolean `is_discrete`; | whether the data are discrete.
gboolean `center_on_ticks`; | whether to center data on ticks.
GOFormat *`fmt`; | GOFormat to use.
const GODateConventions *`date_conv`; | the used GODateConventions.

### gog_plot_axis_clear ()

    void                gog_plot_axis_clear                 (GogPlot *plot,
                                                             GogAxisSet filter);

A utility method to clear all existing axis associations flagged by `filter`

`plot` : | GogPlot
`filter` : | GogAxisSet

### gog_plot_axis_set_assign ()

    gboolean            gog_plot_axis_set_assign            (GogPlot *plot,
                                                             GogAxisSet type);

### gog_plot_axis_set_is_valid ()

    gboolean            gog_plot_axis_set_is_valid          (GogPlot const *plot,
                                                             GogAxisSet type);

### gog_plot_axis_set_pref ()

    GogAxisSet          gog_plot_axis_set_pref              (GogPlot const *plot);

### gog_plot_clear_series ()

    void                gog_plot_clear_series               (GogPlot *plot);

### gog_plot_description ()

    GogPlotDesc const * gog_plot_description                (GogPlot const *plot);

`plot` : | GogPlot
Returns : | the GogPlotDesc for `plot`. [transfer none]

### gog_plot_foreach_elem ()

    void                gog_plot_foreach_elem               (GogPlot *plot,
                                                             gboolean only_visible,
                                                             GogEnumFunc handler,
                                                             gpointer data);

Executes `funcfor` each plot element. Used to build a legend.

`plot` : | GogPlot
`only_visible` : | whether to restrict to visible elements.
`handler` : | GogEnumFunc. [scope call]
`data` : | user data for `func`

### gog_plot_get_axis ()

    GogAxis *           gog_plot_get_axis                   (GogPlot const *plot,
                                                             GogAxisType type);

`plot` : | GogPlot
`type` : | GogAxisType
Returns : | the axis if any. [transfer none]

### gog_plot_get_axis_bounds ()

    GOData *            gog_plot_get_axis_bounds            (GogPlot *plot,
                                                             GogAxisType axis,
                                                             GogPlotBoundInfo *bounds);

Queries `plot` for its axis preferences for `axis` and stores the results in `bounds`. All elements of `bounds` are initialized to sane values before the query _EXCEPT_ ::fmt. The caller is responsible for initializing it. This is done so that once on plot has selected a format the others need not do the lookup too if so desired.

Caller is responsible for unrefing ::fmt.

`plot` : | GogPlot
`axis` : | GogAxisType
`bounds` : | GogPlotBoundInfo
Returns : | The data providing the bound (does not add a ref). [transfer none]

### gog_plot_get_cardinality ()

    void                gog_plot_get_cardinality            (GogPlot *plot,
                                                             unsigned *full,
                                                             unsigned *visible);

Return the number of logical elements in the plot. See `gog_chart_get_cardinality`.

`full` and `visible` may be NULL.

`plot` : | GogPlot
`full` : | placeholder for full cardinality
`visible` : | placeholder for visible cardinality

### gog_plot_get_percent_value ()

    double              gog_plot_get_percent_value          (GogPlot *plot,
                                                             unsigned  series,
                                                             unsigned  index);

### gog_plot_get_series ()

    GSList const *      gog_plot_get_series                 (GogPlot const *plot);

`plot` : | GogPlot
Returns : | (transfer none) (element-type GogSeries) : A list of the series in `plot`. Do not modify or free the list.

### gog_plot_guru_helper ()

    void                gog_plot_guru_helper                (GogPlot *plot);

### gog_plot_new_by_name ()

    GogPlot *           gog_plot_new_by_name                (char const *id);

### gog_plot_new_by_type ()

    GogPlot *           gog_plot_new_by_type                (GogPlotType const *type);

### gog_plot_new_series ()

    GogSeries *         gog_plot_new_series                 (GogPlot *plot);

`plot` : | GogPlot
Returns : | a new GogSeries of a type consistent with `plot`. [transfer none]

### gog_plot_request_cardinality_update ()

    void                gog_plot_request_cardinality_update (GogPlot *plot);

### gog_plot_set_axis ()

    void                gog_plot_set_axis                   (GogPlot *plot,
                                                             GogAxis *axis);

Connect `axis` and `plot`.

`plot` : | GogPlot
`axis` : | GogAxis

### gog_plot_supports_vary_style_by_element ()

    gboolean            gog_plot_supports_vary_style_by_element
                                                            (GogPlot const *plot);

### gog_plot_update_3d ()

    void                gog_plot_update_3d                  (GogPlot *plot);

### gog_plot_update_cardinality ()

    void                gog_plot_update_cardinality         (GogPlot *plot,
                                                             int index_num);

Update cardinality and cache result. See `gog_chart_get_cardinality`.

`plot` : | GogPlot
`index_num` : | index offset for this plot

### gog_plot_view_get_data_at_point ()

    int                 gog_plot_view_get_data_at_point     (GogPlotView *view,
                                                             double x,
                                                             double y,
                                                             GogSeries **series);

Search a data represented at (`x`,`y`) in `view` and set `series` on success.

`view` : | GogPlotView
`x` : | x position
`y` : | y position
`series` : | where to store the series
Returns : | index of the found data in `series` or -1.

## Property Details

### The `"bubble-axis"` property

      "bubble-axis"              guint                 : Read / Write

Reference to bubble axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"circ-axis"` property

      "circ-axis"                guint                 : Read / Write

Reference to circular axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"color-axis"` property

      "color-axis"               guint                 : Read / Write

Reference to color axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"guru-hints"` property

      "guru-hints"               gchar*                : Read / Write

Semicolon separated list of hints for automatic addition of objects in guru dialog.

Default value: NULL

### The `"interpolation"` property

      "interpolation"            gchar*                : Read / Write

Default type of series line interpolation.

Default value: "linear"

### The `"plot-group"` property

      "plot-group"               gchar*                : Read / Write

Name of plot group if any.

Default value: NULL

### The `"pseudo-3d-axis"` property

      "pseudo-3d-axis"           guint                 : Read / Write

Reference to pseudo-3D axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"radial-axis"` property

      "radial-axis"              guint                 : Read / Write

Reference to radial axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"vary-style-by-element"` property

      "vary-style-by-element"    gboolean              : Read / Write

Use a different style for each segment.

Default value: FALSE

### The `"x-axis"` property

      "x-axis"                   guint                 : Read / Write

Reference to X axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"y-axis"` property

      "y-axis"                   guint                 : Read / Write

Reference to Y axis.

Allowed values: <= G_MAXINT

Default value: 0

### The `"z-axis"` property

      "z-axis"                   guint                 : Read / Write

Reference to Z axis.

Allowed values: <= G_MAXINT

Default value: 0

## See Also

GogChart, GogSeries