GimpWidgets: GIMP Widgets Library Reference Manual

## GimpWidgets GimpWidgets — A collection of convenient widget constructors, standard callbacks and helper functions. |

## Functions

GtkWidget * | gimp_radio_group_new ()
GtkWidget * | gimp_radio_group_new2 ()
void | gimp_radio_group_set_active ()
GtkWidget * | gimp_int_radio_group_new ()
void | gimp_int_radio_group_set_active ()
GtkWidget * | gimp_spin_button_new ()
#define | GIMP_SCALE_ENTRY_LABEL()
#define | GIMP_SCALE_ENTRY_SCALE()
#define | GIMP_SCALE_ENTRY_SCALE_ADJ()
#define | GIMP_SCALE_ENTRY_SPINBUTTON()
#define | GIMP_SCALE_ENTRY_SPINBUTTON_ADJ()
GtkObject * | gimp_scale_entry_new ()
void | gimp_scale_entry_set_sensitive ()
void | gimp_scale_entry_set_logarithmic ()
gboolean | gimp_scale_entry_get_logarithmic ()
GtkObject * | gimp_color_scale_entry_new ()
#define | GIMP_RANDOM_SEED_SPINBUTTON()
#define | GIMP_RANDOM_SEED_SPINBUTTON_ADJ()
#define | GIMP_RANDOM_SEED_TOGGLE()
GtkWidget * | gimp_random_seed_new ()
#define | GIMP_COORDINATES_CHAINBUTTON()
GtkWidget * | gimp_coordinates_new ()
void | gimp_toggle_button_update ()
void | gimp_radio_button_update ()
void | gimp_int_adjustment_update ()
void | gimp_uint_adjustment_update ()
void | gimp_float_adjustment_update ()
void | gimp_double_adjustment_update ()
GQuark | gimp_widgets_error_quark ()

## Types and Values

enum | GimpWidgetsError
#define | GIMP_WIDGETS_ERROR

## Description

A collection of convenient widget constructors, standard callbacks and helper functions.

## Functions

### gimp_radio_group_new ()

    GtkWidget *
    gimp_radio_group_new (gboolean in_frame,
                          const gchar *frame_title);

Convenience function to create a group of radio buttons embedded into a GtkFrame or GtkVBox.

#### Parameters

in_frame | `TRUE` if you want a GtkFrame around the radio button group. |
frame_title | The title of the Frame or `NULL` if you don't want a title. |
... | A `NULL`-terminated `va_list` describing the radio buttons. |

#### Returns

A GtkFrame or GtkVBox (depending on `in_frame` ).

### gimp_radio_group_new2 ()

    GtkWidget *
    gimp_radio_group_new2 (gboolean in_frame,
                           const gchar *frame_title,
                           GCallback radio_button_callback,
                           gpointer radio_button_callback_data,
                           gpointer initial);

Convenience function to create a group of radio buttons embedded into a GtkFrame or GtkVBox.

#### Parameters

in_frame | `TRUE` if you want a GtkFrame around the radio button group. |
frame_title | The title of the Frame or `NULL` if you don't want a title. |
radio_button_callback | The callback each button's "toggled" signal will be connected with. |
radio_button_callback_data | The data which will be passed to `g_signal_connect()`. |
initial | The `item_data` of the initially pressed radio button. |
... | A `NULL`-terminated `va_list` describing the radio buttons. |

#### Returns

A GtkFrame or GtkVBox (depending on `in_frame` ).

### gimp_radio_group_set_active ()

    void
    gimp_radio_group_set_active (GtkRadioButton *radio_button,
                                 gpointer item_data);

Calls `gtk_toggle_button_set_active()` with the radio button that was created with a matching `item_data` .

#### Parameters

radio_button | Pointer to a GtkRadioButton. |
item_data | The `item_data` of the radio button you want to select. |

### gimp_int_radio_group_new ()

    GtkWidget *
    gimp_int_radio_group_new (gboolean in_frame,
                              const gchar *frame_title,
                              GCallback radio_button_callback,
                              gpointer radio_button_callback_data,
                              gint initial);

Convenience function to create a group of radio buttons embedded into a GtkFrame or GtkVBox. This function does the same thing as `gimp_radio_group_new2()`, but it takes integers as `item_data` instead of pointers, since that is a very common case (mapping an enum to a radio group).

#### Parameters

in_frame | `TRUE` if you want a GtkFrame around the radio button group. |
frame_title | The title of the Frame or `NULL` if you don't want a title. |
radio_button_callback | The callback each button's "toggled" signal will be connected with. |
radio_button_callback_data | The data which will be passed to `g_signal_connect()`. |
initial | The `item_data` of the initially pressed radio button. |
... | A `NULL`-terminated `va_list` describing the radio buttons. |

#### Returns

A GtkFrame or GtkVBox (depending on `in_frame` ).

### gimp_int_radio_group_set_active ()

    void
    gimp_int_radio_group_set_active (GtkRadioButton *radio_button,
                                     gint item_data);

Calls `gtk_toggle_button_set_active()` with the radio button that was created with a matching `item_data` . This function does the same thing as `gimp_radio_group_set_active()`, but takes integers as `item_data` instead of pointers.

#### Parameters

radio_button | Pointer to a GtkRadioButton. |
item_data | The `item_data` of the radio button you want to select. |

### gimp_spin_button_new ()

    GtkWidget *
    gimp_spin_button_new (GtkObject **adjustment,
                          gdouble value,
                          gdouble lower,
                          gdouble upper,
                          gdouble step_increment,
                          gdouble page_increment,
                          gdouble page_size,
                          gdouble climb_rate,
                          guint digits);

`gimp_spin_button_new` has been deprecated since version 2.10 and should not be used in newly-written code.

Use `gtk_spin_button_new()` instead.

This function is a shortcut for `gtk_adjustment_new()` and a subsequent `gtk_spin_button_new()`. It also calls `gtk_spin_button_set_numeric()` so that non-numeric text cannot be entered.

#### Parameters

adjustment | Returns the spinbutton's GtkAdjustment. |
value | The initial value of the spinbutton. |
lower | The lower boundary. |
upper | The upper boundary. |
step_increment | The spinbutton's step increment. |
page_increment | The spinbutton's page increment (mouse button 2). |
page_size | Ignored, spin buttons must always have a zero page size. |
climb_rate | The spinbutton's climb rate. |
digits | The spinbutton's number of decimal digits. |

#### Returns

A GtkSpinButton and its GtkAdjustment.

Since: 2.10.10

### GIMP_SCALE_ENTRY_LABEL()

    #define             GIMP_SCALE_ENTRY_LABEL(adj)

#### Parameters

adj | The GtkAdjustment returned by `gimp_scale_entry_new()`. |

#### Returns

the scale_entry's GtkLabel.

### GIMP_SCALE_ENTRY_SCALE()

    #define             GIMP_SCALE_ENTRY_SCALE(adj)

#### Parameters

adj | The GtkAdjustment returned by `gimp_scale_entry_new()`. |

#### Returns

the scale_entry's GtkHScale.

### GIMP_SCALE_ENTRY_SCALE_ADJ()

    #define             GIMP_SCALE_ENTRY_SCALE_ADJ(adj)

#### Parameters

adj | The GtkAdjustment returned by `gimp_scale_entry_new()`. |

#### Returns

the GtkAdjustment of the scale_entry's GtkHScale.

### GIMP_SCALE_ENTRY_SPINBUTTON()

    #define             GIMP_SCALE_ENTRY_SPINBUTTON(adj)

#### Parameters

adj | The GtkAdjustment returned by `gimp_scale_entry_new()`. |

#### Returns

the scale_entry's GtkSpinButton.

### GIMP_SCALE_ENTRY_SPINBUTTON_ADJ()

    #define             GIMP_SCALE_ENTRY_SPINBUTTON_ADJ(adj)

#### Parameters

adj | The GtkAdjustment returned by `gimp_scale_entry_new()`. |

#### Returns

the GtkAdjustment of the scale_entry's GtkSpinButton.

### gimp_scale_entry_new ()

    GtkObject *
    gimp_scale_entry_new (GtkTable *table,
                          gint column,
                          gint row,
                          const gchar *text,
                          gint scale_width,
                          gint spinbutton_width,
                          gdouble value,
                          gdouble lower,
                          gdouble upper,
                          gdouble step_increment,
                          gdouble page_increment,
                          guint digits,
                          gboolean constrain,
                          gdouble unconstrained_lower,
                          gdouble unconstrained_upper,
                          const gchar *tooltip,
                          const gchar *help_id);

This function creates a GtkLabel, a GtkHScale and a GtkSpinButton and attaches them to a 3-column GtkTable.

#### Parameters

table | The GtkTable the widgets will be attached to. |
column | The column to start with. |
row | The row to attach the widgets. |
text | The text for the GtkLabel which will appear left of the GtkHScale. |
scale_width | The minimum horizontal size of the GtkHScale. |
spinbutton_width | The minimum horizontal size of the GtkSpinButton. |
value | The initial value. |
lower | The lower boundary. |
upper | The upper boundary. |
step_increment | The step increment. |
page_increment | The page increment. |
digits | The number of decimal digits. |
constrain | `TRUE` if the range of possible values of the GtkSpinButton should be the same as of the GtkHScale. |
unconstrained_lower | The spinbutton's lower boundary if `constrain` == `FALSE`. |
unconstrained_upper | The spinbutton's upper boundary if `constrain` == `FALSE`. |
tooltip | A tooltip message for the scale and the spinbutton. |
help_id | The widgets' help_id (see `gimp_help_set_help_data()`). |

#### Returns

The GtkSpinButton's GtkAdjustment.

### gimp_scale_entry_set_sensitive ()

    void
    gimp_scale_entry_set_sensitive (GtkObject *adjustment,
                                    gboolean sensitive);

Sets the sensitivity of the scale_entry's GtkLabel, GtkHScale and GtkSpinButton.

#### Parameters

adjustment | a GtkAdjustment returned by `gimp_scale_entry_new()` |
sensitive | a boolean value with the same semantics as the `sensitive` parameter of `gtk_widget_set_sensitive()` |

### gimp_scale_entry_set_logarithmic ()

    void
    gimp_scale_entry_set_logarithmic (GtkObject *adjustment,
                                      gboolean logarithmic);

Sets whether the scale_entry's scale widget will behave in a linear or logharithmic fashion. Useful when an entry has to attend large ranges, but smaller selections on that range require a finer adjustment.

#### Parameters

adjustment | a GtkAdjustment as returned by `gimp_scale_entry_new()` |
logarithmic | a boolean value to set or reset logarithmic behaviour of the scale widget |

Since: 2.2

### gimp_scale_entry_get_logarithmic ()

    gboolean
    gimp_scale_entry_get_logarithmic (GtkObject *adjustment);

#### Parameters

adjustment | a GtkAdjustment as returned by `gimp_scale_entry_new()` |

#### Returns

`TRUE` if the the entry's scale widget will behave in logharithmic fashion, `FALSE` for linear behaviour.

Since: 2.2

### gimp_color_scale_entry_new ()

    GtkObject *
    gimp_color_scale_entry_new (GtkTable *table,
                                gint column,
                                gint row,
                                const gchar *text,
                                gint scale_width,
                                gint spinbutton_width,
                                gdouble value,
                                gdouble lower,
                                gdouble upper,
                                gdouble step_increment,
                                gdouble page_increment,
                                guint digits,
                                const gchar *tooltip,
                                const gchar *help_id);

This function creates a GtkLabel, a GimpColorScale and a GtkSpinButton and attaches them to a 3-column GtkTable.

#### Parameters

table | The GtkTable the widgets will be attached to. |
column | The column to start with. |
row | The row to attach the widgets. |
text | The text for the GtkLabel which will appear left of the GtkHScale. |
scale_width | The minimum horizontal size of the GtkHScale. |
spinbutton_width | The minimum horizontal size of the GtkSpinButton. |
value | The initial value. |
lower | The lower boundary. |
upper | The upper boundary. |
step_increment | The step increment. |
page_increment | The page increment. |
digits | The number of decimal digits. |
tooltip | A tooltip message for the scale and the spinbutton. |
help_id | The widgets' help_id (see `gimp_help_set_help_data()`). |

#### Returns

The GtkSpinButton's GtkAdjustment.

### GIMP_RANDOM_SEED_SPINBUTTON()

    #define             GIMP_RANDOM_SEED_SPINBUTTON(hbox)

#### Parameters

hbox | The GtkHBox returned by `gimp_random_seed_new()`. |

#### Returns

the random_seed's GtkSpinButton.

### GIMP_RANDOM_SEED_SPINBUTTON_ADJ()

    #define             GIMP_RANDOM_SEED_SPINBUTTON_ADJ(hbox)

#### Parameters

hbox | The GtkHBox returned by `gimp_random_seed_new()`. |

#### Returns

the GtkAdjustment of the random_seed's GtkSpinButton.

### GIMP_RANDOM_SEED_TOGGLE()

    #define             GIMP_RANDOM_SEED_TOGGLE(hbox)

#### Parameters

hbox | The GtkHBox returned by `gimp_random_seed_new()`. |

#### Returns

the random_seed's GtkToggleButton.

### gimp_random_seed_new ()

    GtkWidget *
    gimp_random_seed_new (guint32 *seed,
                          gboolean *random_seed);

Creates a widget that allows the user to control how the random number generator is initialized.

#### Parameters

seed | A pointer to the variable which stores the random seed. |
random_seed | A pointer to a boolean indicating whether seed should be initialised randomly or not. |

#### Returns

A GtkHBox containing a GtkSpinButton for the seed and a GtkButton for setting a random seed.

### GIMP_COORDINATES_CHAINBUTTON()

    #define             GIMP_COORDINATES_CHAINBUTTON(sizeentry)

#### Parameters

sizeentry | The GimpSizeEntry returned by `gimp_coordinates_new()`. |

#### Returns

the GimpChainButton which is attached to the GimpSizeEntry.

### gimp_coordinates_new ()

    GtkWidget *
    gimp_coordinates_new (GimpUnit unit,
                          const gchar *unit_format,
                          gboolean menu_show_pixels,
                          gboolean menu_show_percent,
                          gint spinbutton_width,
                          GimpSizeEntryUpdatePolicy update_policy,
                          gboolean chainbutton_active,
                          gboolean chain_constrains_ratio,
                          const gchar *xlabel,
                          gdouble x,
                          gdouble xres,
                          gdouble lower_boundary_x,
                          gdouble upper_boundary_x,
                          gdouble xsize_0,
                          gdouble xsize_100,
                          const gchar *ylabel,
                          gdouble y,
                          gdouble yres,
                          gdouble lower_boundary_y,
                          gdouble upper_boundary_y,
                          gdouble ysize_0,
                          gdouble ysize_100);

Convenience function that creates a GimpSizeEntry with two fields for x/y coordinates/sizes with a GimpChainButton attached to constrain either the two fields' values or the ratio between them.

#### Parameters

unit | The initial unit of the GimpUnitMenu. |
unit_format | A printf-like unit-format string as is used with `gimp_unit_menu_new()`. |
menu_show_pixels | `TRUE` if the GimpUnitMenu should contain an item for GIMP_UNIT_PIXEL. |
menu_show_percent | `TRUE` if the GimpUnitMenu should contain an item for GIMP_UNIT_PERCENT. |
spinbutton_width | The horizontal size of the GimpSizeEntry's GtkSpinButton's. |
update_policy | The update policy for the GimpSizeEntry. |
chainbutton_active | `TRUE` if the attached GimpChainButton should be active. |
chain_constrains_ratio | `TRUE` if the chainbutton should constrain the fields' aspect ratio. If `FALSE`, the values will be constrained. |
xlabel | The label for the X coordinate. |
x | The initial value of the X coordinate. |
xres | The horizontal resolution in DPI. |
lower_boundary_x | The lower boundary of the X coordinate. |
upper_boundary_x | The upper boundary of the X coordinate. |
xsize_0 | The X value which will be treated as 0%. |
xsize_100 | The X value which will be treated as 100%. |
ylabel | The label for the Y coordinate. |
y | The initial value of the Y coordinate. |
yres | The vertical resolution in DPI. |
lower_boundary_y | The lower boundary of the Y coordinate. |
upper_boundary_y | The upper boundary of the Y coordinate. |
ysize_0 | The Y value which will be treated as 0%. |
ysize_100 | The Y value which will be treated as 100%. |

#### Returns

The new GimpSizeEntry.

### gimp_toggle_button_update ()

    void
    gimp_toggle_button_update (GtkWidget *widget,
                               gpointer data);

Note that this function calls `gimp_toggle_button_sensitive_update()` which is a deprecated hack you shouldn't use. See that function's documentation for a proper replacement of its functionality.

#### Parameters

widget | A GtkToggleButton. |
data | A pointer to a gint variable which will store the value of `gtk_toggle_button_get_active()`. |

### gimp_radio_button_update ()

    void
    gimp_radio_button_update (GtkWidget *widget,
                              gpointer data);

Note that this function calls `gimp_toggle_button_sensitive_update()` which is a deprecated hack you shouldn't use. See that function's documentation for a proper replacement of its functionality.

#### Parameters

widget | A GtkRadioButton. |
data | A pointer to a gint variable which will store the value of GPOINTER_TO_INT (g_object_get_data (`widget` , "gimp-item-data")). |

### gimp_int_adjustment_update ()

    void
    gimp_int_adjustment_update (GtkAdjustment *adjustment,
                                gpointer data);

Note that the GtkAdjustment's value (which is a gdouble) will be rounded with `RINT()`.

#### Parameters

adjustment | A GtkAdjustment. |
data | A pointer to a gint variable which will store the `adjustment` 's value. |

### gimp_uint_adjustment_update ()

    void
    gimp_uint_adjustment_update (GtkAdjustment *adjustment,
                                 gpointer data);

Note that the GtkAdjustment's value (which is a gdouble) will be rounded with (guint) (value + 0.5).

#### Parameters

adjustment | A GtkAdjustment. |
data | A pointer to a guint variable which will store the `adjustment` 's value. |

### gimp_float_adjustment_update ()

    void
    gimp_float_adjustment_update (GtkAdjustment *adjustment,
                                  gpointer data);

#### Parameters

adjustment | A GtkAdjustment. |
data | A pointer to a gfloat variable which will store the `adjustment` 's value. |

### gimp_double_adjustment_update ()

    void
    gimp_double_adjustment_update (GtkAdjustment *adjustment,
                                   gpointer data);

#### Parameters

adjustment | A GtkAdjustment. |
data | A pointer to a gdouble variable which will store the `adjustment` 's value. |

### gimp_widgets_error_quark ()

    GQuark
    gimp_widgets_error_quark (void);

This function is never called directly. Use `GIMP_WIDGETS_ERROR()` instead.

#### Returns

the GQuark that defines the GIMP widgets error domain.

## Types and Values

### enum GimpWidgetsError

Types of errors returned by libgimpwidgets functions

#### Members

GIMP_WIDGETS_PARSE_ERROR | A parse error has occured |

### GIMP_WIDGETS_ERROR

    #define GIMP_WIDGETS_ERROR (gimp_widgets_error_quark ())

The GIMP widgets error domain.

Since: 2.8