GtkDataboxRuler: GtkDatabox Reference Manual

## GtkDataboxRuler GtkDataboxRuler — An improved version of the GtkRuler. |

## Functions

GtkWidget * | gtk_databox_ruler_new ()
void | gtk_databox_ruler_set_range ()
void | gtk_databox_ruler_set_max_length ()
void | gtk_databox_ruler_set_scale_type ()
void | gtk_databox_ruler_get_range ()
guint | gtk_databox_ruler_get_max_length ()
GtkDataboxScaleType | gtk_databox_ruler_get_scale_type ()
void | gtk_databox_ruler_set_orientation ()
GtkOrientation | gtk_databox_ruler_get_orientation ()
void | gtk_databox_ruler_set_text_orientation ()
GtkOrientation | gtk_databox_ruler_get_text_orientation ()
void | gtk_databox_ruler_set_text_alignment ()
PangoAlignment | gtk_databox_ruler_get_text_alignment ()
void | gtk_databox_ruler_set_text_hoffset ()
gint | gtk_databox_ruler_get_text_hoffset ()
void | gtk_databox_ruler_set_draw_ticks ()
gboolean | gtk_databox_ruler_get_draw_ticks ()
void | gtk_databox_ruler_set_draw_position ()
gboolean | gtk_databox_ruler_get_draw_position ()
void | gtk_databox_ruler_set_draw_subticks ()
gboolean | gtk_databox_ruler_get_draw_subticks ()
void | gtk_databox_ruler_set_invert_edge ()
gboolean | gtk_databox_ruler_get_invert_edge ()
void | gtk_databox_ruler_set_linear_label_format ()
void | gtk_databox_ruler_set_log_label_format ()
gchar * | gtk_databox_ruler_get_linear_label_format ()
gchar * | gtk_databox_ruler_get_log_label_format ()
void | gtk_databox_ruler_set_manual_ticks ()
gfloat * | gtk_databox_ruler_get_manual_ticks ()
void | gtk_databox_ruler_set_manual_tick_cnt ()
guint | gtk_databox_ruler_get_manual_tick_cnt ()
void | gtk_databox_ruler_set_manual_tick_labels ()
gchar ** | gtk_databox_ruler_get_manual_tick_labels ()
void | gtk_databox_ruler_set_box_shadow ()
GtkShadowType | gtk_databox_ruler_get_box_shadow ()

## Properties

guint | box-shadow | Read / Write
guint | draw-position | Read / Write
guint | draw-subticks | Read / Write
guint | draw-ticks | Read / Write
guint | invert-edge | Read / Write
char * | linear-label-format | Read / Write
char * | log-label-format | Read / Write
double | lower | Read / Write
guint | manual-tick-cnt | Read / Write
gpointer | manual-tick-labels | Read / Write
gpointer | manual-ticks | Read / Write
guint | max-length | Read / Write
guint | orientation | Read / Write / Construct Only
double | position | Read / Write
guint | text-alignment | Read / Write
guint | text-hoffset | Read / Write
guint | text-orientation | Read / Write
double | upper | Read / Write

## Types and Values

struct | GtkDataboxRuler
struct | GtkDataboxRulerClass
| GtkDataboxRulerPrivate
#define | GTK_DATABOX_RULER_MAX_MAX_LENGTH

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkDataboxRuler

## Implemented Interfaces

GtkDataboxRuler implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtkdatabox_ruler.h>

## Description

GtkDataboxRuler is a widget for the GTK+ library similar to GtkRuler.

It is improved in several ways:

- It supports linear and logarithmic scales.

- In the vertical orientation, the labels are rotated 90° (instead of being written as a vertical column of horizontal characters). This increases readability.

- It works for very small and very large value ranges.

## Functions

### gtk_databox_ruler_new ()

    GtkWidget *
    gtk_databox_ruler_new (GtkOrientation orientation);

Creates a new GtkDataboxRuler widget with the given `orientation` (horizontal or vertical).

#### Parameters

orientation | orientation of the ruler |

#### Returns

A new GtkDataboxRuler

### gtk_databox_ruler_set_range ()

    void
    gtk_databox_ruler_set_range (GtkDataboxRuler *ruler,
                                 gdouble lower,
                                 gdouble upper,
                                 gdouble position);

Sets values indicating the range and current position of a GtkDataboxRuler.

See `gtk_databox_ruler_get_range()`.

#### Parameters

ruler | a GtkDataboxRuler |
lower | lower limit of the ruler |
upper | upper limit of the ruler |
position | current position of the mark on the ruler |

### gtk_databox_ruler_set_max_length ()

    void
    gtk_databox_ruler_set_max_length (GtkDataboxRuler *ruler,
                                      guint max_length);

This function sets the maximum number of digits to be used for each tick label of the `ruler` .

The `max_length` cannot be smaller than 2 and not bigger than GTK_DATABOX_RULER_MAX_MAX_LENGTH.

#### Parameters

ruler | A GtkDataboxRuler widget |
max_length | Maximum length (digits) of tick labels |

### gtk_databox_ruler_set_scale_type ()

    void
    gtk_databox_ruler_set_scale_type (GtkDataboxRuler *ruler,
                                      guint scale_type);

This function sets the scale type of the `ruler` .

#### Parameters

ruler | A GtkDataboxRuler widget |
scale_type | The new scale type for `ruler` (linear or logarithmic) |

### gtk_databox_ruler_get_range ()

    void
    gtk_databox_ruler_get_range (GtkDataboxRuler *ruler,
                                 gdouble *lower,
                                 gdouble *upper,
                                 gdouble *position);

Retrieves values indicating the range and current position of a GtkDataboxRuler. See `gtk_databox_ruler_set_range()`.

#### Parameters

ruler | a GtkDataboxRuler |
lower | location to store lower limit of the ruler, or `NULL` |
upper | location to store upper limit of the ruler, or `NULL` |
position | location to store the current position of the mark on the ruler, or `NULL` |

### gtk_databox_ruler_get_max_length ()

    guint
    gtk_databox_ruler_get_max_length (GtkDataboxRuler *ruler);

This function returns the maximum number of digits to be used for each tick label of the `ruler` .

#### Parameters

ruler | A GtkDataboxRuler widget |

#### Returns

The maximum length of the tick labels.

### gtk_databox_ruler_get_scale_type ()

    GtkDataboxScaleType
    gtk_databox_ruler_get_scale_type (GtkDataboxRuler *ruler);

This function returns the scale type of the `ruler` (linear or logarithmic).

#### Parameters

ruler | A GtkDataboxRuler widget |

#### Returns

The scale type (linear or logarithmic)

### gtk_databox_ruler_set_orientation ()

    void
    gtk_databox_ruler_set_orientation (GtkDataboxRuler *ruler,
                                       GtkOrientation orientation);

Sets the orientation of the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |
orientation | new orientation of the ruler |

### gtk_databox_ruler_get_orientation ()

    GtkOrientation
    gtk_databox_ruler_get_orientation (GtkDataboxRuler *ruler);

Gets the orientation of the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Orientation of the `ruler` .

### gtk_databox_ruler_set_text_orientation ()

    void
    gtk_databox_ruler_set_text_orientation
                                   (GtkDataboxRuler *ruler,
                                    GtkOrientation orientation);

Sets the text orientation of the `ruler` (vertical).

#### Parameters

ruler | a GtkDataboxRuler |
orientation | new orientation of the tick marks in the vertical ruler |

### gtk_databox_ruler_get_text_orientation ()

    GtkOrientation
    gtk_databox_ruler_get_text_orientation
                                   (GtkDataboxRuler *ruler);

Gets the text orientation of the `ruler` (horizontal or vertical). Horizontal rulers always have horizontal text

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Text orientation of the `ruler` .

### gtk_databox_ruler_set_text_alignment ()

    void
    gtk_databox_ruler_set_text_alignment (GtkDataboxRuler *ruler,
                                          PangoAlignment alignment);

Sets the text alignment of the `ruler` (vertical with horizontal text).

#### Parameters

ruler | a GtkDataboxRuler |
alignment | new alignment of the tick label in the vertical ruler when horizontal text is set |

### gtk_databox_ruler_get_text_alignment ()

    PangoAlignment
    gtk_databox_ruler_get_text_alignment (GtkDataboxRuler *ruler);

Gets the text alignment of the `ruler` (vertical). Vertical rulers with vertical text do not use this flag

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Text alignment of the `ruler` .

### gtk_databox_ruler_set_text_hoffset ()

    void
    gtk_databox_ruler_set_text_hoffset (GtkDataboxRuler *ruler,
                                        gint offset);

Sets the text x (horizontal) offset of the `ruler` .

#### Parameters

ruler | a GtkDataboxRuler |
offset | new x offset of the tick label in the ruler |

### gtk_databox_ruler_get_text_hoffset ()

    gint
    gtk_databox_ruler_get_text_hoffset (GtkDataboxRuler *ruler);

Gets the text x (horizontal) offset of the `ruler` .

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Text horizontal (x) offset of the `ruler` .

### gtk_databox_ruler_set_draw_ticks ()

    void
    gtk_databox_ruler_set_draw_ticks (GtkDataboxRuler *ruler,
                                      gboolean draw);

Sets the option for drawing the ticks. If false, don't draw any ticks, If true draw major ticks and subticks if the draw_subticks boolean is set.

#### Parameters

ruler | a GtkDataboxRuler |
draw | whether to draw the ticks on the ruler at all |

### gtk_databox_ruler_get_draw_ticks ()

    gboolean
    gtk_databox_ruler_get_draw_ticks (GtkDataboxRuler *ruler);

Gets the draw ticks option from the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Tick drawing option of the `ruler` .

### gtk_databox_ruler_set_draw_position ()

    void
    gtk_databox_ruler_set_draw_position (GtkDataboxRuler *ruler,
                                         gboolean draw);

Sets the option for drawing the position arrows. If false, don't draw any arrows, If true draw arrows.

#### Parameters

ruler | a GtkDataboxRuler |
draw | whether to draw the position arrows on the ruler at all |

### gtk_databox_ruler_get_draw_position ()

    gboolean
    gtk_databox_ruler_get_draw_position (GtkDataboxRuler *ruler);

Gets the draw position arrows option from the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Position drawing option of the `ruler` .

### gtk_databox_ruler_set_draw_subticks ()

    void
    gtk_databox_ruler_set_draw_subticks (GtkDataboxRuler *ruler,
                                         gboolean draw);

Sets the option for drawing the subticks

#### Parameters

ruler | a GtkDataboxRuler |
draw | whether to draw the subticks on the ruler |

### gtk_databox_ruler_get_draw_subticks ()

    gboolean
    gtk_databox_ruler_get_draw_subticks (GtkDataboxRuler *ruler);

Gets the draw subticks option from the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Subtick drawing option of the `ruler` .

### gtk_databox_ruler_set_invert_edge ()

    void
    gtk_databox_ruler_set_invert_edge (GtkDataboxRuler *ruler,
                                       gboolean invert);

Sets the option for drawing the ruler detail on the opposite edge

#### Parameters

ruler | a GtkDataboxRuler |
invert | whether to draw the ruler detail with the edge inverted |

### gtk_databox_ruler_get_invert_edge ()

    gboolean
    gtk_databox_ruler_get_invert_edge (GtkDataboxRuler *ruler);

Gets the invert edge option from the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Edge inversion option of the `ruler` .

### gtk_databox_ruler_set_linear_label_format ()

    void
    gtk_databox_ruler_set_linear_label_format
                                   (GtkDataboxRuler *ruler,
                                    gchar *format);

Sets the meta `format` string for the labels of linear rulers, for example "%%+-`dg`" will become "%+-#g" where # is the int variable

#### Parameters

ruler | a GtkDataboxRuler |
format | How to format the labels for linear rulers |

### gtk_databox_ruler_set_log_label_format ()

    void
    gtk_databox_ruler_set_log_label_format
                                   (GtkDataboxRuler *ruler,
                                    gchar *format);

Sets the meta `format` string for the labels of log scaled rulers, for example "%%-`dg`" will become "%-#g" where # is the int variable

#### Parameters

ruler | a GtkDataboxRuler |
format | How to format the labels for log scaled rulers |

### gtk_databox_ruler_get_linear_label_format ()

    gchar *
    gtk_databox_ruler_get_linear_label_format
                                   (GtkDataboxRuler *ruler);

Gets the linear label meta format of the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

The string meta format the `ruler` NULL on failure.

### gtk_databox_ruler_get_log_label_format ()

    gchar *
    gtk_databox_ruler_get_log_label_format
                                   (GtkDataboxRuler *ruler);

Gets the log label meta format of the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

The string meta format the `ruler` , NULL on failure.

### gtk_databox_ruler_set_manual_ticks ()

    void
    gtk_databox_ruler_set_manual_ticks (GtkDataboxRuler *ruler,
                                        gfloat *manual_ticks);

Sets the ticks for the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |
manual_ticks | sets the pointer to the hline values for the `ruler` |

### gtk_databox_ruler_get_manual_ticks ()

    gfloat *
    gtk_databox_ruler_get_manual_ticks (GtkDataboxRuler *ruler);

Gets the pointer to the manual tick values for the `ruler` .

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Pointer to the manual tick values for the `ruler` .

### gtk_databox_ruler_set_manual_tick_cnt ()

    void
    gtk_databox_ruler_set_manual_tick_cnt (GtkDataboxRuler *ruler,
                                           guint manual_tick_cnt);

Sets the number of manual ticks for the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |
manual_tick_cnt | sets the number of manual ticks for the `ruler` |

### gtk_databox_ruler_get_manual_tick_cnt ()

    guint
    gtk_databox_ruler_get_manual_tick_cnt (GtkDataboxRuler *ruler);

Gets the number manual tick values for the `ruler` .

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

The number of manual tick values for the `ruler` .

### gtk_databox_ruler_set_manual_tick_labels ()

    void
    gtk_databox_ruler_set_manual_tick_labels
                                   (GtkDataboxRuler *ruler,
                                    gchar **manual_tick_labels);

Note: This function should be preceeded by calls to `gtk_databox_ruler_set_manual_ticks()` and `gtk_databox_ruler_set_manual_tick_cnt()`. The number of tick labels should match `gtk_databox_ruler_get_manual_tick_cnt()`.

Sets the tick labels of the `ruler` (horizontal or vertical).

#### Parameters

ruler | a GtkDataboxRuler |
manual_tick_labels | sets the pointer to the labels for the ticks on the `ruler` |

### gtk_databox_ruler_get_manual_tick_labels ()

    gchar **
    gtk_databox_ruler_get_manual_tick_labels
                                   (GtkDataboxRuler *ruler);

Gets the pointer to the manual tick labels for the `ruler` .

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

Pointer to the manual tick labels for the `ruler` .

### gtk_databox_ruler_set_box_shadow ()

    void
    gtk_databox_ruler_set_box_shadow (GtkDataboxRuler *ruler,
                                      GtkShadowType which_shadow);

Sets the shadow type when using gtk_paint_box. This will draw the desired edge shadow.

#### Parameters

ruler | a GtkDataboxRuler |
which_shadow | How to render the box shadow on the ruler edges. |

### gtk_databox_ruler_get_box_shadow ()

    GtkShadowType
    gtk_databox_ruler_get_box_shadow (GtkDataboxRuler *ruler);

Gets the type of shadow being rendered to the `ruler` (GTK_SHADOW_NONE, GTK_SHADOW_IN, GTK_SHADOW_OUT, GTK_SHADOW_ETCHED_IN, GTK_SHADOW_ETCHED_OUT).

#### Parameters

ruler | a GtkDataboxRuler |

#### Returns

The currently used shadow type of the `ruler` , -1 on failure.

## Types and Values

### struct GtkDataboxRuler

    struct GtkDataboxRuler;

An improved version (see above) of GtkRuler which supports linear and logarithmic scales.

### struct GtkDataboxRulerClass

    struct GtkDataboxRulerClass {
       GtkWidgetClass parent_class;
    };

The object class of GtkDataboxRuler.

### GtkDataboxRulerPrivate

    typedef struct _GtkDataboxRulerPrivate GtkDataboxRulerPrivate;

A private data structure used by the GtkDataboxRuler. It shields all internal things from developers who are just using the object.

### GTK_DATABOX_RULER_MAX_MAX_LENGTH

    #define GTK_DATABOX_RULER_MAX_MAX_LENGTH 63

The maximum upper limit of label length in characters

## Property Details

### The `“box-shadow”` property

      “box-shadow”               guint

Style of the box shadow: GTK_SHADOW_NONE, GTK_SHADOW_IN, GTK_SHADOW_OUT, GTK_SHADOW_ETCHED_IN, GTK_SHADOW_ETCHED_OUT.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 4

Default value: 2

### The `“draw-position”` property

      “draw-position”            guint

Draw the position arrows: true or false.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 1

Default value: 1

### The `“draw-subticks”` property

      “draw-subticks”            guint

Draw the subticks: true or false.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 1

Default value: 1

### The `“draw-ticks”` property

      “draw-ticks”               guint

Draw the Ticks: true or false.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 1

Default value: 1

### The `“invert-edge”` property

      “invert-edge”              guint

Invert the Edge - the edge is drawn inverted: true or false.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 1

Default value: 0

### The `“linear-label-format”` property

      “linear-label-format”      char *

Linear Label format mark up strings: marked up formatting strings for linear labels (i.e. "%%-+%dg").

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: "%%-+%dg"

### The `“log-label-format”` property

      “log-label-format”         char *

Log Label format mark up strings: marked up formatting strings for log labels (i.e. "%%-%dg").

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: "%%-%dg"

### The `“lower”` property

      “lower”                    double

Lower limit of ruler.

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: 0

### The `“manual-tick-cnt”` property

      “manual-tick-cnt”          guint

The number of manual ticks in the manual_tick array: horizontal or vertical.

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: 0

### The `“manual-tick-labels”` property

      “manual-tick-labels”       gpointer

Manually specify the tick labels.

Owner: GtkDataboxRuler

Flags: Read / Write

### The `“manual-ticks”` property

      “manual-ticks”             gpointer

Manually specify the tick locations.

Owner: GtkDataboxRuler

Flags: Read / Write

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

      “max-length”               guint

Maximum length of the labels (in digits).

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: [2,63]

Default value: 6

### The `“orientation”` property

      “orientation”              guint

Orientation of the ruler: horizontal or vertical.

Owner: GtkDataboxRuler

Flags: Read / Write / Construct Only

Allowed values: <= 1

Default value: 0

### The `“position”` property

      “position”                 double

Position of mark on the ruler.

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: 0

### The `“text-alignment”` property

      “text-alignment”           guint

Alignment of the tick mark text (on the vertical ruler when using horizonal text): { PANGO_ALIGN_LEFT, PANGO_ALIGN_CENTER, PANGO_ALIGN_RIGHT}.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 2

Default value: 0

### The `“text-hoffset”` property

      “text-hoffset”             guint

Move the tick mark text left or right : pixels.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 20

Default value: 0

### The `“text-orientation”` property

      “text-orientation”         guint

Orientation of the tick mark text (on the vertical ruler): horizontal or vertical.

Owner: GtkDataboxRuler

Flags: Read / Write

Allowed values: <= 1

Default value: 1

### The `“upper”` property

      “upper”                    double

Upper limit of ruler.

Owner: GtkDataboxRuler

Flags: Read / Write

Default value: 0

## See Also

GtkDatabox