GogAxis: GOffice Reference Manual

## GogAxis GogAxis — An axis. |

## Functions

void | gog_axis_add_contributor ()
void | gog_axis_bound_changed ()
void | gog_axis_clear_contributors ()
GSList const * | gog_axis_contributors ()
void | gog_axis_data_get_bounds ()
void | gog_axis_del_contributor ()
GogAxisType | gog_axis_get_atype ()
gboolean | gog_axis_get_bounds ()
double | gog_axis_get_circular_rotation ()
GogAxisColorMap const * | gog_axis_get_color_map ()
GogColorScale * | gog_axis_get_color_scale ()
const GODateConventions * | gog_axis_get_date_conv ()
GOFormat * | gog_axis_get_effective_format ()
void | gog_axis_get_effective_span ()
double | gog_axis_get_entry ()
GOFormat * | gog_axis_get_format ()
GogGridLine * | gog_axis_get_grid_line ()
GOData * | gog_axis_get_labels ()
double | gog_axis_get_major_ticks_distance ()
GogAxisMetrics | gog_axis_get_metrics ()
double | gog_axis_get_polar_perimeter ()
GogAxisPolarUnit | gog_axis_get_polar_unit ()
GogAxis * | gog_axis_get_ref_axis ()
unsigned | gog_axis_get_ticks ()
gboolean | gog_axis_is_center_on_ticks ()
gboolean | gog_axis_is_discrete ()
gboolean | gog_axis_is_inverted ()
gboolean | gog_axis_is_zero_important ()
void | gog_axis_set_bounds ()
void | gog_axis_set_extents ()
gboolean | gog_axis_set_format ()
GogAxisSet | gog_axis_set_from_str ()
void | gog_axis_set_polar_unit ()

## Types and Values

enum | GogAxisElemType
enum | GogAxisPolarUnit
| GogAxisTick
enum | GogAxisSet
enum | GogAxisMetrics
enum | GogAxisType

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

## Functions

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

#### Parameters

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

#### Parameters

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

#### Parameters

axis | GogAxis |

#### Returns

the list of the axis contributors.

[element-type GogObject][transfer none]

### gog_axis_data_get_bounds ()

    void
    gog_axis_data_get_bounds (GogAxis *axis,
                              GOData *data,
                              double *minimum,
                              double *maximum);

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

    double
    gog_axis_get_major_ticks_distance (GogAxis const *axis);

### gog_axis_get_metrics ()

    GogAxisMetrics
    gog_axis_get_metrics (GogAxis const *axis);

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

#### Parameters

axis | a GogAxis |

#### Returns

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

### gog_axis_get_ref_axis ()

    GogAxis *
    gog_axis_get_ref_axis (GogAxis const *axis);

#### Parameters

axis | a GogAxis |

#### Returns

the axis used to evaluate the length of `axis` or NULL.

[transfer none]

Since: 0.10.17

### gog_axis_get_ticks ()

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

An accessor to `axis->ticks` .

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

axis | GogAxis |

#### Returns

TRUE if `axis` is inverted.

### gog_axis_is_zero_important ()

    gboolean
    gog_axis_is_zero_important (GogAxis *axis);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

axis | GogAxis |
fmt | GOFormat. | [transfer full]

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

#### Parameters

axis | a GogAxis |
unit | GogAxisPolarUnit |

## Types and Values

### enum GogAxisElemType

The indices of the GOData associated to the axis.

#### Members

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

#### Members

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;

#### Members

double `position`; | position on the axis. |
GogAxisTickTypes `type`; | GogAxisTickTypes |
GOString *`str`; | label, might be rich text. |

### enum GogAxisSet

Gives the needed axes for a plot.

#### Members

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 GogAxisMetrics

#### Members

GOG_AXIS_METRICS_INVALID | invalid. |
GOG_AXIS_METRICS_DEFAULT | default. |
GOG_AXIS_METRICS_ABSOLUTE | absolute distance between major ticks. |
GOG_AXIS_METRICS_RELATIVE | relative to another axis. |
GOG_AXIS_METRICS_RELATIVE_TICKS | relative distance between ticks related to another axis. |
GOG_AXIS_METRICS_MAX | first unused value. |

### enum GogAxisType

#### Members

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