GimpPropWidgets: GIMP Widgets Library Reference Manual

GimpPropWidgets

GimpPropWidgets — Editable views on GObject properties.

Functions

GtkWidget *	gimp_prop_boolean_combo_box_new ()
GtkWidget *	gimp_prop_boolean_radio_frame_new ()
GtkWidget *	gimp_prop_check_button_new ()
GtkWidget *	gimp_prop_color_area_new ()
gboolean	gimp_prop_coordinates_connect ()
GtkWidget *	gimp_prop_coordinates_new ()
GtkWidget *	gimp_prop_entry_new ()
GtkWidget *	gimp_prop_pointer_combo_box_new ()
GtkWidget *	gimp_prop_enum_check_button_new ()
GtkWidget *	gimp_prop_enum_combo_box_new ()
GtkWidget *	gimp_prop_enum_label_new ()
GtkWidget *	gimp_prop_enum_radio_box_new ()
GtkWidget *	gimp_prop_enum_radio_frame_new ()
GtkWidget *	gimp_prop_enum_stock_box_new ()
GtkWidget *	gimp_prop_enum_icon_box_new ()
GtkWidget *	gimp_prop_expander_new ()
GtkWidget *	gimp_prop_file_chooser_button_new ()
GtkWidget *	gimp_prop_file_chooser_button_new_with_dialog ()
GtkWidget *	gimp_prop_hscale_new ()
GtkWidget *	gimp_prop_icon_image_new ()
GtkWidget *	gimp_prop_int_combo_box_new ()
GtkWidget *	gimp_prop_label_new ()
GtkWidget *	gimp_prop_memsize_entry_new ()
GtkObject *	gimp_prop_opacity_entry_new ()
GtkWidget *	gimp_prop_path_editor_new ()
GtkObject *	gimp_prop_scale_entry_new ()
GtkWidget *	gimp_prop_size_entry_new ()
GtkWidget *	gimp_prop_spin_button_new ()
GtkWidget *	gimp_prop_stock_image_new ()
GtkWidget *	gimp_prop_string_combo_box_new ()
GtkTextBuffer *	gimp_prop_text_buffer_new ()
GtkWidget *	gimp_prop_unit_combo_box_new ()
GtkWidget *	gimp_prop_unit_menu_new ()

Description

Editable views on GObject properties.

Functions

gimp_prop_boolean_combo_box_new ()

GtkWidget *
gimp_prop_boolean_combo_box_new (GObject *config,
                                 const gchar *property_name,
                                 const gchar *true_text,
                                 const gchar *false_text);

Creates a GtkComboBox widget to display and set the specified boolean property. The combo box will have two entries, one displaying the true_text label, the other displaying the false_text label.

Parameters

config	Object to which property is attached.
property_name	Name of boolean property controlled by combo box.
true_text	Label used for entry corresponding to `TRUE` value.
false_text	Label used for entry corresponding to `FALSE` value.

Returns

The newly created GtkComboBox widget.

Since: 2.4

gimp_prop_boolean_radio_frame_new ()

GtkWidget *
gimp_prop_boolean_radio_frame_new (GObject *config,
                                   const gchar *property_name,
                                   const gchar *title,
                                   const gchar *true_text,
                                   const gchar *false_text);

Creates a pair of radio buttons which function to set and display the specified boolean property. If title is NULL, the property_name 's nick will be used as label of the returned frame.

Parameters

config	Object to which property is attached.
property_name	Name of boolean property controlled by the radio buttons.
title	Label for the frame.
true_text	Label for the button corresponding to `TRUE`.
false_text	Label for the button corresponding to `FALSE`.

Returns

A GimpFrame containing the radio buttons.

Since: 2.4

gimp_prop_check_button_new ()

GtkWidget *
gimp_prop_check_button_new (GObject *config,
                            const gchar *property_name,
                            const gchar *label);

Creates a GtkCheckButton that displays and sets the specified boolean property. If label is NULL, the property_name 's nick will be used as label of the returned button.

Parameters

config	Object to which property is attached.
property_name	Name of boolean property controlled by checkbutton.
label	Label to give checkbutton (including mnemonic).

Returns

The newly created GtkCheckButton widget.

Since: 2.4

gimp_prop_color_area_new ()

GtkWidget *
gimp_prop_color_area_new (GObject *config,
                          const gchar *property_name,
                          gint width,
                          gint height,
                          GimpColorAreaType type);

Creates a GimpColorArea to set and display the value of an RGB property.

Parameters

config	Object to which property is attached.
property_name	Name of RGB property.
width	Width of color area.
height	Height of color area.
type	How transparency is represented.

Returns

A new GimpColorArea widget.

Since: 2.4

gimp_prop_coordinates_connect ()

gboolean
gimp_prop_coordinates_connect (GObject *config,
                               const gchar *x_property_name,
                               const gchar *y_property_name,
                               const gchar *unit_property_name,
                               GtkWidget *sizeentry,
                               GtkWidget *chainbutton,
                               gdouble xresolution,
                               gdouble yresolution);

gimp_prop_coordinates_new ()

GtkWidget *
gimp_prop_coordinates_new (GObject *config,
                           const gchar *x_property_name,
                           const gchar *y_property_name,
                           const gchar *unit_property_name,
                           const gchar *unit_format,
                           GimpSizeEntryUpdatePolicy update_policy,
                           gdouble xresolution,
                           gdouble yresolution,
                           gboolean has_chainbutton);

Creates a GimpSizeEntry to set and display two double or int properties, which will usually represent X and Y coordinates, and their associated unit property.

Parameters

config	Object to which property is attached.
x_property_name	Name of int or double property for X coordinate.
y_property_name	Name of int or double property for Y coordinate.
unit_property_name	Name of unit property.
unit_format	A printf-like unit-format string as is used with `gimp_unit_menu_new()`.
update_policy	How the automatic pixel <-> real-world-unit calculations should be done.
xresolution	The resolution (in dpi) for the X coordinate.
yresolution	The resolution (in dpi) for the Y coordinate.
has_chainbutton	Whether to add a chainbutton to the size entry.

Returns

A new GimpSizeEntry widget.

Since: 2.4

gimp_prop_entry_new ()

GtkWidget *
gimp_prop_entry_new (GObject *config,
                     const gchar *property_name,
                     gint max_len);

Creates a GtkEntry to set and display the value of the specified string property.

Parameters

config	Object to which property is attached.
property_name	Name of string property.
max_len	Maximum allowed length of string.

Returns

A new GtkEntry widget.

Since: 2.4

gimp_prop_pointer_combo_box_new ()

GtkWidget *
gimp_prop_pointer_combo_box_new (GObject *config,
                                 const gchar *property_name,
                                 GimpIntStore *store);

Creates a GimpIntComboBox widget to display and set the specified property. The contents of the widget are determined by store , which should be created using gimp_int_store_new(). Values are GType/gpointer data, and therefore must be stored in the "user-data" column, instead of the usual "value" column.

Parameters

config	Object to which property is attached.
property_name	Name of GType/gpointer property controlled by combo box.
store	GimpIntStore holding list of labels, values, etc.

Returns

The newly created GimpIntComboBox widget.

Since: 2.10

gimp_prop_enum_check_button_new ()

GtkWidget *
gimp_prop_enum_check_button_new (GObject *config,
                                 const gchar *property_name,
                                 const gchar *label,
                                 gint false_value,
                                 gint true_value);

Creates a GtkCheckButton that displays and sets the specified property of type Enum. Note that this widget only allows two values for the enum, one corresponding to the "checked" state and the other to the "unchecked" state. If label is NULL, the property_name 's nick will be used as label of the returned button.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by checkbutton.
label	Label to give checkbutton (including mnemonic).
false_value	Enum value corresponding to unchecked state.
true_value	Enum value corresponding to checked state.

Returns

The newly created GtkCheckButton widget.

Since: 2.4

gimp_prop_enum_combo_box_new ()

GtkWidget *
gimp_prop_enum_combo_box_new (GObject *config,
                              const gchar *property_name,
                              gint minimum,
                              gint maximum);

Creates a GimpIntComboBox widget to display and set the specified enum property. The mimimum_value and maximum_value give the possibility of restricting the allowed range to a subset of the enum. If the two values are equal (e.g., 0, 0), then the full range of the Enum is used.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by combo box.
minimum	Smallest allowed value of enum.
maximum	Largest allowed value of enum.

Returns

The newly created GimpEnumComboBox widget.

Since: 2.4

gimp_prop_enum_label_new ()

GtkWidget *
gimp_prop_enum_label_new (GObject *config,
                          const gchar *property_name);

Parameters

config	Object to which property is attached.
property_name	Name of enum property to be displayed.

Returns

The newly created GimpEnumLabel widget.

Since: 2.4

gimp_prop_enum_radio_box_new ()

GtkWidget *
gimp_prop_enum_radio_box_new (GObject *config,
                              const gchar *property_name,
                              gint minimum,
                              gint maximum);

Creates a group of radio buttons which function to set and display the specified enum property. The minimum and maximum arguments allow only a subset of the enum to be used. If the two arguments are equal (e.g., 0, 0), then the full range of the enum will be used. If you want to assign a label to the group of radio buttons, use gimp_prop_enum_radio_frame_new() instead of this function.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by the radio buttons.
minimum	Smallest value of enum to be included.
maximum	Largest value of enum to be included.

Returns

A GtkVBox containing the radio buttons.

Since: 2.4

gimp_prop_enum_radio_frame_new ()

GtkWidget *
gimp_prop_enum_radio_frame_new (GObject *config,
                                const gchar *property_name,
                                const gchar *title,
                                gint minimum,
                                gint maximum);

Creates a group of radio buttons which function to set and display the specified enum property. The minimum and maximum arguments allow only a subset of the enum to be used. If the two arguments are equal (e.g., 0, 0), then the full range of the enum will be used. If title is NULL, the property_name 's nick will be used as label of the returned frame.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by the radio buttons.
title	Label for the frame holding the buttons
minimum	Smallest value of enum to be included.
maximum	Largest value of enum to be included.

Returns

A GimpFrame containing the radio buttons.

Since: 2.4

gimp_prop_enum_stock_box_new ()

GtkWidget *
gimp_prop_enum_stock_box_new (GObject *config,
                              const gchar *property_name,
                              const gchar *stock_prefix,
                              gint minimum,
                              gint maximum);

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

Creates a horizontal box of radio buttons with stock icons, which function to set and display the value of the specified Enum property. The stock_id for each icon is created by appending the enum_value's nick to the given stock_prefix . See gimp_enum_stock_box_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by the radio buttons.
stock_prefix	The prefix of the group of stock ids to use.
minimum	Smallest value of enum to be included.
maximum	Largest value of enum to be included.

Returns

A libgimpwidgets-gimpenumstockbox containing the radio buttons.

Since: 2.4

gimp_prop_enum_icon_box_new ()

GtkWidget *
gimp_prop_enum_icon_box_new (GObject *config,
                             const gchar *property_name,
                             const gchar *icon_prefix,
                             gint minimum,
                             gint maximum);

Creates a horizontal box of radio buttons with named icons, which function to set and display the value of the specified Enum property. The icon name for each icon is created by appending the enum_value's nick to the given icon_prefix . See gimp_enum_icon_box_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of enum property controlled by the radio buttons.
icon_prefix	The prefix of the group of icon names to use.
minimum	Smallest value of enum to be included.
maximum	Largest value of enum to be included.

Returns

A libgimpwidgets-gimpenumiconbox containing the radio buttons.

Since: 2.10

gimp_prop_expander_new ()

GtkWidget *
gimp_prop_expander_new (GObject *config,
                        const gchar *property_name,
                        const gchar *label);

Creates a GtkExpander controlled by the specified boolean property. A value of TRUE for the property corresponds to the expanded state for the widget. If label is NULL, the property_name 's nick will be used as label of the returned widget.

Parameters

config	Object to which property is attached.
property_name	Name of boolean property.
label	Label for expander.

Returns

A new GtkExpander widget.

Since: 2.4

gimp_prop_file_chooser_button_new ()

GtkWidget *
gimp_prop_file_chooser_button_new (GObject *config,
                                   const gchar *property_name,
                                   const gchar *title,
                                   GtkFileChooserAction action);

Creates a GtkFileChooserButton to edit the specified path property.

Note that GtkFileChooserButton implements the GtkFileChooser interface; you can use the GtkFileChooser API with it.

Parameters

config	object to which property is attached.
property_name	name of path property.
title	the title of the browse dialog.
action	the open mode for the widget.

Returns

A new GtkFileChooserButton.

Since: 2.4

gimp_prop_file_chooser_button_new_with_dialog ()

GtkWidget *
gimp_prop_file_chooser_button_new_with_dialog
                               (GObject *config,
                                const gchar *property_name,
                                GtkWidget *dialog);

Creates a GtkFileChooserButton to edit the specified path property.

The button uses dialog as it's file-picking window. Note that dialog must be a GtkFileChooserDialog (or subclass) and must not have GTK_DIALOG_DESTROY_WITH_PARENT set.

Note that GtkFileChooserButton implements the GtkFileChooser interface; you can use the GtkFileChooser API with it.

Parameters

config	object to which property is attached.
property_name	name of path property.
dialog	the GtkFileChooserDialog widget to use.

Returns

A new GtkFileChooserButton.

Since: 2.4

gimp_prop_hscale_new ()

GtkWidget *
gimp_prop_hscale_new (GObject *config,
                      const gchar *property_name,
                      gdouble step_increment,
                      gdouble page_increment,
                      gint digits);

Creates a horizontal scale to control the value of the specified integer or double property.

Parameters

config	Object to which property is attached.
property_name	Name of integer or double property controlled by the scale.
step_increment	Step size.
page_increment	Page size.
digits	Number of digits after decimal point to display.

Returns

A new GtkScale.

Since: 2.4

gimp_prop_icon_image_new ()

GtkWidget *
gimp_prop_icon_image_new (GObject *config,
                          const gchar *property_name,
                          GtkIconSize icon_size);

Creates a widget to display a icon image representing the value of the specified string property, which should encode an icon name. See gtk_image_new_from_icon_name() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of string property.
icon_size	Size of desired icon image.

Returns

A new GtkImage widget.

Since: 2.10

gimp_prop_int_combo_box_new ()

GtkWidget *
gimp_prop_int_combo_box_new (GObject *config,
                             const gchar *property_name,
                             GimpIntStore *store);

Creates a GimpIntComboBox widget to display and set the specified property. The contents of the widget are determined by store , which should be created using gimp_int_store_new().

Parameters

config	Object to which property is attached.
property_name	Name of int property controlled by combo box.
store	GimpIntStore holding list of labels, values, etc.

Returns

The newly created GimpIntComboBox widget.

Since: 2.4

gimp_prop_label_new ()

GtkWidget *
gimp_prop_label_new (GObject *config,
                     const gchar *property_name);

Creates a GtkLabel to display the value of the specified property. The property should be a string property or at least transformable to a string. If the user should be able to edit the string, use gimp_prop_entry_new() instead.

Parameters

config	Object to which property is attached.
property_name	Name of string property.

Returns

A new GtkLabel widget.

Since: 2.4

gimp_prop_memsize_entry_new ()

GtkWidget *
gimp_prop_memsize_entry_new (GObject *config,
                             const gchar *property_name);

Creates a GimpMemsizeEntry (spin button and option menu) to set and display the value of the specified memsize property. See gimp_memsize_entry_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of memsize property.

Returns

A new GimpMemsizeEntry.

Since: 2.4

gimp_prop_opacity_entry_new ()

GtkObject *
gimp_prop_opacity_entry_new (GObject *config,
                             const gchar *property_name,
                             GtkTable *table,
                             gint column,
                             gint row,
                             const gchar *label);

Creates a libgimpwidgets-gimpscaleentry (slider and spin button) to set and display the value of the specified double property, which should represent an "opacity" variable with range 0 to 100. See gimp_scale_entry_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of double property controlled by the spin button.
table	The GtkTable the widgets will be attached to.
column	The column to start with.
row	The row to attach the widgets.
label	The text for the GtkLabel which will appear left of the GtkHScale.

Returns

The GtkSpinButton's GtkAdjustment.

Since: 2.4

gimp_prop_path_editor_new ()

GtkWidget *
gimp_prop_path_editor_new (GObject *config,
                           const gchar *path_property_name,
                           const gchar *writable_property_name,
                           const gchar *filesel_title);

gimp_prop_scale_entry_new ()

GtkObject *
gimp_prop_scale_entry_new (GObject *config,
                           const gchar *property_name,
                           GtkTable *table,
                           gint column,
                           gint row,
                           const gchar *label,
                           gdouble step_increment,
                           gdouble page_increment,
                           gint digits,
                           gboolean limit_scale,
                           gdouble lower_limit,
                           gdouble upper_limit);

Creates a libgimpwidgets-gimpscaleentry (slider and spin button) to set and display the value of the specified double property. See gimp_scale_entry_new() for more information. If label is NULL, the property_name 's nick will be used as label of the returned object.

Note that the scale_limits boolean is the inverse of gimp_scale_entry_new()'s "constrain" parameter.

Parameters

config	Object to which property is attached.
property_name	Name of double property controlled by the spin button.
table	The GtkTable the widgets will be attached to.
column	The column to start with.
row	The row to attach the widgets.
label	The text for the GtkLabel which will appear left of the GtkHScale.
step_increment	Step size.
page_increment	Page size.
digits	Number of digits after decimal point to display.
limit_scale	`FALSE` if the range of possible values of the GtkHScale should be the same as of the GtkSpinButton.
lower_limit	The scale's lower boundary if `scale_limits` is `TRUE`.
upper_limit	The scale's upper boundary if `scale_limits` is `TRUE`.

Returns

The GtkSpinButton's GtkAdjustment.

Since: 2.4

gimp_prop_size_entry_new ()

GtkWidget *
gimp_prop_size_entry_new (GObject *config,
                          const gchar *property_name,
                          gboolean property_is_pixel,
                          const gchar *unit_property_name,
                          const gchar *unit_format,
                          GimpSizeEntryUpdatePolicy update_policy,
                          gdouble resolution);

Creates a GimpSizeEntry to set and display the specified double or int property, and its associated unit property. Note that this function is only suitable for creating a size entry holding a single value. Use gimp_prop_coordinates_new() to create a size entry holding two values.

Parameters

config	Object to which property is attached.
property_name	Name of int or double property.
property_is_pixel	When `TRUE`, the property value is in pixels, and in the selected unit otherwise.
unit_property_name	Name of unit property.
unit_format	A printf-like unit-format string as is used with `gimp_unit_menu_new()`.
update_policy	How the automatic pixel <-> real-world-unit calculations should be done.
resolution	The resolution (in dpi) for the field.

Returns

A new GimpSizeEntry widget.

Since: 2.4

gimp_prop_spin_button_new ()

GtkWidget *
gimp_prop_spin_button_new (GObject *config,
                           const gchar *property_name,
                           gdouble step_increment,
                           gdouble page_increment,
                           gint digits);

Creates a spin button to set and display the value of the specified double property.

Parameters

config	Object to which property is attached.
property_name	Name of double property controlled by the spin button.
step_increment	Step size.
page_increment	Page size.
digits	Number of digits after decimal point to display.

Returns

A new libgimpwidgets-gimpspinbutton.

Since: 2.4

gimp_prop_stock_image_new ()

GtkWidget *
gimp_prop_stock_image_new (GObject *config,
                           const gchar *property_name,
                           GtkIconSize icon_size);

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

Creates a widget to display a stock image representing the value of the specified string property, which should encode a Stock ID. See gtk_image_new_from_stock() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of string property.
icon_size	Size of desired stock image.

Returns

A new GtkImage widget.

Since: 2.4

gimp_prop_string_combo_box_new ()

GtkWidget *
gimp_prop_string_combo_box_new (GObject *config,
                                const gchar *property_name,
                                GtkTreeModel *model,
                                gint id_column,
                                gint label_column);

Creates a GimpStringComboBox widget to display and set the specified property. The contents of the widget are determined by store .

Parameters

config	Object to which property is attached.
property_name	Name of int property controlled by combo box.
model	GtkTreeStore holding list of values
id_column	column in `store` that holds string IDs
label_column	column in `store` that holds labels to use in the combo-box

Returns

The newly created GimpStringComboBox widget.

Since: 2.4

gimp_prop_text_buffer_new ()

GtkTextBuffer *
gimp_prop_text_buffer_new (GObject *config,
                           const gchar *property_name,
                           gint max_len);

Creates a GtkTextBuffer to set and display the value of the specified string property. Unless the string is expected to contain multiple lines or a large amount of text, use gimp_prop_entry_new() instead. See GtkTextView for information on how to insert a text buffer into a visible widget.

If max_len is 0 or negative, the text buffer allows an unlimited number of characters to be entered.

Parameters

config	Object to which property is attached.
property_name	Name of string property.
max_len	Maximum allowed length of text (in characters).

Returns

A new GtkTextBuffer.

Since: 2.4

gimp_prop_unit_combo_box_new ()

GtkWidget *
gimp_prop_unit_combo_box_new (GObject *config,
                              const gchar *property_name);

Creates a GimpUnitComboBox to set and display the value of a Unit property. See gimp_unit_combo_box_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of Unit property.

Returns

A new GimpUnitComboBox widget.

Since: 2.8

gimp_prop_unit_menu_new ()

GtkWidget *
gimp_prop_unit_menu_new (GObject *config,
                         const gchar *property_name,
                         const gchar *unit_format);

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

Creates a GimpUnitMenu to set and display the value of a Unit property. See gimp_unit_menu_new() for more information.

Parameters

config	Object to which property is attached.
property_name	Name of Unit property.
unit_format	A printf-like format string which is used to create the unit strings.

Returns

A new GimpUnitMenu widget.

Since: 2.4