## GimpWidgets

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

## Synopsis

    enum                GimpWidgetsError;
    GtkWidget *         gimp_radio_group_new                (gboolean in_frame,
                                                             const gchar *frame_title,
                                                             ...);
    GtkWidget *         gimp_radio_group_new2               (gboolean in_frame,
                                                             const gchar *frame_title,
                                                             GCallback radio_button_callback,
                                                             gpointer radio_button_callback_data,
                                                             gpointer initial,
                                                             ...);
    void                gimp_radio_group_set_active         (GtkRadioButton *radio_button,
                                                             gpointer item_data);
    GtkWidget *         gimp_int_radio_group_new            (gboolean in_frame,
                                                             const gchar *frame_title,
                                                             GCallback radio_button_callback,
                                                             gpointer radio_button_callback_data,
                                                             gint initial,
                                                             ...);
    void                gimp_int_radio_group_set_active     (GtkRadioButton *radio_button,
                                                             gint item_data);
    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);
    #define             GIMP_SCALE_ENTRY_LABEL              (adj)
    #define             GIMP_SCALE_ENTRY_SCALE              (adj)
    #define             GIMP_SCALE_ENTRY_SCALE_ADJ          (adj)
    #define             GIMP_SCALE_ENTRY_SPINBUTTON         (adj)
    #define             GIMP_SCALE_ENTRY_SPINBUTTON_ADJ     (adj)
    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);
    void                gimp_scale_entry_set_sensitive      (GtkObject *adjustment,
                                                             gboolean sensitive);
    void                gimp_scale_entry_set_logarithmic    (GtkObject *adjustment,
                                                             gboolean logarithmic);
    gboolean            gimp_scale_entry_get_logarithmic    (GtkObject *adjustment);
    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);
    #define             GIMP_RANDOM_SEED_SPINBUTTON         (hbox)
    #define             GIMP_RANDOM_SEED_SPINBUTTON_ADJ     (hbox)
    #define             GIMP_RANDOM_SEED_TOGGLE             (hbox)
    GtkWidget *         gimp_random_seed_new                (guint32 *seed,
                                                             gboolean *random_seed);
    #define             GIMP_COORDINATES_CHAINBUTTON        (sizeentry)
    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);
    void                gimp_toggle_button_update           (GtkWidget *widget,
                                                             gpointer data);
    void                gimp_radio_button_update            (GtkWidget *widget,
                                                             gpointer data);
    void                gimp_int_adjustment_update          (GtkAdjustment *adjustment,
                                                             gpointer data);
    void                gimp_uint_adjustment_update         (GtkAdjustment *adjustment,
                                                             gpointer data);
    void                gimp_float_adjustment_update        (GtkAdjustment *adjustment,
                                                             gpointer data);
    void                gimp_double_adjustment_update       (GtkAdjustment *adjustment,
                                                             gpointer data);
    GtkWidget *         gimp_table_attach_aligned           (GtkTable *table,
                                                             gint column,
                                                             gint row,
                                                             const gchar *label_text,
                                                             gfloat xalign,
                                                             gfloat yalign,
                                                             GtkWidget *widget,
                                                             gint colspan,
                                                             gboolean left_align);
    void                gimp_label_set_attributes           (GtkLabel *label,
                                                             ...);
    #define             GIMP_WIDGETS_ERROR
    GQuark              gimp_widgets_error_quark            (void);

## Description

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

## Details

### enum GimpWidgetsError

    typedef enum {
      GIMP_WIDGETS_PARSE_ERROR
    } GimpWidgetsError;

`GIMP_WIDGETS_PARSE_ERROR` |

### 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.

`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.

`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`.

`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).

`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.

`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);

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.

`adjustment` : | Returns the spinbutton's GtkAdjustment.
`value` : | The initial value of the spinbutton.
`lower` : | The lower boundary.
`upper` : | The uppper 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.

### GIMP_SCALE_ENTRY_LABEL()

    #define             GIMP_SCALE_ENTRY_LABEL(adj)

`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)

`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)

`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)

`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)

`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.

`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.

`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.

`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 GIMP 2.2

### gimp_scale_entry_get_logarithmic ()

    gboolean            gimp_scale_entry_get_logarithmic    (GtkObject *adjustment);

`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 GIMP 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.

`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)

`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)

`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)

`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.

`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)

`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.

`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.

`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.

`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()`.

`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).

`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);

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

### gimp_double_adjustment_update ()

    void                gimp_double_adjustment_update       (GtkAdjustment *adjustment,
                                                             gpointer data);

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

### gimp_table_attach_aligned ()

    GtkWidget *         gimp_table_attach_aligned           (GtkTable *table,
                                                             gint column,
                                                             gint row,
                                                             const gchar *label_text,
                                                             gfloat xalign,
                                                             gfloat yalign,
                                                             GtkWidget *widget,
                                                             gint colspan,
                                                             gboolean left_align);

Note that the `label_text` can be `NULL` and that the widget will be attached starting at (`column` + 1) in this case, too.

`table` : | The GtkTable the widgets will be attached to.
`column` : | The column to start with.
`row` : | The row to attach the widgets.
`label_text` : | The text for the GtkLabel which will be attached left of the widget.
`xalign` : | The horizontal alignment of the GtkLabel.
`yalign` : | The vertival alignment of the GtkLabel.
`widget` : | The GtkWidget to attach right of the label.
`colspan` : | The number of columns the widget will use.
`left_align` : | `TRUE` if the widget should be left-aligned.
Returns : | The created GtkLabel.

### gimp_label_set_attributes ()

    void                gimp_label_set_attributes           (GtkLabel *label,
                                                             ...);

Sets Pango attributes on a GtkLabel in a more convenient way than `gtk_label_set_attributes()`.

This function is useful if you want to change the font attributes of a GtkLabel. This is an alternative to using PangoMarkup which is slow to parse and akward to handle in an i18n-friendly way.

The attributes are set on the complete label, from start to end. If you need to set attributes on part of the label, you will have to use the PangoAttributes API directly.

`label` : | a GtkLabel
`...` : | a list of PangoAttrType and value pairs terminated by -1.

Since GIMP 2.2

### GIMP_WIDGETS_ERROR

    #define GIMP_WIDGETS_ERROR (gimp_widgets_error_quark ())

The GIMP widgets error domain.

Since GIMP 2.8

### 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.