## 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_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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 2.4

### 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 corresonding to checked state. |

#### Returns

The newly created GtkCheckButton widget.

Since GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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` is deprecated and should not be used in newly-written code.

GIMP 2.10

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 GIMP 2.4

### gimp_prop_enum_icon_box_new ()

    GtkWidget *
    gimp_prop_enum_icon_box_new (GObject *config,
                                 const gchar *property_name,
                                 const gchar *stock_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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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 GIMP 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. |
scale_limits | `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 GIMP 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 GIMP 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 GIMP 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` is deprecated and should not be used in newly-written code.

GIMP 2.10

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 GIMP 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 GIMP 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 GIMP 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 GIMP 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` is deprecated 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 GIMP 2.4

## Types and Values