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