GwyAxis: Gwyddion Widgets Library Reference Manual

## GwyAxis GwyAxis — Axis with ticks and labels |

## Functions

GtkWidget * | gwy_axis_new ()
void | gwy_axis_set_logarithmic ()
void | gwy_axis_set_visible ()
gboolean | gwy_axis_is_visible ()
gboolean | gwy_axis_is_logarithmic ()
GtkPositionType | gwy_axis_get_orientation ()
void | gwy_axis_set_auto ()
void | gwy_axis_request_range ()
void | gwy_axis_get_range ()
void | gwy_axis_get_requested_range ()
gdouble | gwy_axis_get_magnification ()
const gchar * | gwy_axis_get_magnification_string ()
void | gwy_axis_set_label ()
const gchar * | gwy_axis_get_label ()
void | gwy_axis_set_si_unit ()
void | gwy_axis_enable_label_edit ()
void | gwy_axis_draw_on_drawable ()
GString * | gwy_axis_export_vector ()
const gdouble * | gwy_axis_get_major_ticks ()

## Properties

gboolean | auto | Read / Write
char * | label | Read / Write
int | line-thickness | Read / Write
int | major-length | Read / Write
int | major-maxticks | Read / Write
int | major-thickness | Read / Write
int | minor-division | Read / Write
int | minor-length | Read / Write
int | minor-thickness | Read / Write
int | outer-border-width | Read / Write

## Signals

void | rescaled | Run First

## Types and Values

| GwyAxisParams
struct | GwyAxis
struct | GwyAxisClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GwyAxis

## Implemented Interfaces

GwyAxis implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgwydgets/gwydgets.h>

## Description

GwyAxis is used for drawing axis. It is namely used within GwyGraph widget, but it can be also used standalone. It plots a horizontal or vertical axis with major and minor ticks, with ranges in the requested interval.

## Functions

### gwy_axis_new ()

    GtkWidget *
    gwy_axis_new (gint orientation);

Creates a new axis.

#### Parameters

orientation | axis orientation |

#### Returns

New axis as a GtkWidget.

### gwy_axis_set_logarithmic ()

    void
    gwy_axis_set_logarithmic (GwyAxis *axis,
                              gboolean is_logarithmic);

Sets logarithmic mode.

#### Parameters

axis | graph axis |
is_logarithmic | logarithmic mode |

### gwy_axis_set_visible ()

    void
    gwy_axis_set_visible (GwyAxis *axis,
                          gboolean is_visible);

Sets the visibility of an axis.

#### Parameters

axis | An axis. |
is_visible | visibility |

### gwy_axis_is_visible ()

    gboolean
    gwy_axis_is_visible (GwyAxis *axis);

Determines whether axis is set to be visible.

Return: `TRUE` if `axis` is set to be visible.

#### Parameters

axis | An axis. |

### gwy_axis_is_logarithmic ()

    gboolean
    gwy_axis_is_logarithmic (GwyAxis *axis);

Determines whether axis is set to be locarithmic.

#### Parameters

axis | An axis. |

#### Returns

`TRUE` if `axis` is logarithmic.

### gwy_axis_get_orientation ()

    GtkPositionType
    gwy_axis_get_orientation (GwyAxis *axis);

Gets the orientation of an axis.

#### Parameters

axis | An axis. |

#### Returns

The orientation.

### gwy_axis_set_auto ()

    void
    gwy_axis_set_auto (GwyAxis *axis,
                       gboolean is_auto);

Enables or disables automatic axis adjustmet.

#### Parameters

axis | An axis. |
is_auto | `TRUE` to enable automatic tick size and distribution adjustment, `FALSE` to disable it. |

### gwy_axis_request_range ()

    void
    gwy_axis_request_range (GwyAxis *axis,
                            gdouble min,
                            gdouble max);

Sets the requisition of axis boundaries.

The axis will adjust the boundaries to satisfy requisition but still have reasonable tick values and spacing. Use `gwy_axis_get_range()` to obtain the boundaries the axis actually decided to use.

#### Parameters

axis | An axis. |
min | Minimum requisition (min boundary value). |
max | Maximum requisition (max boundary value). |

### gwy_axis_get_range ()

    void
    gwy_axis_get_range (GwyAxis *axis,
                        gdouble *min,
                        gdouble *max);

Gets the actual boundaries of an axis.

#### Parameters

axis | An axis. |
min | Location to store actual axis minimum, or `NULL`. |
max | Location to store actual axis maximum, or `NULL`. |

### gwy_axis_get_requested_range ()

    void
    gwy_axis_get_requested_range (GwyAxis *axis,
                                  gdouble *min,
                                  gdouble *max);

Gets the requested boundaries of an axis.

#### Parameters

axis | An axis. |
min | Location to store requested axis minimum, or `NULL`. |
max | Location to store requested axis maximum, or `NULL`. |

### gwy_axis_get_magnification ()

    gdouble
    gwy_axis_get_magnification (GwyAxis *axis);

Gets the magnification value of a graph axis.

#### Parameters

axis | Axis widget |

#### Returns

Magnification value of the axis.

### gwy_axis_get_magnification_string ()

    const gchar *
    gwy_axis_get_magnification_string (GwyAxis *axis);

Gets the magnification string of an axis.

#### Parameters

axis | An axis. |

#### Returns

Magnification string of the axis, owned by the axis.

### gwy_axis_set_label ()

    void
    gwy_axis_set_label (GwyAxis *axis,
                        const gchar *label);

Sets the label text of an axis.

#### Parameters

axis | An axis. |
label | The new label text (it can be `NULL` for an empty label). |

### gwy_axis_get_label ()

    const gchar *
    gwy_axis_get_label (GwyAxis *axis);

Gets the label of an axis.

#### Parameters

axis | An axis. |

#### Returns

Axis label as a string owned by `axis` .

### gwy_axis_set_si_unit ()

    void
    gwy_axis_set_si_unit (GwyAxis *axis,
                          GwySIUnit *unit);

Sets the axis unit. This will be added automatically to the label. `unit` is duplicated.

#### Parameters

axis | An axis. |
unit | axis unit |

### gwy_axis_enable_label_edit ()

    void
    gwy_axis_enable_label_edit (GwyAxis *axis,
                                gboolean enable);

Enables/disables user to change axis label by clicking on axis widget.

#### Parameters

axis | Axis widget |
enable | enable/disable user to change axis label |

### gwy_axis_draw_on_drawable ()

    void
    gwy_axis_draw_on_drawable (GwyAxis *axis,
                               GdkDrawable *drawable,
                               GdkGC *gc,
                               gint xmin,
                               gint ymin,
                               gint width,
                               gint height);

Draws the x and y-axis on a drawable

#### Parameters

axis | An axis. |
drawable | Drawable to draw on. |
gc | Graphics context. It is modified by this function unpredictably. |
xmin | The minimum x-axis value. |
ymin | The minimum y-axis value. |
width | The width of the x-axis. |
height | The height of the y-axis. |

### gwy_axis_export_vector ()

    GString *
    gwy_axis_export_vector (GwyAxis *axis,
                            gint xmin,
                            gint ymin,
                            gint width,
                            gint height,
                            gint fontsize);

Renders a graph axis in PostScript.

This is a helper functions for `gwy_graph_export_postscript()` and probably not useful anywhere else.

#### Parameters

axis | An axis. |
xmin | Left edge of the bounding rectangle. |
ymin | Bottom edge of the bounding rectangle. |
width | Width of the bounding rectangle. |
height | Height of the bounding rectangle. |
fontsize | Font size to use. |

#### Returns

A newly created GString.

### gwy_axis_get_major_ticks ()

    const gdouble *
    gwy_axis_get_major_ticks (GwyAxis *axis,
                              guint *nticks);

Gets the positions of major ticks of an axis.

#### Parameters

axis | An axis. |
nticks | Location to store the number of returned ticks. |

#### Returns

The positions of axis major ticks (as real values, not pixels). The returned array is owned by the axis.

## Types and Values

### GwyAxisParams

    typedef struct {
        gint major_length;
        gint major_thickness;
        gint major_maxticks;
        GwyAxisScaleFormat major_printmode;

        gint minor_length;
        gint minor_thickness;
        gint minor_division;          /*minor division*/

        gint line_thickness;

        PangoFontDescription *major_font;
        PangoFontDescription *label_font;
    } GwyAxisParams;

### struct GwyAxis

    struct GwyAxis;

### struct GwyAxisClass

    struct GwyAxisClass {
        GtkWidgetClass parent_class;

        void (*rescaled)(GwyAxis *axis);

        void (*reserved1)(void);
        void (*reserved2)(void);
    };

## Property Details

### The `“auto”` property

      “auto”                     gboolean

Autoscale ticks with changing content.

Owner: GwyAxis

Flags: Read / Write

Default value: TRUE

### The `“label”` property

      “label”                    char *

Axis label (without units).

Owner: GwyAxis

Flags: Read / Write

Default value: ""

### The `“line-thickness”` property

      “line-thickness”           int

Axis main line thickness.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“major-length”` property

      “major-length”             int

Major ticks length.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“major-maxticks”` property

      “major-maxticks”           int

Major ticks maximum number.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,50]

Default value: 5

### The `“major-thickness”` property

      “major-thickness”          int

Major ticks thickness.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“minor-division”` property

      “minor-division”           int

Minor ticks division.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“minor-length”` property

      “minor-length”             int

Minor ticks length.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“minor-thickness”` property

      “minor-thickness”          int

Minor ticks thickness.

Owner: GwyAxis

Flags: Read / Write

Allowed values: [0,20]

Default value: 5

### The `“outer-border-width”` property

      “outer-border-width”       int

The extra amount of space left on the outer side of an axis. This space is also retained when axis is set non-visible.

Owner: GwyAxis

Flags: Read / Write

Allowed values: >= 0

Default value: 5

## Signal Details

### The `“rescaled”` signal

    void
    user_function (GwyAxis *gwyaxis,
                   gpointer user_data)

Flags: Run First

## See Also

GwyColorAxis -- Axis with a false color scale, GwyRuler -- Horizontal and vertical rulers