gog-axis

gog-axis — An axis.

Synopsis

enum                GogAxisPolarUnit;
enum                GogAxisElemType;
                    GogAxisTick;
                    GogAxisMap;
GogAxisMap*         gog_axis_map_new                    (GogAxis *axis,
                                                         double offset,
                                                         double length);
double              gog_axis_map                        (GogAxisMap *map,
                                                         double value);
double              gog_axis_map_to_view                (GogAxisMap *map,
                                                         double value);
double              gog_axis_map_derivative_to_view     (GogAxisMap *map,
                                                         double value);
double              gog_axis_map_from_view              (GogAxisMap *map,
                                                         double value);
gboolean            gog_axis_map_finite                 (GogAxisMap *map,
                                                         double value);
double              gog_axis_map_get_baseline           (GogAxisMap *map);
void                gog_axis_map_get_extents            (GogAxisMap *map,
                                                         double *start,
                                                         double *stop);
void                gog_axis_map_get_bounds             (GogAxisMap *map,
                                                         double *minimum,
                                                         double *maximum);
void                gog_axis_map_free                   (GogAxisMap *map);
gboolean            gog_axis_map_is_valid               (GogAxisMap *map);
gboolean            gog_axis_map_is_inverted            (GogAxisMap *map);
gboolean            gog_axis_map_is_discrete            (GogAxisMap *map);
GogAxisType         gog_axis_get_atype                  (GogAxis const *axis);
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);
gboolean            gog_axis_get_bounds                 (GogAxis const *axis,
                                                         double *minima,
                                                         double *maxima);
void                gog_axis_set_bounds                 (GogAxis *axis,
                                                         double minimum,
                                                         double maximum);
void                gog_axis_set_extents                (GogAxis *axis,
                                                         double start,
                                                         double stop);
GOFormat *          gog_axis_get_format                 (GogAxis const *axis);
GOFormat *          gog_axis_get_effective_format       (GogAxis const *axis);
gboolean            gog_axis_set_format                 (GogAxis *axis,
                                                         GOFormat *fmt);
const GODateConventions * gog_axis_get_date_conv        (GogAxis const *axis);
unsigned            gog_axis_get_ticks                  (GogAxis *axis,
                                                         GogAxisTick **ticks);
GOData *            gog_axis_get_labels                 (GogAxis const *axis,
                                                         GogPlot **plot_that_labeled_axis);
double              gog_axis_get_entry                  (GogAxis const *axis,
                                                         GogAxisElemType i,
                                                         gboolean *user_defined);
void                gog_axis_add_contributor            (GogAxis *axis,
                                                         GogObject *contrib);
void                gog_axis_del_contributor            (GogAxis *axis,
                                                         GogObject *contrib);
GSList const *      gog_axis_contributors               (GogAxis *axis);
void                gog_axis_clear_contributors         (GogAxis *axis);
void                gog_axis_bound_changed              (GogAxis *axis,
                                                         GogObject *contrib);
GogGridLine *       gog_axis_get_grid_line              (GogAxis *axis,
                                                         gboolean major);
void                gog_axis_set_polar_unit             (GogAxis *axis,
                                                         GogAxisPolarUnit unit);
GogAxisPolarUnit    gog_axis_get_polar_unit             (GogAxis *axis);
double              gog_axis_get_polar_perimeter        (GogAxis *axis);
double              gog_axis_get_circular_rotation      (GogAxis *axis);

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

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.

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.

GogAxisMap

typedef struct _GogAxisMap GogAxisMap;


gog_axis_map_new ()

GogAxisMap*         gog_axis_map_new                    (GogAxis *axis,
                                                         double offset,
                                                         double length);

Creates a GogAxisMap for data mapping to plot window. offset and length are optional parameters to be used with gog_axis_map_to_view in order to translates data coordinates into canvas space.

axis :

a GogAxis

offset :

start of plot area.

length :

length of plot area.

Returns :

a newly allocated GogAxisMap. [transfer full]

gog_axis_map ()

double              gog_axis_map                        (GogAxisMap *map,
                                                         double value);

Converts value to plot coordinates. A value in [0,1.0] range means a data within axis bounds.

map :

a GogAxisMap

value :

value to map to plot space.

Returns :

mapped value.

gog_axis_map_to_view ()

double              gog_axis_map_to_view                (GogAxisMap *map,
                                                         double value);

Converts value from data space to canvas space, using offset and length parameters given to gog_axis_map_new.

map :

a GogAxisMap

value :

value to map to canvas space

Returns :

a value in canvas coordinates

gog_axis_map_derivative_to_view ()

double              gog_axis_map_derivative_to_view     (GogAxisMap *map,
                                                         double value);

map :

a GogAxisMap

value :

value to map to canvas space

Returns :

the derivative of the mapping expression at value.

gog_axis_map_from_view ()

double              gog_axis_map_from_view              (GogAxisMap *map,
                                                         double value);

Converts value from canvas space to data space.

map :

a GogAxisMap

value :

value to unmap from canvas space.

Returns :

value in data coordinates

gog_axis_map_finite ()

gboolean            gog_axis_map_finite                 (GogAxisMap *map,
                                                         double value);

Tests whether value is valid for the given map.

map :

a GogAxisMap

value :

value to test

Returns :

TRUE if value means something

gog_axis_map_get_baseline ()

double              gog_axis_map_get_baseline           (GogAxisMap *map);

map :

a GogAxisMap

Returns :

the baseline for map, in view coordinates, clipped to offset and offset+length, where offset and length are the parameters of gog_axis_map_new.

gog_axis_map_get_extents ()

void                gog_axis_map_get_extents            (GogAxisMap *map,
                                                         double *start,
                                                         double *stop);

Gets start and stop for the whole chart relative to the given axis map in data coordinates. If axis is not inverted, start = minimum and stop = maximum. If axis is invalid, it'll return arbitrary bounds.

Any of start and stop may be NULL.

map :

a GogAxisMap

start :

location to store start for this axis

stop :

location to store stop for this axis

gog_axis_map_get_bounds ()

void                gog_axis_map_get_bounds             (GogAxisMap *map,
                                                         double *minimum,
                                                         double *maximum);

Gets bounds for the whole chart relative to the given axis map in data coordinates. If axis is invalid, it'll return arbitrary bounds.

Any of minimum and maximum may be NULL.

map :

a GogAxisMap

minimum :

location to store minimum for this axis

maximum :

location to store maximum for this axis

gog_axis_map_free ()

void                gog_axis_map_free                   (GogAxisMap *map);

Frees GogAxisMap object.

map :

a GogAxisMap

gog_axis_map_is_valid ()

gboolean            gog_axis_map_is_valid               (GogAxisMap *map);

Tests if map was correctly initialized, i.e. if bounds are valid.

map :

a GogAxisMap

Returns :

TRUE if map is valid

gog_axis_map_is_inverted ()

gboolean            gog_axis_map_is_inverted            (GogAxisMap *map);

map :

a GogAxisMap

Returns :

TRUE is the axis is inverted;

gog_axis_map_is_discrete ()

gboolean            gog_axis_map_is_discrete            (GogAxisMap *map);

map :

a GogAxisMap

Returns :

TRUE is the axis is discrete;

gog_axis_get_atype ()

GogAxisType         gog_axis_get_atype                  (GogAxis const *axis);

axis :

Returns :


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_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_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_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_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_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_get_date_conv ()

const GODateConventions * gog_axis_get_date_conv        (GogAxis const *axis);

axis :

Returns :


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_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_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_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_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_contributors ()

GSList const *      gog_axis_contributors               (GogAxis *axis);

axis :

GogAxis

Returns :

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

gog_axis_clear_contributors ()

void                gog_axis_clear_contributors         (GogAxis *axis);

axis :


gog_axis_bound_changed ()

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

axis :

GogAxis

contrib :

GogObject

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

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_polar_perimeter ()

double              gog_axis_get_polar_perimeter        (GogAxis *axis);

axis :

Returns :


gog_axis_get_circular_rotation ()

double              gog_axis_get_circular_rotation      (GogAxis *axis);

axis :

a GogAxis

Returns :

rotation of a circular GogAxis.