<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="GtkRuler">
<refmeta>
<refentrytitle role="top_of_page" id="GtkRuler.top_of_page">GtkRuler</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkRuler</refname>
<refpurpose>Base class for horizontal or vertical rulers</refpurpose>
</refnamediv>

<refsynopsisdiv id="GtkRuler.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gtk/gtk.h&gt;

                    <link linkend="GtkRuler-struct">GtkRuler</link>;
                    <link linkend="GtkRulerMetric">GtkRulerMetric</link>;
<link linkend="void">void</link>                <link linkend="gtk-ruler-set-metric">gtk_ruler_set_metric</link>                (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="GtkMetricType">GtkMetricType</link> metric);
<link linkend="void">void</link>                <link linkend="gtk-ruler-set-range">gtk_ruler_set_range</link>                 (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="gdouble">gdouble</link> lower,
                                                         <link linkend="gdouble">gdouble</link> upper,
                                                         <link linkend="gdouble">gdouble</link> position,
                                                         <link linkend="gdouble">gdouble</link> max_size);
<link linkend="GtkMetricType">GtkMetricType</link>       <link linkend="gtk-ruler-get-metric">gtk_ruler_get_metric</link>                (<link linkend="GtkRuler">GtkRuler</link> *ruler);
<link linkend="void">void</link>                <link linkend="gtk-ruler-get-range">gtk_ruler_get_range</link>                 (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="gdouble">gdouble</link> *lower,
                                                         <link linkend="gdouble">gdouble</link> *upper,
                                                         <link linkend="gdouble">gdouble</link> *position,
                                                         <link linkend="gdouble">gdouble</link> *max_size);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkRuler.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
         +----<link linkend="GtkObject">GtkObject</link>
               +----<link linkend="GtkWidget">GtkWidget</link>
                     +----GtkRuler
                           +----<link linkend="GtkHRuler">GtkHRuler</link>
                           +----<link linkend="GtkVRuler">GtkVRuler</link>
</synopsis>
</refsect1>



<refsect1 id="GtkRuler.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkRuler implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link> and  <link linkend="GtkOrientable">GtkOrientable</link>.</para>
</refsect1>


<refsect1 id="GtkRuler.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="GtkRuler--lower">lower</link>&quot;                    <link linkend="gdouble">gdouble</link>               : Read / Write
  &quot;<link linkend="GtkRuler--max-size">max-size</link>&quot;                 <link linkend="gdouble">gdouble</link>               : Read / Write
  &quot;<link linkend="GtkRuler--metric">metric</link>&quot;                   <link linkend="GtkMetricType">GtkMetricType</link>         : Read / Write
  &quot;<link linkend="GtkRuler--position">position</link>&quot;                 <link linkend="gdouble">gdouble</link>               : Read / Write
  &quot;<link linkend="GtkRuler--upper">upper</link>&quot;                    <link linkend="gdouble">gdouble</link>               : Read / Write
</synopsis>
</refsect1>



<refsect1 id="GtkRuler.description" role="desc">
<title role="desc.title">Description</title>
<note>
<para>
 This widget is considered too specialized/little-used for
 GTK+, and will in the future be moved to some other package.  If
 your application needs this widget, feel free to use it, as the
 widget does work and is useful in some applications; it's just not
 of general interest. However, we are not accepting new features for
 the widget, and it will eventually move out of the GTK+
 distribution.
</para>
</note>
<para>
The GTKRuler widget is a base class for horizontal and vertical rulers. Rulers
are used to show the mouse pointer's location in a window. The ruler can either
be horizontal or vertical on the window. Within the ruler a small triangle
indicates the location of the mouse relative to the horizontal or vertical
ruler. See <link linkend="GtkHRuler"><type>GtkHRuler</type></link> to learn how to create a new horizontal ruler. See
<link linkend="GtkVRuler"><type>GtkVRuler</type></link> to learn how to create a new vertical ruler.
</para>
</refsect1>

<refsect1 id="GtkRuler.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkRuler-struct" role="struct">
<title>GtkRuler</title>
<indexterm zone="GtkRuler-struct"><primary sortas="Ruler">GtkRuler</primary></indexterm><programlisting>typedef struct _GtkRuler GtkRuler;</programlisting>
<para>
All distances are in 1/72nd's of an inch. (According to Adobe thats a point, but
points are really 1/72.27 in.)
</para></refsect2>
<refsect2 id="GtkRulerMetric" role="struct">
<title>GtkRulerMetric</title>
<indexterm zone="GtkRulerMetric"><primary sortas="RulerMetric">GtkRulerMetric</primary></indexterm><programlisting>typedef struct {
  gchar *metric_name;
  gchar *abbrev;
  /* This should be points_per_unit. This is the size of the unit
   * in 1/72nd's of an inch and has nothing to do with screen pixels */
  gdouble pixels_per_unit;
  gdouble ruler_scale[10];
  gint subdivide[5];        /* five possible modes of subdivision */
} GtkRulerMetric;
</programlisting>
<para>
This should be points_per_unit. This is the size of the unit in 1/72nd's of an inch and has nothing to do with screen pixels.
</para></refsect2>
<refsect2 id="gtk-ruler-set-metric" role="function">
<title>gtk_ruler_set_metric ()</title>
<indexterm zone="gtk-ruler-set-metric"><primary sortas="ruler_set_metric">gtk_ruler_set_metric</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_ruler_set_metric                (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="GtkMetricType">GtkMetricType</link> metric);</programlisting>
<para>
This calls the <link linkend="GTKMetricType"><type>GTKMetricType</type></link> to set the ruler to units defined. Available units
are GTK_PIXELS, GTK_INCHES, or GTK_CENTIMETERS. The default unit of measurement
is GTK_PIXELS.
</para><variablelist role="params">
<varlistentry><term><parameter>ruler</parameter>&#160;:</term>
<listitem><simpara>the gtkruler
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>metric</parameter>&#160;:</term>
<listitem><simpara>the unit of measurement
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-ruler-set-range" role="function">
<title>gtk_ruler_set_range ()</title>
<indexterm zone="gtk-ruler-set-range"><primary sortas="ruler_set_range">gtk_ruler_set_range</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_ruler_set_range                 (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="gdouble">gdouble</link> lower,
                                                         <link linkend="gdouble">gdouble</link> upper,
                                                         <link linkend="gdouble">gdouble</link> position,
                                                         <link linkend="gdouble">gdouble</link> max_size);</programlisting>
<para>
This sets the range of the ruler.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ruler</parameter>&#160;:</term>
<listitem><simpara> the gtkruler
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>lower</parameter>&#160;:</term>
<listitem><simpara> the lower limit of the ruler
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>upper</parameter>&#160;:</term>
<listitem><simpara> the upper limit of the ruler
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>position</parameter>&#160;:</term>
<listitem><simpara> the mark on the ruler
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_size</parameter>&#160;:</term>
<listitem><simpara> the maximum size of the ruler used when calculating the space to
leave for the text
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-ruler-get-metric" role="function">
<title>gtk_ruler_get_metric ()</title>
<indexterm zone="gtk-ruler-get-metric"><primary sortas="ruler_get_metric">gtk_ruler_get_metric</primary></indexterm><programlisting><link linkend="GtkMetricType">GtkMetricType</link>       gtk_ruler_get_metric                (<link linkend="GtkRuler">GtkRuler</link> *ruler);</programlisting>
<para>
Gets the units used for a <link linkend="GtkRuler"><type>GtkRuler</type></link>. See <link linkend="gtk-ruler-set-metric"><function>gtk_ruler_set_metric()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ruler</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkRuler"><type>GtkRuler</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the units currently used for <parameter>ruler</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-ruler-get-range" role="function">
<title>gtk_ruler_get_range ()</title>
<indexterm zone="gtk-ruler-get-range"><primary sortas="ruler_get_range">gtk_ruler_get_range</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_ruler_get_range                 (<link linkend="GtkRuler">GtkRuler</link> *ruler,
                                                         <link linkend="gdouble">gdouble</link> *lower,
                                                         <link linkend="gdouble">gdouble</link> *upper,
                                                         <link linkend="gdouble">gdouble</link> *position,
                                                         <link linkend="gdouble">gdouble</link> *max_size);</programlisting>
<para>
Retrieves values indicating the range and current position of a <link linkend="GtkRuler"><type>GtkRuler</type></link>.
See <link linkend="gtk-ruler-set-range"><function>gtk_ruler_set_range()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ruler</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkRuler"><type>GtkRuler</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>lower</parameter>&#160;:</term>
<listitem><simpara> location to store lower limit of the ruler, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>upper</parameter>&#160;:</term>
<listitem><simpara> location to store upper limit of the ruler, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>position</parameter>&#160;:</term>
<listitem><simpara> location to store the current position of the mark on the ruler, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_size</parameter>&#160;:</term>
<listitem><simpara> location to store the maximum size of the ruler used when calculating
           the space to leave for the text, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1 id="GtkRuler.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkRuler--lower" role="property"><title>The <literal>&quot;lower&quot;</literal> property</title>
<indexterm zone="GtkRuler--lower"><primary sortas="Ruler:lower">GtkRuler:lower</primary></indexterm><programlisting>  &quot;lower&quot;                    <link linkend="gdouble">gdouble</link>               : Read / Write</programlisting>
<para>Lower limit of ruler.</para><para>Default value: 0</para>
</refsect2>
<refsect2 id="GtkRuler--max-size" role="property"><title>The <literal>&quot;max-size&quot;</literal> property</title>
<indexterm zone="GtkRuler--max-size"><primary sortas="Ruler:max-size">GtkRuler:max-size</primary></indexterm><programlisting>  &quot;max-size&quot;                 <link linkend="gdouble">gdouble</link>               : Read / Write</programlisting>
<para>Maximum size of the ruler.</para><para>Default value: 0</para>
</refsect2>
<refsect2 id="GtkRuler--metric" role="property"><title>The <literal>&quot;metric&quot;</literal> property</title>
<indexterm zone="GtkRuler--metric" role="2.8"><primary sortas="Ruler:metric">GtkRuler:metric</primary></indexterm><programlisting>  &quot;metric&quot;                   <link linkend="GtkMetricType">GtkMetricType</link>         : Read / Write</programlisting>
<para>
The metric used for the ruler.</para>
<para>
</para><para>Default value: GTK_PIXELS</para>
<para>Since 2.8</para>
</refsect2>
<refsect2 id="GtkRuler--position" role="property"><title>The <literal>&quot;position&quot;</literal> property</title>
<indexterm zone="GtkRuler--position"><primary sortas="Ruler:position">GtkRuler:position</primary></indexterm><programlisting>  &quot;position&quot;                 <link linkend="gdouble">gdouble</link>               : Read / Write</programlisting>
<para>Position of mark on the ruler.</para><para>Default value: 0</para>
</refsect2>
<refsect2 id="GtkRuler--upper" role="property"><title>The <literal>&quot;upper&quot;</literal> property</title>
<indexterm zone="GtkRuler--upper"><primary sortas="Ruler:upper">GtkRuler:upper</primary></indexterm><programlisting>  &quot;upper&quot;                    <link linkend="gdouble">gdouble</link>               : Read / Write</programlisting>
<para>Upper limit of ruler.</para><para>Default value: 0</para>
</refsect2>
</refsect1>



<refsect1 id="GtkRuler.see-also">
<title>See Also</title>
<para>
<link linkend="GtkHRuler"><type>GtkHRuler</type></link>, <link linkend="GtkVRuler"><type>GtkVRuler</type></link>
</para>
</refsect1>

</refentry>
