gtkscale.sgml 4.03 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4 5 6 7 8
<!-- ##### SECTION Title ##### -->
GtkScale

<!-- ##### SECTION Short_Description ##### -->
a base class for #GtkHScale and #GtkVScale.

<!-- ##### SECTION Long_Description ##### -->
<para>
9 10 11 12 13 14 15 16
A #GtkScale is a slider control used to select a numeric value.
To use it, you'll probably want to investigate the methods on 
its base class, #GtkRange, in addition to the methods for #GtkScale itself.
To set the value of a scale, you would normally use gtk_range_set_value(). 
To detect changes to the value, you would normally use the "value_changed" 
signal.
</para>
<para>
Owen Taylor's avatar
Owen Taylor committed
17
The #GtkScale widget is an abstract class, used only for deriving the
18 19
subclasses #GtkHScale and #GtkVScale. To create a scale widget, 
call gtk_hscale_new_with_range() or gtk_vscale_new_with_range().
Owen Taylor's avatar
Owen Taylor committed
20 21 22 23 24 25 26 27 28 29 30 31 32
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT GtkScale ##### -->
<para>
The #GtkScale-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)

Matthias Clasen's avatar
Matthias Clasen committed
33 34
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
Owen Taylor's avatar
Owen Taylor committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
<tbody>

<row>
<entry>#guint <structfield>draw_value</structfield>;</entry>
<entry>non-zero if the scale's current value is displayed next to the
slider.</entry>
</row>

<row>
<entry>#guint <structfield>value_pos</structfield>;</entry>
<entry>the position in which the textual value is displayed, selected from
#GtkPositionType.</entry>
</row>

</tbody></tgroup></informaltable>
</para>


<!-- ##### FUNCTION gtk_scale_set_digits ##### -->
<para>
Havoc Pennington's avatar
Havoc Pennington committed
55 56 57
Sets the number of decimal places that are displayed in the value.  Also causes
the value of the adjustment to be rounded off to this number of digits, so the
retrieved value matches the value the user saw.
Owen Taylor's avatar
Owen Taylor committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71
</para>

@scale: a #GtkScale.
@digits: the number of decimal places to display, e.g. use 1 to display 1.0,
2 to display 1.00 etc.


<!-- ##### FUNCTION gtk_scale_set_draw_value ##### -->
<para>
Specifies whether the current value is displayed as a string next to the
slider.
</para>

@scale: a #GtkScale.
72
@draw_value: a boolean.
Owen Taylor's avatar
Owen Taylor committed
73 74 75 76 77 78 79 80 81 82 83


<!-- ##### FUNCTION gtk_scale_set_value_pos ##### -->
<para>
Sets the position in which the current value is displayed.
</para>

@scale: a #GtkScale.
@pos: the position in which the current value is displayed.


84 85
<!-- ##### FUNCTION gtk_scale_get_digits ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
86
Gets the number of decimal places that are displayed in the value.
87 88
</para>

Matthias Clasen's avatar
Matthias Clasen committed
89 90
@scale: a #GtkScale.
@Returns: the number of decimal places that are displayed.
91 92 93 94


<!-- ##### FUNCTION gtk_scale_get_draw_value ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
95 96
Returns whether the current value is displayed as a string next to the
slider.
97 98
</para>

Matthias Clasen's avatar
Matthias Clasen committed
99 100
@scale: a #GtkScale.
@Returns: whether the current value is displayed as a string.
101 102 103 104


<!-- ##### FUNCTION gtk_scale_get_value_pos ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
105
Gets the position in which the current value is displayed.
106 107
</para>

Matthias Clasen's avatar
Matthias Clasen committed
108 109
@scale: a #GtkScale.
@Returns: the position in which the current value is displayed.
110 111


Havoc Pennington's avatar
Havoc Pennington committed
112 113
<!-- ##### SIGNAL GtkScale::format-value ##### -->
<para>
114 115 116 117
Signal which allows you to change how the scale value is displayed.  Connect a
signal handler which returns an allocated string representing @value.
That string will then be used to display the scale's value.
Here's an example signal handler which displays a value 1.0 as
Matthias Clasen's avatar
Matthias Clasen committed
118
with "--&gt;1.0&lt;--".
Matthias Clasen's avatar
Matthias Clasen committed
119
<informalexample><programlisting>
120 121 122 123
static gchar*
format_value_callback (GtkScale *scale,
                       gdouble   value)
{
124
  return g_strdup_printf ("--&gt;&percnt;0.*g&lt;--",
125 126
                          gtk_scale_get_digits (scale), value);
}
Matthias Clasen's avatar
Matthias Clasen committed
127
</programlisting></informalexample>
Havoc Pennington's avatar
Havoc Pennington committed
128 129 130
</para>

@scale: the object which received the signal.
131
@arg1: 
132
@Returns: allocated string representing @value
133 134
<!-- # Unused Parameters # -->
@value: value to format
Havoc Pennington's avatar
Havoc Pennington committed
135

Owen Taylor's avatar
Owen Taylor committed
136 137
<!-- ##### ARG GtkScale:digits ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
138

Owen Taylor's avatar
Owen Taylor committed
139 140
</para>

Owen Taylor's avatar
Owen Taylor committed
141
<!-- ##### ARG GtkScale:draw-value ##### -->
Owen Taylor's avatar
Owen Taylor committed
142
<para>
Matthias Clasen's avatar
Matthias Clasen committed
143

Owen Taylor's avatar
Owen Taylor committed
144 145
</para>

Owen Taylor's avatar
Owen Taylor committed
146
<!-- ##### ARG GtkScale:value-pos ##### -->
Owen Taylor's avatar
Owen Taylor committed
147
<para>
Matthias Clasen's avatar
Matthias Clasen committed
148

Owen Taylor's avatar
Owen Taylor committed
149 150
</para>

Owen Taylor's avatar
Owen Taylor committed
151
<!-- ##### ARG GtkScale:slider-length ##### -->
152 153 154 155
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
156
<!-- ##### ARG GtkScale:value-spacing ##### -->
157 158 159 160
<para>

</para>