<refentry id="GtkDial" revision="20 Jun 2000">
<refmeta>
<refentrytitle>GtkDial</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOMEUI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkDial</refname><refpurpose>Analog dial widget for number selection.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gnome.h&gt;


struct      <link linkend="GtkDial-struct">GtkDial</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gtk-dial-new">gtk_dial_new</link>                    (<link linkend="GtkAdjustment">GtkAdjustment</link> *adjustment);
<link linkend="GtkAdjustment">GtkAdjustment</link>* <link linkend="gtk-dial-get-adjustment">gtk_dial_get_adjustment</link>      (<link linkend="GtkDial">GtkDial</link> *dial);
void        <link linkend="gtk-dial-set-update-policy">gtk_dial_set_update_policy</link>      (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="GtkUpdateType">GtkUpdateType</link> policy);
void        <link linkend="gtk-dial-set-adjustment">gtk_dial_set_adjustment</link>         (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="GtkAdjustment">GtkAdjustment</link> *adjustment);
<link linkend="gfloat">gfloat</link>      <link linkend="gtk-dial-set-percentage">gtk_dial_set_percentage</link>         (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gfloat">gfloat</link> percent);
<link linkend="gfloat">gfloat</link>      <link linkend="gtk-dial-get-percentage">gtk_dial_get_percentage</link>         (<link linkend="GtkDial">GtkDial</link> *dial);
<link linkend="gfloat">gfloat</link>      <link linkend="gtk-dial-set-value">gtk_dial_set_value</link>              (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gfloat">gfloat</link> value);
<link linkend="gfloat">gfloat</link>      <link linkend="gtk-dial-get-value">gtk_dial_get_value</link>              (<link linkend="GtkDial">GtkDial</link> *dial);
void        <link linkend="gtk-dial-set-view-only">gtk_dial_set_view_only</link>          (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gboolean">gboolean</link> view_only);

</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GtkObject">GtkObject</link>
   +----<link linkend="GtkWidget">GtkWidget</link>
         +----GtkDial
</synopsis>

</refsect1>




<refsect1>
<title>Description</title>
<para>
This widget provides an analog dial widget, similar to, for example, a
physical volume control on a stereo. Dial values can be changable or
read-only for value reporting.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkDial-struct">struct GtkDial</title>
<programlisting>struct GtkDial;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gtk-dial-new">gtk_dial_new ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gtk_dial_new                    (<link linkend="GtkAdjustment">GtkAdjustment</link> *adjustment);</programlisting>
<para>
This function creates a new GtkDial widget, and ties it to a
specified GtkAdjustment. When the dial is moved, the adjustment is
updated, and vice-versa.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>adjustment</parameter>&nbsp;:</entry>
<entry> Pointer to GtkAdjustment object
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Pointer to new GtkDial widget.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-get-adjustment">gtk_dial_get_adjustment ()</title>
<programlisting><link linkend="GtkAdjustment">GtkAdjustment</link>* gtk_dial_get_adjustment      (<link linkend="GtkDial">GtkDial</link> *dial);</programlisting>
<para>
Retrieves the GtkAdjustment associated with the
GtkDial <parameter>dial</parameter>.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Pointer to GtkAdjustment object.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-set-update-policy">gtk_dial_set_update_policy ()</title>
<programlisting>void        gtk_dial_set_update_policy      (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="GtkUpdateType">GtkUpdateType</link> policy);</programlisting>
<para>
Sets the update policy of the GtkDial <parameter>dial</parameter> to one of either
<literal>GTK_UPDATE_CONTINUOUS</literal>, <literal>GTK_UPDATE_DISCONTINUOUS</literal>, or
<literal>GTK_UPDATE_DELAYED</literal>. Please see Gtk+ documentation for an
explanation of these values.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><parameter>policy</parameter>&nbsp;:</entry>
<entry> New policy type
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-set-adjustment">gtk_dial_set_adjustment ()</title>
<programlisting>void        gtk_dial_set_adjustment         (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="GtkAdjustment">GtkAdjustment</link> *adjustment);</programlisting>
<para>
Associates a new GtkAdjustment with GtkDial <parameter>dial</parameter>
widget. The old adjustment is removed and replaced with the new.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><parameter>adjustment</parameter>&nbsp;:</entry>
<entry> Pointer to GtkAdjustment object
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-set-percentage">gtk_dial_set_percentage ()</title>
<programlisting><link linkend="gfloat">gfloat</link>      gtk_dial_set_percentage         (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gfloat">gfloat</link> percent);</programlisting>
<para>
Sets the GtkDial's value to <parameter>percent</parameter> of
<parameter>dial</parameter>-&gt;adjustment-&gt;upper. The upper value is set when the
GtkAdjustment is created.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><parameter>percent</parameter>&nbsp;:</entry>
<entry> New percentage
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> New value of adjustment.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-get-percentage">gtk_dial_get_percentage ()</title>
<programlisting><link linkend="gfloat">gfloat</link>      gtk_dial_get_percentage         (<link linkend="GtkDial">GtkDial</link> *dial);</programlisting>
<para>
Retrieves the current percentage held in the dial widget.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Current percentage.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-set-value">gtk_dial_set_value ()</title>
<programlisting><link linkend="gfloat">gfloat</link>      gtk_dial_set_value              (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gfloat">gfloat</link> value);</programlisting>
<para>
Sets the current value held in the GtkDial's
adjustment object to <parameter>value</parameter>.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> New value
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> New percentage of value to the adjustment's upper limit.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-get-value">gtk_dial_get_value ()</title>
<programlisting><link linkend="gfloat">gfloat</link>      gtk_dial_get_value              (<link linkend="GtkDial">GtkDial</link> *dial);</programlisting>
<para>
Retrieves the current value helt in the dial widget.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Current value
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-dial-set-view-only">gtk_dial_set_view_only ()</title>
<programlisting>void        gtk_dial_set_view_only          (<link linkend="GtkDial">GtkDial</link> *dial,
                                             <link linkend="gboolean">gboolean</link> view_only);</programlisting>
<para>
Specifies whether or not the user is to be able to
edit the value represented by the dial widget. If <parameter>view_only</parameter> is
TRUE, the dial will be set to view-only mode, and the user will not 
be able to edit it. If <parameter>view_only</parameter> is FALSE, the user will be able
to change the value represented.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dial</parameter>&nbsp;:</entry>
<entry> Pointer to GtkDial widget
</entry></row>
<row><entry align="right"><parameter>view_only</parameter>&nbsp;:</entry>
<entry> TRUE to set dial to read-only, FALSE to edit.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<link linkend="GnomeNumberEntry">GnomeNumberEntry</link>
</para>
</refsect1>

</refentry>
