GogPlot: GOffice Reference Manual

## GogPlot GogPlot — A plot. |

## Functions

#define | GOG_PLOT_GET_CLASS()
void | gog_plot_axis_clear ()
gboolean | gog_plot_axis_set_assign ()
gboolean | gog_plot_axis_set_is_valid ()
GogAxisSet | gog_plot_axis_set_pref ()
void | gog_plot_clear_series ()
GogPlotDesc const * | gog_plot_description ()
void | gog_plot_foreach_elem ()
GogAxis * | gog_plot_get_axis ()
GOData * | gog_plot_get_axis_bounds ()
void | gog_plot_get_cardinality ()
double | gog_plot_get_percent_value ()
GSList const * | gog_plot_get_series ()
void | gog_plot_guru_helper ()
GogPlot * | gog_plot_new_by_name ()
GogPlot * | gog_plot_new_by_type ()
GogSeries * | gog_plot_new_series ()
void | gog_plot_request_cardinality_update ()
void | gog_plot_set_axis ()
gboolean | gog_plot_supports_vary_style_by_element ()
void | gog_plot_update_3d ()
void | gog_plot_update_cardinality ()
int | gog_plot_view_get_data_at_point ()

## Types and Values

| GogPlot
| GogPlotClass
| GogPlotDesc
| GogPlotView
| GogPlotViewClass
| GogPlotBoundInfo

## Object Hierarchy

        GObject
        ├── GogObject
        │   ╰── GogPlot
        ╰── GogView
            ╰── GogPlotView

## 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.

## Functions

### GOG_PLOT_GET_CLASS()

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

### 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`

#### Parameters

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);

[skip]

#### Parameters

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.

#### Parameters

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);

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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);

#### Parameters

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);

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

view | GogPlotView |
x | x position |
y | y position |
series | where to store the series |

#### Returns

index of the found data in `series` or -1.

## Types and Values

### 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;

#### Members

GogObjectClass `base`; | base class |
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 int num_series_max;
    	GogSeriesDesc series;
    } GogPlotDesc;

#### Members

unsigned int `num_series_max`; | maximum number of series that can be added. |
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;

#### Members

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

### 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.

#### Members

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. |

## See Also

GogChart, GogSeries