## GogAxis

GogAxis — Master axes

## 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_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);
    #define             GOG_AXIS_TYPE
    #define             GOG_AXIS                            (o)
    #define             IS_GOG_AXIS                         (o)
    GType               gog_axis_get_type                   (void);
    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);
    gboolean            gog_axis_set_format                 (GogAxis *axis,
                                                             GOFormat *fmt);
    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);
    GSListconst *       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

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

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

### GogAxisTick

    typedef struct {
    	double		 position;
    	GogAxisTickTypes	 type;
    	char 		*label;
    } GogAxisTick;

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

### 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.
`value` : |
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_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 wether `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);

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

`map` : | a GogAxisMap
Returns : |

### gog_axis_map_get_extents ()

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

Gets start and stop for 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. For example, an non inverted invalid X axis will have start set to 0.0 and stop set to 1.0.

minimum or maximum can be NULL.

`map` : | a GogAxisMap
`start` : | start for this axis
`stop` : | 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 given axis map in data coordinates. If axis is invalid, it'll return arbitrary bounds. For example, for an invalid x axis, minimum = 0.0 and maximum = 1.0.

minimum or maximum can be NULL.

`map` : | a GogAxisMap
`minimum` : | minimum for this axis
`maximum` : | 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);

Accessor to the axis is_inverted property.

`map` : | a GogAxisMap
Returns : |

### GOG_AXIS_TYPE

    #define GOG_AXIS_TYPE	(gog_axis_get_type ())

### GOG_AXIS()

    #define GOG_AXIS(o)	(G_TYPE_CHECK_INSTANCE_CAST ((o), GOG_AXIS_TYPE, GogAxis))

`o` : |

### IS_GOG_AXIS()

    #define IS_GOG_AXIS(o)	(G_TYPE_CHECK_INSTANCE_TYPE ((o), GOG_AXIS_TYPE))

`o` : |

### gog_axis_get_type ()

    GType               gog_axis_get_type                   (void);

Returns : |

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

return TRUE if the bounds stored in `minima` and `maxima` are sane

`axis` : | GogAxis
`minima` : | result
`maxima` : | result
Returns : |

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

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

### gog_axis_get_entry ()

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

`axis` : | GogAxis
`i` : |
`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 ()

    GSListconst *       gog_axis_contributors               (GogAxis *axis);

`axis` : |
Returns : |

### 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` : |
`major` : |
Returns : |

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