Synopsis

enum                GogAxisElemType;
enum                GogAxisPolarUnit;
                    GogAxisTick;
enum                GogAxisSet;
enum                GogAxisType;
void                gog_axis_add_contributor            (GogAxis *axis,
                                                         GogObject *contrib);
void                gog_axis_bound_changed              (GogAxis *axis,
                                                         GogObject *contrib);
void                gog_axis_clear_contributors         (GogAxis *axis);
GSList const *      gog_axis_contributors               (GogAxis *axis);
void                gog_axis_del_contributor            (GogAxis *axis,
                                                         GogObject *contrib);
GogAxisType         gog_axis_get_atype                  (GogAxis const *axis);
gboolean            gog_axis_get_bounds                 (GogAxis const *axis,
                                                         double *minima,
                                                         double *maxima);
double              gog_axis_get_circular_rotation      (GogAxis *axis);
GogAxisColorMap const * gog_axis_get_color_map          (GogAxis *axis);
GogColorScale *     gog_axis_get_color_scale            (GogAxis *axis);
const GODateConventions * gog_axis_get_date_conv        (GogAxis const *axis);
GOFormat *          gog_axis_get_effective_format       (GogAxis const *axis);
void                gog_axis_get_effective_span         (GogAxis const *axis,
                                                         double *start,
                                                         double *end);
double              gog_axis_get_entry                  (GogAxis const *axis,
                                                         GogAxisElemType i,
                                                         gboolean *user_defined);
GOFormat *          gog_axis_get_format                 (GogAxis const *axis);
GogGridLine *       gog_axis_get_grid_line              (GogAxis *axis,
                                                         gboolean major);
GOData *            gog_axis_get_labels                 (GogAxis const *axis,
                                                         GogPlot **plot_that_labeled_axis);
double              gog_axis_get_polar_perimeter        (GogAxis *axis);
GogAxisPolarUnit    gog_axis_get_polar_unit             (GogAxis *axis);
unsigned            gog_axis_get_ticks                  (GogAxis *axis,
                                                         GogAxisTick **ticks);
gboolean            gog_axis_is_center_on_ticks         (GogAxis const *axis);
gboolean            gog_axis_is_discrete                (GogAxis const *axis);
gboolean            gog_axis_is_inverted                (GogAxis const *axis);
void                gog_axis_set_bounds                 (GogAxis *axis,
                                                         double minimum,
                                                         double maximum);
void                gog_axis_set_extents                (GogAxis *axis,
                                                         double start,
                                                         double stop);
gboolean            gog_axis_set_format                 (GogAxis *axis,
                                                         GOFormat *fmt);
GogAxisSet          gog_axis_set_from_str               (char const *str);
void                gog_axis_set_polar_unit             (GogAxis *axis,
                                                         GogAxisPolarUnit unit);

Description

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

Details

enum GogAxisElemType

typedef enum {
	GOG_AXIS_ELEM_MIN = 0,
	GOG_AXIS_ELEM_MAX,
	GOG_AXIS_ELEM_MAJOR_TICK,
	GOG_AXIS_ELEM_MINOR_TICK,
	GOG_AXIS_ELEM_CROSS_POINT,
	GOG_AXIS_ELEM_MAX_ENTRY
} GogAxisElemType;

The indices of the GOData associated to the axis.

GOG_AXIS_ELEM_MIN

minimum value.

GOG_AXIS_ELEM_MAX

maximum value.

GOG_AXIS_ELEM_MAJOR_TICK

distance between two major ticks.

GOG_AXIS_ELEM_MINOR_TICK

distance between two minor ticks.

GOG_AXIS_ELEM_CROSS_POINT

position of the other axis crossing.

GOG_AXIS_ELEM_MAX_ENTRY

maximum value, should not occur.

enum GogAxisPolarUnit

typedef enum {
	GOG_AXIS_POLAR_UNIT_DEGREES,
	GOG_AXIS_POLAR_UNIT_RADIANS,
	GOG_AXIS_POLAR_UNIT_GRADS,
	GOG_AXIS_POLAR_UNIT_MAX
} GogAxisPolarUnit;

GOG_AXIS_POLAR_UNIT_DEGREES

units as degrees.

GOG_AXIS_POLAR_UNIT_RADIANS

units as radians.

GOG_AXIS_POLAR_UNIT_GRADS

units as grads.

GOG_AXIS_POLAR_UNIT_MAX

maximum values, should not occur.

GogAxisTick

typedef struct {
	double		 position;
	GogAxisTickTypes type;
	GOString        *str;
} GogAxisTick;

double position;

position on the axis.

GogAxisTickTypes type;

GogAxisTickTypes

GOString *str;

label, might be rich text.

enum GogAxisSet

typedef enum {
	GOG_AXIS_SET_UNKNOWN 	  = -1,
	GOG_AXIS_SET_NONE   	  = 0,
	GOG_AXIS_SET_X		  = (1 << GOG_AXIS_X),
	GOG_AXIS_SET_XY		  = (1 << GOG_AXIS_X) | (1 << GOG_AXIS_Y),
	GOG_AXIS_SET_XY_pseudo_3d = (1 << GOG_AXIS_X) | (1 << GOG_AXIS_Y) | (1 << GOG_AXIS_PSEUDO_3D),
	GOG_AXIS_SET_XY_COLOR 	  = (1 << GOG_AXIS_X) | (1 << GOG_AXIS_Y) | (1 << GOG_AXIS_COLOR),
	GOG_AXIS_SET_XY_BUBBLE 	  = (1 << GOG_AXIS_X) | (1 << GOG_AXIS_Y) | (1 << GOG_AXIS_BUBBLE),
	GOG_AXIS_SET_XYZ	  = (1 << GOG_AXIS_X) | (1 << GOG_AXIS_Y) | (1 << GOG_AXIS_Z),
	GOG_AXIS_SET_RADAR        = (1 << GOG_AXIS_CIRCULAR) | (1 << GOG_AXIS_RADIAL),
	GOG_AXIS_SET_FUNDAMENTAL  = ((1 << GOG_AXIS_VIRTUAL) - 1),
	GOG_AXIS_SET_ALL	  = ((1 << GOG_AXIS_TYPES) -1)
} GogAxisSet;

Gives the needed axes for a plot.

GOG_AXIS_SET_UNKNOWN

unkown, should not occur.

GOG_AXIS_SET_NONE

no axis.

GOG_AXIS_SET_X

only an X axis.

GOG_AXIS_SET_XY

both X and Y axes.

GOG_AXIS_SET_XY_pseudo_3d

X, Y, and pseudo-3D axes.

GOG_AXIS_SET_XY_COLOR

X, Y, and color axes.

GOG_AXIS_SET_XY_BUBBLE

X, Y, and bubble axes.

GOG_AXIS_SET_XYZ

X, Y, and Z axes.

GOG_AXIS_SET_RADAR

circular and radial axes.

GOG_AXIS_SET_FUNDAMENTAL

mask for all fundamental axes.

GOG_AXIS_SET_ALL

mask for all known axis types.

enum GogAxisType

typedef enum {
	GOG_AXIS_UNKNOWN = -1,
	GOG_AXIS_X	 = 0,
	GOG_AXIS_Y,
	GOG_AXIS_Z,
	GOG_AXIS_CIRCULAR,
	GOG_AXIS_RADIAL,
	GOG_AXIS_VIRTUAL,
	GOG_AXIS_PSEUDO_3D = GOG_AXIS_VIRTUAL,
	GOG_AXIS_COLOR,
	GOG_AXIS_BUBBLE,
	GOG_AXIS_TYPES
} GogAxisType;

GOG_AXIS_UNKNOWN

invalid, should not occur.

GOG_AXIS_X

X axis.

GOG_AXIS_Y

Y axis.

GOG_AXIS_Z

Z axis.

GOG_AXIS_CIRCULAR

circular axis/

GOG_AXIS_RADIAL

radial axis.

GOG_AXIS_VIRTUAL

start of virtual axes.

GOG_AXIS_PSEUDO_3D

pseudo-3d axis.

GOG_AXIS_COLOR

color axis.

GOG_AXIS_BUBBLE

bubble axis.

GOG_AXIS_TYPES

maximum value, should not occur.

gog_axis_add_contributor ()

void                gog_axis_add_contributor            (GogAxis *axis,
                                                         GogObject *contrib);

Register contrib as taking part in the negotiation of axis's bounds.

axis :

GogAxis

contrib :

GogObject (can we relax this to use an interface ?)

gog_axis_bound_changed ()

void                gog_axis_bound_changed              (GogAxis *axis,
                                                         GogObject *contrib);

axis :

GogAxis

contrib :

GogObject

gog_axis_clear_contributors ()

void                gog_axis_clear_contributors         (GogAxis *axis);


gog_axis_contributors ()

GSList const *      gog_axis_contributors               (GogAxis *axis);

axis :

GogAxis

Returns :

the list of the axis contributors. [element-type GogObject][transfer none]

gog_axis_del_contributor ()

void                gog_axis_del_contributor            (GogAxis *axis,
                                                         GogObject *contrib);

contrib no longer takes part in the negotiation of axis's bounds.

axis :

GogAxis

contrib :

GogObject (can we relax this to use an interface ?)

gog_axis_get_atype ()

GogAxisType         gog_axis_get_atype                  (GogAxis const *axis);


gog_axis_get_bounds ()

gboolean            gog_axis_get_bounds                 (GogAxis const *axis,
                                                         double *minima,
                                                         double *maxima);

axis :

GogAxis

minima :

non-NULL storage for result

maxima :

non-NULL storage for result

Returns :

TRUE if the bounds stored in minima and maxima are sane

gog_axis_get_circular_rotation ()

double              gog_axis_get_circular_rotation      (GogAxis *axis);

axis :

a GogAxis

Returns :

rotation of a circular GogAxis.

gog_axis_get_color_map ()

GogAxisColorMap const * gog_axis_get_color_map          (GogAxis *axis);

Retrieves the GogAxisColorMap associated to the axis or NULL.

axis :

a GogAxis

Returns :

the color map used by the axis if any. [transfer none]

gog_axis_get_color_scale ()

GogColorScale *     gog_axis_get_color_scale            (GogAxis *axis);

Retrieves the GogColorScale associated to the axis or NULL.

axis :

a GogAxis

Returns :

the color scale used to display the axis colors dor color and pseudo-3d axes. [transfer none]

gog_axis_get_date_conv ()

const GODateConventions * gog_axis_get_date_conv        (GogAxis const *axis);


gog_axis_get_effective_format ()

GOFormat *          gog_axis_get_effective_format       (GogAxis const *axis);

axis :

GogAxis

Returns :

the GOFormat used for the axis labels. Differs from gog_axis_get_format in that it never returns a general format (see go_format_is_general). [transfer none]

gog_axis_get_effective_span ()

void                gog_axis_get_effective_span         (GogAxis const *axis,
                                                         double *start,
                                                         double *end);


gog_axis_get_entry ()

double              gog_axis_get_entry                  (GogAxis const *axis,
                                                         GogAxisElemType i,
                                                         gboolean *user_defined);

axis :

GogAxis

user_defined :

an optionally NULL pointr to gboolean

Returns :

the value of axis element i and sets user_defined or NaN on error

gog_axis_get_format ()

GOFormat *          gog_axis_get_format                 (GogAxis const *axis);

axis :

GogAxis

Returns :

the format assigned to axis but does not add a reference. [transfer none]

gog_axis_get_grid_line ()

GogGridLine *       gog_axis_get_grid_line              (GogAxis *axis,
                                                         gboolean major);

axis :

GogAxis

major :

whether to retrieve major or minor grid line.

Returns :

a pointer to GridLine object associated to given axis, NULL if it doesn't exists. [transfer none]

gog_axis_get_labels ()

GOData *            gog_axis_get_labels                 (GogAxis const *axis,
                                                         GogPlot **plot_that_labeled_axis);

axis :

a GogAxis

plot_that_labeled_axis :

a GogPlot

Returns :

the possibly NULL GOData used as a label for this axis along with the plot that it was associated with. [transfer none]

gog_axis_get_polar_perimeter ()

double              gog_axis_get_polar_perimeter        (GogAxis *axis);


gog_axis_get_polar_unit ()

GogAxisPolarUnit    gog_axis_get_polar_unit             (GogAxis *axis);

axis :

a GogAxis

Returns :

unit of axis if it's a circular axis of a polar axis set, -1 otherwise.

gog_axis_get_ticks ()

unsigned            gog_axis_get_ticks                  (GogAxis *axis,
                                                         GogAxisTick **ticks);

An accessor to axis->ticks.

axis :

GogAxis

ticks :

an array of GogAxisTick

Returns :

number of ticks

gog_axis_is_center_on_ticks ()

gboolean            gog_axis_is_center_on_ticks         (GogAxis const *axis);

axis :

GogAxis

Returns :

TRUE if labels are centered on ticks when axis is discrete

gog_axis_is_discrete ()

gboolean            gog_axis_is_discrete                (GogAxis const *axis);

axis :

GogAxis

Returns :

TRUE if axis enumerates a set of discrete items, rather than a continuous value

gog_axis_is_inverted ()

gboolean            gog_axis_is_inverted                (GogAxis const *axis);

axis :

GogAxis

Returns :

TRUE if axis is inverted.

gog_axis_set_bounds ()

void                gog_axis_set_bounds                 (GogAxis *axis,
                                                         double minimum,
                                                         double maximum);

Sets axis bounds. If minimum or maximum are not finite values, corresponding bound remains unchanged.

axis :

GogAxis

minimum :

axis low bound

maximum :

axis high bound

gog_axis_set_extents ()

void                gog_axis_set_extents                (GogAxis *axis,
                                                         double start,
                                                         double stop);

Set axis exents. It's a convenience function that sets axis bounds taking into account invert flag.

axis :

GogAxis

start :

axis start bound

stop :

axis stop bound

gog_axis_set_format ()

gboolean            gog_axis_set_format                 (GogAxis *axis,
                                                         GOFormat *fmt);

Absorbs a reference to fmt, and accepts NULL.

axis :

GogAxis

fmt :

GOFormat

Returns :

TRUE if things changed

gog_axis_set_from_str ()

GogAxisSet          gog_axis_set_from_str               (char const *str);


gog_axis_set_polar_unit ()

void                gog_axis_set_polar_unit             (GogAxis *axis,
                                                         GogAxisPolarUnit unit);

Sets unit of a circular axis. See GogAxisPolarUnit for valid values.

axis :

a GogAxis

unit :

GogAxisPolarUnit