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