1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5
<refentry id="GimpSizeEntry">
7
<refentrytitle>GimpSizeEntry</refentrytitle>
8
<manvolnum>3</manvolnum>
9
<refmiscinfo>LIBGIMPWIDGETS Library</refmiscinfo>
13
<refname>GimpSizeEntry</refname><refpurpose>Widget for entering pixel values and resolutions.</refpurpose>
16
<refsynopsisdiv><title>Synopsis</title>
22
<link linkend="GimpSizeEntry-struct">GimpSizeEntry</link>;
23
<link linkend="GimpSizeEntryField">GimpSizeEntryField</link>;
24
enum <link linkend="GimpSizeEntryUpdatePolicy">GimpSizeEntryUpdatePolicy</link>;
25
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gimp-size-entry-new">gimp_size_entry_new</link> (<link linkend="gint">gint</link> number_of_fields,
26
<link linkend="GimpUnit">GimpUnit</link> unit,
27
const <link linkend="gchar">gchar</link> *unit_format,
28
<link linkend="gboolean">gboolean</link> menu_show_pixels,
29
<link linkend="gboolean">gboolean</link> menu_show_percent,
30
<link linkend="gboolean">gboolean</link> show_refval,
31
<link linkend="gint">gint</link> spinbutton_width,
32
<link linkend="GimpSizeEntryUpdatePolicy">GimpSizeEntryUpdatePolicy</link> update_policy);
33
<link linkend="void">void</link> <link linkend="gimp-size-entry-add-field">gimp_size_entry_add_field</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
34
<link linkend="GtkSpinButton">GtkSpinButton</link> *value_spinbutton,
35
<link linkend="GtkSpinButton">GtkSpinButton</link> *refval_spinbutton);
36
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gimp-size-entry-attach-label">gimp_size_entry_attach_label</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
37
const <link linkend="gchar">gchar</link> *text,
38
<link linkend="gint">gint</link> row,
39
<link linkend="gint">gint</link> column,
40
<link linkend="gfloat">gfloat</link> alignment);
41
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-resolution">gimp_size_entry_set_resolution</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
42
<link linkend="gint">gint</link> field,
43
<link linkend="gdouble">gdouble</link> resolution,
44
<link linkend="gboolean">gboolean</link> keep_size);
45
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-size">gimp_size_entry_set_size</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
46
<link linkend="gint">gint</link> field,
47
<link linkend="gdouble">gdouble</link> lower,
48
<link linkend="gdouble">gdouble</link> upper);
49
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-value-boundaries">gimp_size_entry_set_value_boundaries</link>
50
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
51
<link linkend="gint">gint</link> field,
52
<link linkend="gdouble">gdouble</link> lower,
53
<link linkend="gdouble">gdouble</link> upper);
54
<link linkend="gdouble">gdouble</link> <link linkend="gimp-size-entry-get-value">gimp_size_entry_get_value</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
55
<link linkend="gint">gint</link> field);
56
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-value">gimp_size_entry_set_value</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
57
<link linkend="gint">gint</link> field,
58
<link linkend="gdouble">gdouble</link> value);
59
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-refval-boundaries">gimp_size_entry_set_refval_boundaries</link>
60
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
61
<link linkend="gint">gint</link> field,
62
<link linkend="gdouble">gdouble</link> lower,
63
<link linkend="gdouble">gdouble</link> upper);
64
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-refval-digits">gimp_size_entry_set_refval_digits</link>
65
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
66
<link linkend="gint">gint</link> field,
67
<link linkend="gint">gint</link> digits);
68
<link linkend="gdouble">gdouble</link> <link linkend="gimp-size-entry-get-refval">gimp_size_entry_get_refval</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
69
<link linkend="gint">gint</link> field);
70
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-refval">gimp_size_entry_set_refval</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
71
<link linkend="gint">gint</link> field,
72
<link linkend="gdouble">gdouble</link> refval);
73
<link linkend="GimpUnit">GimpUnit</link> <link linkend="gimp-size-entry-get-unit">gimp_size_entry_get_unit</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse);
74
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-unit">gimp_size_entry_set_unit</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
75
<link linkend="GimpUnit">GimpUnit</link> unit);
76
<link linkend="void">void</link> <link linkend="gimp-size-entry-set-pixel-digits">gimp_size_entry_set_pixel_digits</link>
77
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
78
<link linkend="gint">gint</link> digits);
79
<link linkend="void">void</link> <link linkend="gimp-size-entry-grab-focus">gimp_size_entry_grab_focus</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse);
80
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gimp-size-entry-get-help-widget">gimp_size_entry_get_help_widget</link> (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
81
<link linkend="gint">gint</link> field);
87
<title>Object Hierarchy</title>
90
<link linkend="GObject">GObject</link>
91
+----<link linkend="GtkObject">GtkObject</link>
92
+----<link linkend="GtkWidget">GtkWidget</link>
93
+----<link linkend="GtkContainer">GtkContainer</link>
94
+----<link linkend="GtkTable">GtkTable</link>
103
<title>Implemented Interfaces</title>
105
GimpSizeEntry implements
106
<link linkend="AtkImplementorIface">AtkImplementorIface</link>.</para>
113
<title>Signal Prototypes</title>
116
"<link linkend="GimpSizeEntry-refval-changed">refval-changed</link>"
117
<link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
118
<link linkend="gpointer">gpointer</link> user_data);
119
"<link linkend="GimpSizeEntry-unit-changed">unit-changed</link>"
120
<link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
121
<link linkend="gpointer">gpointer</link> user_data);
122
"<link linkend="GimpSizeEntry-value-changed">value-changed</link>"
123
<link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
124
<link linkend="gpointer">gpointer</link> user_data);
130
<title>Description</title>
132
This widget is used to enter pixel distances/sizes and resolutions.
135
You can specify the number of fields the widget should provide. For
136
each field automatic mappings are performed between the field's
137
"reference value" and it's "value".
140
There is a <link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link> right of the entry fields which lets you
141
specify the <link linkend="GimpUnit"><type>GimpUnit</type></link> of the displayed values.
144
For each field, there can be one or two <link linkend="GtkSpinButton"><type>GtkSpinButton</type></link>'s to enter
145
"value" and "reference value". If you specify <parameter>show_refval</parameter> as <link linkend="FALSE:CAPS"><type>FALSE</type></link>
146
in <link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link> there will be only one <link linkend="GtkSpinButton"><type>GtkSpinButton</type></link> and the
147
<link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link> will contain an item for selecting GIMP_UNIT_PIXEL.
150
The "reference value" is either of GIMP_UNIT_PIXEL or dpi, depending
151
on which <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> you specify in <link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link>.
152
The "value" is either the size in pixels mapped to the size in a
153
real-world-unit (see <link linkend="GimpUnit"><type>GimpUnit</type></link>) or the dpi value mapped to pixels per
159
<title>Details</title>
161
<title><anchor id="GimpSizeEntry-struct"/>GimpSizeEntry</title>
162
<indexterm><primary>GimpSizeEntry</primary></indexterm><programlisting>typedef struct _GimpSizeEntry GimpSizeEntry;</programlisting>
167
<title><anchor id="GimpSizeEntryField"/>GimpSizeEntryField</title>
168
<indexterm><primary>GimpSizeEntryField</primary></indexterm><programlisting>typedef struct _GimpSizeEntryField GimpSizeEntryField;</programlisting>
173
<title><anchor id="GimpSizeEntryUpdatePolicy"/>enum GimpSizeEntryUpdatePolicy</title>
174
<indexterm><primary>GimpSizeEntryUpdatePolicy</primary></indexterm><programlisting>typedef enum
176
GIMP_SIZE_ENTRY_UPDATE_NONE = 0,
177
GIMP_SIZE_ENTRY_UPDATE_SIZE = 1,
178
GIMP_SIZE_ENTRY_UPDATE_RESOLUTION = 2
179
} GimpSizeEntryUpdatePolicy;
185
<title><anchor id="gimp-size-entry-new"/>gimp_size_entry_new ()</title>
186
<indexterm><primary>gimp_size_entry_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gimp_size_entry_new (<link linkend="gint">gint</link> number_of_fields,
187
<link linkend="GimpUnit">GimpUnit</link> unit,
188
const <link linkend="gchar">gchar</link> *unit_format,
189
<link linkend="gboolean">gboolean</link> menu_show_pixels,
190
<link linkend="gboolean">gboolean</link> menu_show_percent,
191
<link linkend="gboolean">gboolean</link> show_refval,
192
<link linkend="gint">gint</link> spinbutton_width,
193
<link linkend="GimpSizeEntryUpdatePolicy">GimpSizeEntryUpdatePolicy</link> update_policy);</programlisting>
195
Creates a new <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> widget.
198
To have all automatic calculations performed correctly, set up the
199
widget in the following order:
202
1. <link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link>
205
2. (for each additional input field) <link linkend="gimp-size-entry-add-field"><function>gimp_size_entry_add_field()</function></link>
208
3. <link linkend="gimp-size-entry-set-unit"><function>gimp_size_entry_set_unit()</function></link>
211
For each input field:
214
4. <link linkend="gimp-size-entry-set-resolution"><function>gimp_size_entry_set_resolution()</function></link>
217
5. <link linkend="gimp-size-entry-set-refval-boundaries"><function>gimp_size_entry_set_refval_boundaries()</function></link>
218
(or <link linkend="gimp-size-entry-set-value-boundaries"><function>gimp_size_entry_set_value_boundaries()</function></link>)
221
6. <link linkend="gimp-size-entry-set-size"><function>gimp_size_entry_set_size()</function></link>
224
7. <link linkend="gimp-size-entry-set-refval"><function>gimp_size_entry_set_refval()</function></link> (or <link linkend="gimp-size-entry-set-value"><function>gimp_size_entry_set_value()</function></link>)
227
The <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> is derived from <link linkend="GtkTable"><type>GtkTable</type></link> and will have
228
an empty border of one cell width on each side plus an empty column left
229
of the <link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link> to allow the caller to add labels or a
230
<link linkend="GimpChainButton"><type>GimpChainButton</type></link>.</para>
233
</para><variablelist role="params">
234
<varlistentry><term><parameter>number_of_fields</parameter> :</term>
235
<listitem><simpara> The number of input fields.
236
</simpara></listitem></varlistentry>
237
<varlistentry><term><parameter>unit</parameter> :</term>
238
<listitem><simpara> The initial unit.
239
</simpara></listitem></varlistentry>
240
<varlistentry><term><parameter>unit_format</parameter> :</term>
241
<listitem><simpara> A printf-like unit-format string as is used with
242
<link linkend="gimp-unit-menu-new"><function>gimp_unit_menu_new()</function></link>.
243
</simpara></listitem></varlistentry>
244
<varlistentry><term><parameter>menu_show_pixels</parameter> :</term>
245
<listitem><simpara> <literal>TRUE</literal> if the unit menu shold contain an item for
246
GIMP_UNIT_PIXEL (ignored if the <parameter>update_policy</parameter> is not
247
GIMP_SIZE_ENTRY_UPDATE_NONE).
248
</simpara></listitem></varlistentry>
249
<varlistentry><term><parameter>menu_show_percent</parameter> :</term>
250
<listitem><simpara> <literal>TRUE</literal> if the unit menu shold contain an item for
252
</simpara></listitem></varlistentry>
253
<varlistentry><term><parameter>show_refval</parameter> :</term>
254
<listitem><simpara> <literal>TRUE</literal> if you want an extra "reference value"
255
spinbutton per input field.
256
</simpara></listitem></varlistentry>
257
<varlistentry><term><parameter>spinbutton_width</parameter> :</term>
258
<listitem><simpara> The minimal horizontal size of the <link linkend="GtkSpinButton"><type>GtkSpinButton</type></link>'s.
259
</simpara></listitem></varlistentry>
260
<varlistentry><term><parameter>update_policy</parameter> :</term>
261
<listitem><simpara> How the automatic pixel <-> real-world-unit
262
calculations should be done.
263
</simpara></listitem></varlistentry>
264
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A Pointer to the new <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> widget.
265
</simpara></listitem></varlistentry>
266
</variablelist></refsect2>
268
<title><anchor id="gimp-size-entry-add-field"/>gimp_size_entry_add_field ()</title>
269
<indexterm><primary>gimp_size_entry_add_field</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_add_field (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
270
<link linkend="GtkSpinButton">GtkSpinButton</link> *value_spinbutton,
271
<link linkend="GtkSpinButton">GtkSpinButton</link> *refval_spinbutton);</programlisting>
273
Adds an input field to the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
276
The new input field will have the index 0. If you specified <parameter>show_refval</parameter>
277
as <literal>TRUE</literal> in <link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link> you have to pass an additional
278
<link linkend="GtkSpinButton"><type>GtkSpinButton</type></link> to hold the reference value. If <parameter>show_refval</parameter> was <literal>FALSE</literal>,
279
<parameter>refval_spinbutton</parameter> will be ignored.</para>
282
</para><variablelist role="params">
283
<varlistentry><term><parameter>gse</parameter> :</term>
284
<listitem><simpara> The sizeentry you want to add a field to.
285
</simpara></listitem></varlistentry>
286
<varlistentry><term><parameter>value_spinbutton</parameter> :</term>
287
<listitem><simpara> The spinbutton to display the field's value.
288
</simpara></listitem></varlistentry>
289
<varlistentry><term><parameter>refval_spinbutton</parameter> :</term>
290
<listitem><simpara> The spinbutton to display the field's reference value.
291
</simpara></listitem></varlistentry>
292
</variablelist></refsect2>
294
<title><anchor id="gimp-size-entry-attach-label"/>gimp_size_entry_attach_label ()</title>
295
<indexterm><primary>gimp_size_entry_attach_label</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gimp_size_entry_attach_label (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
296
const <link linkend="gchar">gchar</link> *text,
297
<link linkend="gint">gint</link> row,
298
<link linkend="gint">gint</link> column,
299
<link linkend="gfloat">gfloat</link> alignment);</programlisting>
301
Attaches a <link linkend="GtkLabel"><type>GtkLabel</type></link> to the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> (which is a <link linkend="GtkTable"><type>GtkTable</type></link>).</para>
304
</para><variablelist role="params">
305
<varlistentry><term><parameter>gse</parameter> :</term>
306
<listitem><simpara> The sizeentry you want to add a label to.
307
</simpara></listitem></varlistentry>
308
<varlistentry><term><parameter>text</parameter> :</term>
309
<listitem><simpara> The text of the label.
310
</simpara></listitem></varlistentry>
311
<varlistentry><term><parameter>row</parameter> :</term>
312
<listitem><simpara> The row where the label will be attached.
313
</simpara></listitem></varlistentry>
314
<varlistentry><term><parameter>column</parameter> :</term>
315
<listitem><simpara> The column where the label will be attached.
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><parameter>alignment</parameter> :</term>
318
<listitem><simpara> The horizontal alignment of the label.
319
</simpara></listitem></varlistentry>
320
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A pointer to the new <link linkend="GtkLabel"><type>GtkLabel</type></link> widget.
321
</simpara></listitem></varlistentry>
322
</variablelist></refsect2>
324
<title><anchor id="gimp-size-entry-set-resolution"/>gimp_size_entry_set_resolution ()</title>
325
<indexterm><primary>gimp_size_entry_set_resolution</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_resolution (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
326
<link linkend="gint">gint</link> field,
327
<link linkend="gdouble">gdouble</link> resolution,
328
<link linkend="gboolean">gboolean</link> keep_size);</programlisting>
330
Sets the resolution (in dpi) for field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
333
The <parameter>resolution</parameter> passed will be clamped to fit in
334
[<link linkend="GIMP-MIN-RESOLUTION:CAPS"><type>GIMP_MIN_RESOLUTION</type></link>..<link linkend="GIMP-MAX-RESOLUTION:CAPS"><type>GIMP_MAX_RESOLUTION</type></link>].
337
This function does nothing if the <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> specified in
338
<link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link> doesn't equal to <link linkend="GIMP-SIZE-ENTRY-UPDATE-SIZE:CAPS"><type>GIMP_SIZE_ENTRY_UPDATE_SIZE</type></link>.</para>
341
</para><variablelist role="params">
342
<varlistentry><term><parameter>gse</parameter> :</term>
343
<listitem><simpara> The sizeentry you want to set a resolution for.
344
</simpara></listitem></varlistentry>
345
<varlistentry><term><parameter>field</parameter> :</term>
346
<listitem><simpara> The index of the field you want to set the resolution for.
347
</simpara></listitem></varlistentry>
348
<varlistentry><term><parameter>resolution</parameter> :</term>
349
<listitem><simpara> The new resolution (in dpi) for the chosen <parameter>field</parameter>.
350
</simpara></listitem></varlistentry>
351
<varlistentry><term><parameter>keep_size</parameter> :</term>
352
<listitem><simpara> <literal>TRUE</literal> if the <parameter>field</parameter>'s size in pixels should stay the same.
353
<literal>FALSE</literal> if the <parameter>field</parameter>'s size in units should stay the same.
354
</simpara></listitem></varlistentry>
355
</variablelist></refsect2>
357
<title><anchor id="gimp-size-entry-set-size"/>gimp_size_entry_set_size ()</title>
358
<indexterm><primary>gimp_size_entry_set_size</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_size (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
359
<link linkend="gint">gint</link> field,
360
<link linkend="gdouble">gdouble</link> lower,
361
<link linkend="gdouble">gdouble</link> upper);</programlisting>
363
Sets the pixel values for field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>
364
which will be treated as 0% and 100%.
367
These values will be used if you specified <parameter>menu_show_percent</parameter> as <literal>TRUE</literal>
368
in <link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link> and the user has selected GIMP_UNIT_PERCENT in
369
the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s <link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link>.
372
This function does nothing if the <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> specified in
373
<link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link> doesn't equal to GIMP_SIZE_ENTRY_UPDATE_SIZE.</para>
376
</para><variablelist role="params">
377
<varlistentry><term><parameter>gse</parameter> :</term>
378
<listitem><simpara> The sizeentry you want to set a size for.
379
</simpara></listitem></varlistentry>
380
<varlistentry><term><parameter>field</parameter> :</term>
381
<listitem><simpara> The index of the field you want to set the size for.
382
</simpara></listitem></varlistentry>
383
<varlistentry><term><parameter>lower</parameter> :</term>
384
<listitem><simpara> The reference value which will be treated as 0%.
385
</simpara></listitem></varlistentry>
386
<varlistentry><term><parameter>upper</parameter> :</term>
387
<listitem><simpara> The reference value which will be treated as 100%.
388
</simpara></listitem></varlistentry>
389
</variablelist></refsect2>
391
<title><anchor id="gimp-size-entry-set-value-boundaries"/>gimp_size_entry_set_value_boundaries ()</title>
392
<indexterm><primary>gimp_size_entry_set_value_boundaries</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_value_boundaries
393
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
394
<link linkend="gint">gint</link> field,
395
<link linkend="gdouble">gdouble</link> lower,
396
<link linkend="gdouble">gdouble</link> upper);</programlisting>
398
Limits the range of possible values which can be entered in field # <parameter>field</parameter>
399
of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
402
The current value of the <parameter>field</parameter> will be clamped to fit in the <parameter>field</parameter>'s
406
NOTE: In most cases you won't be interested in these values because the
407
<link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s purpose is to shield the programmer from unit
408
calculations. Use <link linkend="gimp-size-entry-set-refval-boundaries"><function>gimp_size_entry_set_refval_boundaries()</function></link> instead.
409
Whatever you do, don't mix these calls. A size entry should either
410
be clamped by the value or the reference value.</para>
413
</para><variablelist role="params">
414
<varlistentry><term><parameter>gse</parameter> :</term>
415
<listitem><simpara> The sizeentry you want to set value boundaries for.
416
</simpara></listitem></varlistentry>
417
<varlistentry><term><parameter>field</parameter> :</term>
418
<listitem><simpara> The index of the field you want to set value boundaries for.
419
</simpara></listitem></varlistentry>
420
<varlistentry><term><parameter>lower</parameter> :</term>
421
<listitem><simpara> The new lower boundary of the value of the chosen <parameter>field</parameter>.
422
</simpara></listitem></varlistentry>
423
<varlistentry><term><parameter>upper</parameter> :</term>
424
<listitem><simpara> The new upper boundary of the value of the chosen <parameter>field</parameter>.
425
</simpara></listitem></varlistentry>
426
</variablelist></refsect2>
428
<title><anchor id="gimp-size-entry-get-value"/>gimp_size_entry_get_value ()</title>
429
<indexterm><primary>gimp_size_entry_get_value</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> gimp_size_entry_get_value (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
430
<link linkend="gint">gint</link> field);</programlisting>
432
Returns the value of field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
435
The <parameter>value</parameter> returned is a distance or resolution
436
in the <link linkend="GimpUnit"><type>GimpUnit</type></link> the user has selected in the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s
437
<link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link>.
440
NOTE: In most cases you won't be interested in this value because the
441
<link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s purpose is to shield the programmer from unit
442
calculations. Use <link linkend="gimp-size-entry-get-refval"><function>gimp_size_entry_get_refval()</function></link> instead.</para>
445
</para><variablelist role="params">
446
<varlistentry><term><parameter>gse</parameter> :</term>
447
<listitem><simpara> The sizeentry you want to know a value of.
448
</simpara></listitem></varlistentry>
449
<varlistentry><term><parameter>field</parameter> :</term>
450
<listitem><simpara> The index of the field you want to know the value of.
451
</simpara></listitem></varlistentry>
452
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The value of the chosen <parameter>field</parameter>.
453
</simpara></listitem></varlistentry>
454
</variablelist></refsect2>
456
<title><anchor id="gimp-size-entry-set-value"/>gimp_size_entry_set_value ()</title>
457
<indexterm><primary>gimp_size_entry_set_value</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_value (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
458
<link linkend="gint">gint</link> field,
459
<link linkend="gdouble">gdouble</link> value);</programlisting>
461
Sets the value for field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
464
The <parameter>value</parameter> passed is treated to be a distance or resolution
465
in the <link linkend="GimpUnit"><type>GimpUnit</type></link> the user has selected in the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s
466
<link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link>.
469
NOTE: In most cases you won't be interested in this value because the
470
<link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s purpose is to shield the programmer from unit
471
calculations. Use <link linkend="gimp-size-entry-set-refval"><function>gimp_size_entry_set_refval()</function></link> instead.</para>
474
</para><variablelist role="params">
475
<varlistentry><term><parameter>gse</parameter> :</term>
476
<listitem><simpara> The sizeentry you want to set a value for.
477
</simpara></listitem></varlistentry>
478
<varlistentry><term><parameter>field</parameter> :</term>
479
<listitem><simpara> The index of the field you want to set a value for.
480
</simpara></listitem></varlistentry>
481
<varlistentry><term><parameter>value</parameter> :</term>
482
<listitem><simpara> The new value for <parameter>field</parameter>.
483
</simpara></listitem></varlistentry>
484
</variablelist></refsect2>
486
<title><anchor id="gimp-size-entry-set-refval-boundaries"/>gimp_size_entry_set_refval_boundaries ()</title>
487
<indexterm><primary>gimp_size_entry_set_refval_boundaries</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_refval_boundaries
488
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
489
<link linkend="gint">gint</link> field,
490
<link linkend="gdouble">gdouble</link> lower,
491
<link linkend="gdouble">gdouble</link> upper);</programlisting>
493
Limits the range of possible reference values which can be entered in
494
field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
497
The current reference value of the <parameter>field</parameter> will be clamped to fit in the
498
<parameter>field</parameter>'s new boundaries.</para>
501
</para><variablelist role="params">
502
<varlistentry><term><parameter>gse</parameter> :</term>
503
<listitem><simpara> The sizeentry you want to set the reference value boundaries for.
504
</simpara></listitem></varlistentry>
505
<varlistentry><term><parameter>field</parameter> :</term>
506
<listitem><simpara> The index of the field you want to set the reference value
508
</simpara></listitem></varlistentry>
509
<varlistentry><term><parameter>lower</parameter> :</term>
510
<listitem><simpara> The new lower boundary of the reference value of the chosen <parameter>field</parameter>.
511
</simpara></listitem></varlistentry>
512
<varlistentry><term><parameter>upper</parameter> :</term>
513
<listitem><simpara> The new upper boundary of the reference value of the chosen <parameter>field</parameter>.
514
</simpara></listitem></varlistentry>
515
</variablelist></refsect2>
517
<title><anchor id="gimp-size-entry-set-refval-digits"/>gimp_size_entry_set_refval_digits ()</title>
518
<indexterm><primary>gimp_size_entry_set_refval_digits</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_refval_digits
519
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
520
<link linkend="gint">gint</link> field,
521
<link linkend="gint">gint</link> digits);</programlisting>
523
Sets the decimal digits of field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> to
524
<parameter>digits</parameter>.
527
If you don't specify this value explicitly, the reference value's number
528
of digits will equal to 0 for <link linkend="GIMP-SIZE-ENTRY-UPDATE-SIZE:CAPS"><type>GIMP_SIZE_ENTRY_UPDATE_SIZE</type></link> and to 2 for
529
<link linkend="GIMP-SIZE-ENTRY-UPDATE-RESOLUTION:CAPS"><type>GIMP_SIZE_ENTRY_UPDATE_RESOLUTION</type></link>.</para>
532
</para><variablelist role="params">
533
<varlistentry><term><parameter>gse</parameter> :</term>
534
<listitem><simpara> The sizeentry you want to set the reference value digits for.
535
</simpara></listitem></varlistentry>
536
<varlistentry><term><parameter>field</parameter> :</term>
537
<listitem><simpara> The index of the field you want to set the reference value for.
538
</simpara></listitem></varlistentry>
539
<varlistentry><term><parameter>digits</parameter> :</term>
540
<listitem><simpara> The new number of decimal digits for the <link linkend="GtkSpinButton"><type>GtkSpinButton</type></link> which
541
displays <parameter>field</parameter>'s reference value.
542
</simpara></listitem></varlistentry>
543
</variablelist></refsect2>
545
<title><anchor id="gimp-size-entry-get-refval"/>gimp_size_entry_get_refval ()</title>
546
<indexterm><primary>gimp_size_entry_get_refval</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> gimp_size_entry_get_refval (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
547
<link linkend="gint">gint</link> field);</programlisting>
549
Returns the reference value for field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
552
The reference value is either a distance in pixels or a resolution
553
in dpi, depending on which <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> you chose in
554
<link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link>.</para>
557
</para><variablelist role="params">
558
<varlistentry><term><parameter>gse</parameter> :</term>
559
<listitem><simpara> The sizeentry you want to know a reference value of.
560
</simpara></listitem></varlistentry>
561
<varlistentry><term><parameter>field</parameter> :</term>
562
<listitem><simpara> The index of the field you want to know the reference value of.
563
</simpara></listitem></varlistentry>
564
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The reference value of the chosen <parameter>field</parameter>.
565
</simpara></listitem></varlistentry>
566
</variablelist></refsect2>
568
<title><anchor id="gimp-size-entry-set-refval"/>gimp_size_entry_set_refval ()</title>
569
<indexterm><primary>gimp_size_entry_set_refval</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_refval (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
570
<link linkend="gint">gint</link> field,
571
<link linkend="gdouble">gdouble</link> refval);</programlisting>
573
Sets the reference value for field # <parameter>field</parameter> of the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>.
576
The <parameter>refval</parameter> passed is either a distance in pixels or a resolution in dpi,
577
depending on which <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> you chose in
578
<link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link>.</para>
581
</para><variablelist role="params">
582
<varlistentry><term><parameter>gse</parameter> :</term>
583
<listitem><simpara> The sizeentry you want to set a reference value for.
584
</simpara></listitem></varlistentry>
585
<varlistentry><term><parameter>field</parameter> :</term>
586
<listitem><simpara> The index of the field you want to set the reference value for.
587
</simpara></listitem></varlistentry>
588
<varlistentry><term><parameter>refval</parameter> :</term>
589
<listitem><simpara> The new reference value for <parameter>field</parameter>.
590
</simpara></listitem></varlistentry>
591
</variablelist></refsect2>
593
<title><anchor id="gimp-size-entry-get-unit"/>gimp_size_entry_get_unit ()</title>
594
<indexterm><primary>gimp_size_entry_get_unit</primary></indexterm><programlisting><link linkend="GimpUnit">GimpUnit</link> gimp_size_entry_get_unit (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse);</programlisting>
596
Returns the <link linkend="GimpUnit"><type>GimpUnit</type></link> the user has selected in the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s
597
<link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link>.</para>
600
</para><variablelist role="params">
601
<varlistentry><term><parameter>gse</parameter> :</term>
602
<listitem><simpara> The sizeentry you want to know the unit of.
603
</simpara></listitem></varlistentry>
604
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The sizeentry's unit.
605
</simpara></listitem></varlistentry>
606
</variablelist></refsect2>
608
<title><anchor id="gimp-size-entry-set-unit"/>gimp_size_entry_set_unit ()</title>
609
<indexterm><primary>gimp_size_entry_set_unit</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_unit (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
610
<link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
612
Sets the <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>'s unit. The reference value for all fields will
613
stay the same but the value in units or pixels per unit will change
614
according to which <link linkend="GimpSizeEntryUpdatePolicy"><type>GimpSizeEntryUpdatePolicy</type></link> you chose in
615
<link linkend="gimp-size-entry-new"><function>gimp_size_entry_new()</function></link>.</para>
618
</para><variablelist role="params">
619
<varlistentry><term><parameter>gse</parameter> :</term>
620
<listitem><simpara> The sizeentry you want to change the unit for.
621
</simpara></listitem></varlistentry>
622
<varlistentry><term><parameter>unit</parameter> :</term>
623
<listitem><simpara> The new unit.
624
</simpara></listitem></varlistentry>
625
</variablelist></refsect2>
627
<title><anchor id="gimp-size-entry-set-pixel-digits"/>gimp_size_entry_set_pixel_digits ()</title>
628
<indexterm><primary>gimp_size_entry_set_pixel_digits</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_set_pixel_digits
629
(<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
630
<link linkend="gint">gint</link> digits);</programlisting>
632
Similar to <link linkend="gimp-unit-menu-set-pixel-digits"><function>gimp_unit_menu_set_pixel_digits()</function></link>, this function allows
633
you set up a <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> so that sub-pixel sizes can be entered.</para>
636
</para><variablelist role="params">
637
<varlistentry><term><parameter>gse</parameter> :</term>
638
<listitem><simpara> a <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>
639
</simpara></listitem></varlistentry>
640
<varlistentry><term><parameter>digits</parameter> :</term>
641
<listitem><simpara> the number of digits to display for a pixel size
642
</simpara></listitem></varlistentry>
643
</variablelist></refsect2>
645
<title><anchor id="gimp-size-entry-grab-focus"/>gimp_size_entry_grab_focus ()</title>
646
<indexterm><primary>gimp_size_entry_grab_focus</primary></indexterm><programlisting><link linkend="void">void</link> gimp_size_entry_grab_focus (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse);</programlisting>
648
This function is rather ugly and just a workaround for the fact that
649
it's impossible to implement <link linkend="gtk-widget-grab-focus"><function>gtk_widget_grab_focus()</function></link> for a <link linkend="GtkTable"><type>GtkTable</type></link>.</para>
652
</para><variablelist role="params">
653
<varlistentry><term><parameter>gse</parameter> :</term>
654
<listitem><simpara> The sizeentry you want to grab the keyboard focus.
655
</simpara></listitem></varlistentry>
656
</variablelist></refsect2>
658
<title><anchor id="gimp-size-entry-get-help-widget"/>gimp_size_entry_get_help_widget ()</title>
659
<indexterm><primary>gimp_size_entry_get_help_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gimp_size_entry_get_help_widget (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gse,
660
<link linkend="gint">gint</link> field);</programlisting>
662
You shouldn't fiddle with the internals of a <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link> but
663
if you want to set tooltips using <link linkend="gimp-help-set-help-data"><function>gimp_help_set_help_data()</function></link> you
664
can use this function to get a pointer to the spinbuttons.</para>
667
</para><variablelist role="params">
668
<varlistentry><term><parameter>gse</parameter> :</term>
669
<listitem><simpara> a <link linkend="GimpSizeEntry"><type>GimpSizeEntry</type></link>
670
</simpara></listitem></varlistentry>
671
<varlistentry><term><parameter>field</parameter> :</term>
672
<listitem><simpara> the index of the widget you want to get a pointer to
673
</simpara></listitem></varlistentry>
674
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GtkWidget"><type>GtkWidget</type></link> pointer that you can attach a tooltip to.
675
</simpara></listitem></varlistentry>
676
</variablelist></refsect2>
681
<title>Signals</title>
682
<refsect2><title><anchor id="GimpSizeEntry-refval-changed"/>The "refval-changed" signal</title>
683
<programlisting><link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
684
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
687
</para><variablelist role="params">
688
<varlistentry><term><parameter>gimpsizeentry</parameter> :</term>
689
<listitem><simpara>the object which received the signal.
691
</simpara></listitem></varlistentry>
692
<varlistentry><term><parameter>user_data</parameter> :</term>
693
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
694
</variablelist></refsect2><refsect2><title><anchor id="GimpSizeEntry-unit-changed"/>The "unit-changed" signal</title>
695
<programlisting><link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
696
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
699
</para><variablelist role="params">
700
<varlistentry><term><parameter>gimpsizeentry</parameter> :</term>
701
<listitem><simpara>the object which received the signal.
703
</simpara></listitem></varlistentry>
704
<varlistentry><term><parameter>user_data</parameter> :</term>
705
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
706
</variablelist></refsect2><refsect2><title><anchor id="GimpSizeEntry-value-changed"/>The "value-changed" signal</title>
707
<programlisting><link linkend="void">void</link> user_function (<link linkend="GimpSizeEntry">GimpSizeEntry</link> *gimpsizeentry,
708
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
711
</para><variablelist role="params">
712
<varlistentry><term><parameter>gimpsizeentry</parameter> :</term>
713
<listitem><simpara>the object which received the signal.
715
</simpara></listitem></varlistentry>
716
<varlistentry><term><parameter>user_data</parameter> :</term>
717
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
718
</variablelist></refsect2>
723
<title>See Also</title>
725
<link linkend="GimpUnit"><type>GimpUnit</type></link>
728
<link linkend="GimpUnitMenu"><type>GimpUnitMenu</type></link>
731
<link linkend="gimp-coordinates-new"><function>gimp_coordinates_new()</function></link>
added
removed
devel-docs/libgimpwidgets/xml/gimpsizeentry.xml
