GogAxis

## GogAxis GogAxis — An axis. |

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