Functions

	cairo_set_focus_line_pattern (cr, widget)
	cairo_set_source_color (cr, color, config, softproof, widget)
	cairo_surface_create_from_pixbuf (pixbuf)
	context_help (widget)
	coordinates_new (unit, unit_format, menu_show_pixels, menu_show_percent, spinbutton_width, update_policy, chainbutton_active, chain_constrains_ratio, xlabel, x, xres, lower_boundary_x, upper_boundary_x, xsize_0, xsize_100, ylabel, y, yres, lower_boundary_y, upper_boundary_y, ysize_0, ysize_100)
	double_adjustment_update (adjustment)
	enum_icon_box_new (enum_type, icon_prefix, icon_size, callback, *callback_data)
	enum_icon_box_new_with_range (enum_type, minimum, maximum, icon_prefix, icon_size, callback, *callback_data)
	enum_icon_box_set_child_padding (icon_box, xpad, ypad)
	enum_icon_box_set_icon_size (icon_box, icon_size)
	enum_radio_box_new (enum_type, callback, *callback_data)
	enum_radio_box_new_with_range (enum_type, minimum, maximum, callback, *callback_data)
	enum_radio_frame_new (enum_type, label_widget, callback, *callback_data)
	enum_radio_frame_new_with_range (enum_type, minimum, maximum, label_widget, callback, *callback_data)
	event_triggers_context_menu (event, on_release)
	float_adjustment_update (adjustment)
	get_monitor_at_pointer ()
	grid_attach_aligned (grid, left, top, label_text, label_xalign, label_yalign, widget, widget_columns)
	help_connect (widget, tooltip, help_func, help_id, *help_data)
	help_id_quark ()
	help_set_help_data (widget, tooltip, help_id)
	help_set_help_data_with_markup (widget, tooltip, help_id)
	icons_init ()
	icons_set_icon_theme (path)
	init (prog_name)
	int_adjustment_update (adjustment)
	int_radio_group_set_active (radio_button, item_data)
	monitor_get_color_profile (monitor)
	proc_view_new (procedure_name)
	prop_boolean_combo_box_new (config, property_name, true_text, false_text)
	prop_boolean_radio_frame_new (config, property_name, title, true_text, false_text)
	prop_brush_chooser_new (config, property_name, chooser_title)
	prop_check_button_new (config, property_name, label)
	prop_choice_combo_box_new (config, property_name)
	prop_choice_radio_frame_new (config, property_name)
	prop_color_area_new (config, property_name, width, height, type)
	prop_color_select_new (config, property_name, width, height, type)
	prop_coordinates_connect (config, x_property_name, y_property_name, unit_property_name, sizeentry, chainbutton, xresolution, yresolution)
	prop_coordinates_new (config, x_property_name, y_property_name, unit_property_name, unit_format, update_policy, xresolution, yresolution, has_chainbutton)
	prop_drawable_chooser_new (config, property_name, chooser_title)
	prop_entry_new (config, property_name, max_len)
	prop_enum_check_button_new (config, property_name, label, false_value, true_value)
	prop_enum_combo_box_new (config, property_name, minimum, maximum)
	prop_enum_icon_box_new (config, property_name, icon_prefix, minimum, maximum)
	prop_enum_label_new (config, property_name)
	prop_enum_radio_box_new (config, property_name, minimum, maximum)
	prop_enum_radio_frame_new (config, property_name, title, minimum, maximum)
	prop_expander_new (config, property_name, label)
	prop_file_chooser_button_new (config, property_name, title, action)
	prop_file_chooser_button_new_with_dialog (config, property_name, dialog)
	prop_file_chooser_new (config, property_name, label, title)
	prop_font_chooser_new (config, property_name, chooser_title)
	prop_gradient_chooser_new (config, property_name, chooser_title)
	prop_hscale_new (config, property_name, step_increment, page_increment, digits)
	prop_icon_image_new (config, property_name, icon_size)
	prop_image_chooser_new (config, property_name, chooser_title)
	prop_int_combo_box_new (config, property_name, store)
	prop_int_radio_frame_new (config, property_name, title, store)
	prop_item_chooser_new (config, property_name, chooser_title)
	prop_label_color_new (config, property_name, editable)
	prop_label_entry_new (config, property_name, max_len)
	prop_label_new (config, property_name)
	prop_label_spin_new (config, property_name, digits)
	prop_memsize_entry_new (config, property_name)
	prop_palette_chooser_new (config, property_name, chooser_title)
	prop_path_editor_new (config, path_property_name, writable_property_name, filechooser_title)
	prop_pattern_chooser_new (config, property_name, chooser_title)
	prop_pointer_combo_box_new (config, property_name, store)
	prop_scale_entry_new (config, property_name, label, factor, limit_scale, lower_limit, upper_limit)
	prop_size_entry_new (config, property_name, property_is_pixel, unit_property_name, unit_format, update_policy, resolution)
	prop_spin_button_new (config, property_name, step_increment, page_increment, digits)
	prop_spin_scale_new (config, property_name, step_increment, page_increment, digits)
	prop_string_combo_box_new (config, property_name, model, id_column, label_column)
	prop_switch_new (config, property_name, label)
	prop_text_buffer_new (config, property_name, max_len)
	prop_toggle_new (config, property_name, icon_name, label)
	prop_unit_combo_box_new (config, property_name)
	prop_widget_set_factor (widget, factor, step_increment, page_increment, digits)
	query_boolean_box (title, parent, help_func, help_id, icon_name, message, true_button, false_button, object, signal, callback, *data)
	query_double_box (title, parent, help_func, help_id, message, initial, lower, upper, digits, object, signal, callback, *data)
	query_int_box (title, parent, help_func, help_id, message, initial, lower, upper, object, signal, callback, *data)
	query_size_box (title, parent, help_func, help_id, message, initial, lower, upper, digits, unit, resolution, dot_for_dot, object, signal, callback, *data)
	query_string_box (title, parent, help_func, help_id, message, initial, object, signal, callback, *data)
	radio_button_update (widget)
	random_seed_new (seed, random_seed)
	scroll_adjustment_values (sevent, hadj, vadj)
	standard_help_func (help_id, help_data)
	toggle_button_update (widget)
	uint_adjustment_update (adjustment)
	widget_animation_enabled ()
	widget_free_native_handle (widget, window_handle)
	widget_get_color_profile (widget)
	widget_get_color_transform (widget, config, src_profile, src_format, dest_format, softproof_profile, proof_intent, proof_bpc)
	widget_get_monitor (widget)
	widget_get_render_space (widget, config)
	widget_set_native_handle (widget, window_handle)
	widget_track_monitor (widget, monitor_changed_callback, *user_data)
	widgets_error_quark ()
	window_set_transient (window)
	window_set_transient_for (window, handle)
	window_set_transient_for_display (window, display)
	zoom_button_new (model, zoom_type, icon_size)

Details

GimpUi.cairo_set_focus_line_pattern(cr, widget)

Parameters:

• cr (cairo.Context) – Cairo context

• widget (Gtk.Widget) – widget to draw the focus indicator on

Returns:

True if the widget style has a focus line pattern, False otherwise

Return type:

bool

Sets color and dash pattern for stroking a focus line on the given cr. The line pattern is taken from widget.

New in version 2.6.

GimpUi.cairo_set_source_color(cr, color, config, softproof, widget)

Parameters:

• cr (cairo.Context) – Cairo context.

• color (Gegl.Color) – the [class`Gegl`.Color] to use as source pattern within cr.

• config (Gimp.ColorConfig) – the color management settings.

• softproof (bool) – whether the color must also be soft-proofed.

• widget (Gtk.Widget or None) – [class`Gtk`.Widget] to draw the focus indicator on.

Sets color as the source pattern within cr, taking into account the profile of the [class`Gdk`.Monitor] which widget is displayed on.

If config is set, the color configuration as set by the user will be used, in particular using any custom monitor profile set in preferences (overriding system-set profile). If no such custom profile is set, it will use the profile of the monitor widget is displayed on and will default to sRGB if widget is None.

Use [func`Gimp`.get_color_configuration] to retrieve the user [class`Gimp`.ColorConfig].

TODO: softproof is currently unused.

New in version 3.0.

GimpUi.cairo_surface_create_from_pixbuf(pixbuf)

Parameters:

pixbuf (GdkPixbuf.Pixbuf) – a GdkPixbuf.Pixbuf

Returns:

a cairo.Surface.

Return type:

cairo.Surface

Create a Cairo image surface from a GdkPixbuf.Pixbuf.

You should avoid calling this function as there are probably more efficient ways of achieving the result you are looking for.

New in version 2.6.

GimpUi.context_help(widget)

Parameters:

widget (Gtk.Widget) – Any Gtk.Widget on the screen.

This function invokes the context help inspector.

The mouse cursor will turn turn into a question mark and the user can click on any widget of the application which started the inspector.

If the widget the user clicked on has a help_id string attached (see GimpUi.help_set_help_data()), the corresponding help page will be displayed. Otherwise the help system will ascend the widget hierarchy until it finds an attached help_id string (which should be the case at least for every window/dialog).

GimpUi.coordinates_new(unit, unit_format, menu_show_pixels, menu_show_percent, spinbutton_width, update_policy, chainbutton_active, chain_constrains_ratio, xlabel, x, xres, lower_boundary_x, upper_boundary_x, xsize_0, xsize_100, ylabel, y, yres, lower_boundary_y, upper_boundary_y, ysize_0, ysize_100)

Parameters:

• unit (Gimp.Unit) – The initial unit of the #GimpUnitMenu.

• unit_format (str) – A printf-like unit-format string as is used with gimp_unit_menu_new().

• menu_show_pixels (bool) – True if the #GimpUnitMenu should contain an item for Gimp.UnitID.PIXEL.

• menu_show_percent (bool) – True if the #GimpUnitMenu should contain an item for Gimp.UnitID.PERCENT.

• spinbutton_width (int) – The horizontal size of the GimpUi.SizeEntry's Gtk.SpinButton's.

• update_policy (GimpUi.SizeEntryUpdatePolicy) – The update policy for the GimpUi.SizeEntry.

• chainbutton_active (bool) – True if the attached GimpUi.ChainButton should be active.

• chain_constrains_ratio (bool) – True if the chainbutton should constrain the fields’ aspect ratio. If False, the values will be constrained.

• xlabel (str) – The label for the X coordinate.

• x (float) – The initial value of the X coordinate.

• xres (float) – The horizontal resolution in DPI.

• lower_boundary_x (float) – The lower boundary of the X coordinate.

• upper_boundary_x (float) – The upper boundary of the X coordinate.

• xsize_0 (float) – The X value which will be treated as 0%.

• xsize_100 (float) – The X value which will be treated as 100%.

• ylabel (str) – The label for the Y coordinate.

• y (float) – The initial value of the Y coordinate.

• yres (float) – The vertical resolution in DPI.

• lower_boundary_y (float) – The lower boundary of the Y coordinate.

• upper_boundary_y (float) – The upper boundary of the Y coordinate.

• ysize_0 (float) – The Y value which will be treated as 0%.

• ysize_100 (float) – The Y value which will be treated as 100%.

Returns:

The new GimpUi.SizeEntry.

Return type:

Gtk.Widget

Convenience function that creates a GimpUi.SizeEntry with two fields for x/y coordinates/sizes with a GimpUi.ChainButton attached to constrain either the two fields’ values or the ratio between them.

GimpUi.double_adjustment_update(adjustment)

Parameters:

adjustment (Gtk.Adjustment) – A Gtk.Adjustment.

Returns:

A return location for the adjustment's value.

Return type:

data: float

GimpUi.enum_icon_box_new(enum_type, icon_prefix, icon_size, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• icon_prefix (str) – the prefix of the group of icon names to use.

• icon_size (Gtk.IconSize) – the icon size for the icons

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new horizontal Gtk.Box holding a group of Gtk.RadioButtons.

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Creates a horizontal box of radio buttons with named icons. The icon name for each icon is created by appending the enum_value’s nick to the given icon_prefix.

New in version 2.10.

GimpUi.enum_icon_box_new_with_range(enum_type, minimum, maximum, icon_prefix, icon_size, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• minimum (int) – the minumim enum value

• maximum (int) – the maximum enum value

• icon_prefix (str) – the prefix of the group of icon names to use.

• icon_size (Gtk.IconSize) – the icon size for the icons

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new horizontal Gtk.Box holding a group of Gtk.RadioButtons.

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Just like GimpUi.enum_icon_box_new(), this function creates a group of radio buttons, but additionally it supports limiting the range of available enum values.

New in version 2.10.

GimpUi.enum_icon_box_set_child_padding(icon_box, xpad, ypad)

Parameters:

• icon_box (Gtk.Widget) – an icon box widget

• xpad (int) – horizontal padding

• ypad (int) – vertical padding

Sets the padding of all buttons in a box created by GimpUi.enum_icon_box_new().

New in version 2.10.

GimpUi.enum_icon_box_set_icon_size(icon_box, icon_size)

Parameters:

• icon_box (Gtk.Widget) – an icon box widget

• icon_size (Gtk.IconSize) – the Gtk.IconSize enum

Sets the icon size of all buttons in a box created by GimpUi.enum_icon_box_new().

New in version 3.0.

GimpUi.enum_radio_box_new(enum_type, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new Gtk.Box holding a group of Gtk.RadioButtons.

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Creates a new group of Gtk.RadioButtons representing the enum values. A group of radiobuttons is a good way to represent enums with up to three or four values. Often it is better to use a GimpUi.EnumComboBox instead.

New in version 2.4.

GimpUi.enum_radio_box_new_with_range(enum_type, minimum, maximum, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• minimum (int) – the minimum enum value

• maximum (int) – the maximum enum value

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new vertical Gtk.Box holding a group of Gtk.RadioButtons

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Just like GimpUi.enum_radio_box_new(), this function creates a group of radio buttons, but additionally it supports limiting the range of available enum values.

New in version 2.4.

GimpUi.enum_radio_frame_new(enum_type, label_widget, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• label_widget (Gtk.Widget or None) – a Gtk.Widget to use as label for the frame that will hold the radio box.

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new Gtk.Frame holding a group of Gtk.RadioButtons.

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Calls GimpUi.enum_radio_box_new() and puts the resulting vbox into a Gtk.Frame.

New in version 2.4.

GimpUi.enum_radio_frame_new_with_range(enum_type, minimum, maximum, label_widget, callback, *callback_data)

Parameters:

• enum_type (GObject.GType) – the GObject.GType of an enum.

• minimum (int) – the minimum enum value

• maximum (int) – the maximum enum value

• label_widget (Gtk.Widget or None) – a widget to put into the frame that will hold the radio box.

• callback (GObject.Callback or None) – a callback to connect to the “toggled” signal of each Gtk.RadioButton that is created.

• callback_data (object or None) – data to pass to the callback.

Returns:

a new Gtk.Frame holding a group of Gtk.RadioButtons.

first_button:

Returns the first button in the created group.

Return type:

(Gtk.Widget, first_button: Gtk.Widget)

Calls GimpUi.enum_radio_box_new_with_range() and puts the resulting vertical box into a Gtk.Frame.

New in version 2.4.

GimpUi.event_triggers_context_menu(event, on_release)

Parameters:

• event (Gdk.Event) – The Gdk.Event to verify.

• on_release (bool) – Whether a menu is triggered on a button release event instead of a press event.

Returns:

True if the event should trigger a context menu.

Return type:

bool

Alternative of Gdk.Event.triggers_context_menu() with the additional feature of allowing a menu triggering to happen on a button release event. All the other rules on whether event should trigger a contextual menu are exactly the same. Only the swapping to release state as additional feature is different.

New in version 3.0.

GimpUi.float_adjustment_update(adjustment)

Parameters:

adjustment (Gtk.Adjustment) – A Gtk.Adjustment.

Returns:

A return location for the adjustment's value.

Return type:

data: float

GimpUi.get_monitor_at_pointer()

Returns:

the Gdk.Monitor where the pointer is.

Return type:

Gdk.Monitor

GimpUi.grid_attach_aligned(grid, left, top, label_text, label_xalign, label_yalign, widget, widget_columns)

Parameters:

• grid (Gtk.Grid) – The Gtk.Grid the widgets will be attached to.

• left (int) – The column to start with.

• top (int) – The row to attach the widgets.

• label_text (str) – The text for the Gtk.Label which will be attached left of the widget.

• label_xalign (float) – The horizontal alignment of the Gtk.Label.

• label_yalign (float) – The vertical alignment of the Gtk.Label.

• widget (Gtk.Widget) – The Gtk.Widget to attach right of the label.

• widget_columns (int) – The number of columns the widget will use.

Returns:

The created Gtk.Label.

Return type:

Gtk.Widget

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

GimpUi.help_connect(widget, tooltip, help_func, help_id, *help_data)

Parameters:

• widget (Gtk.Widget) – The widget you want to connect the help accelerator for. Will be a Gtk.Window in most cases.

• tooltip (str or None) – The text for this widget’s tooltip. For windows, you usually want to set None.

• help_func (GimpUi.HelpFunc) – The function which will be called if the user presses “F1”.

• help_id (str) – The help_id which will be passed to help_func.

• help_data (object or None) – The help_data pointer which will be passed to help_func.

Note that this function is automatically called by all libgimp dialog constructors. You only have to call it for windows/dialogs you created “manually”.

Most of the time, what you want to call for non-windows widgets is simply [func`GimpUi`.help_set_help_data]. Yet if you need to set up an help_func, call gimp_help_connect instead. Note that gimp_help_set_help_data is implied, so you don’t have to call it too.

GimpUi.help_id_quark()

Returns:

The #GQuark.

Return type:

int

This function returns the #GQuark which should be used as key when attaching help IDs to widgets and objects.

New in version 2.2.

GimpUi.help_set_help_data(widget, tooltip, help_id)

Parameters:

• widget (Gtk.Widget) – The Gtk.Widget you want to set a tooltip and/or help_id for.

• tooltip (str or None) – The text for this widget’s tooltip (or None).

• help_id (str) – The help_id for the #GtkTipsQuery tooltips inspector.

The reason why we don’t use Gtk.Widget.set_tooltip_text() is that elements in the GIMP user interface should, if possible, also have a help_id set for context-sensitive help.

This function can be called with None for tooltip. Use this feature if you want to set a help link for a widget which shouldn’t have a visible tooltip.

GimpUi.help_set_help_data_with_markup(widget, tooltip, help_id)

Parameters:

• widget (Gtk.Widget) – The Gtk.Widget you want to set a tooltip and/or help_id for.

• tooltip (str) – The markup for this widget’s tooltip (or None).

• help_id (str) – The help_id for the #GtkTipsQuery tooltips inspector.

Just like GimpUi.help_set_help_data(), but supports to pass text which is marked up with Pango text markup language.

New in version 2.6.

GimpUi.icons_init()

Initializes the GIMP stock icon factory.

You don’t need to call this function as GimpUi.init() already does this for you.

GimpUi.icons_set_icon_theme(path)

Parameters:

path (Gio.File) –

Return type:

bool

GimpUi.init(prog_name)

Parameters:

prog_name (str) – The name of the plug-in which will be passed as argv[0] to gtk_init(). It’s a convention to use the name of the executable and _not_ the PDB procedure name.

This function initializes GTK with [func`Gtk`.init], as well as GEGL and babl.

It also sets up various other things so that the plug-in user looks and behaves like the GIMP core. This includes selecting the GTK theme and setting up the help system as chosen in GIMP preferences. Any plug-in that provides a user interface should call this function.

It can safely be called more than once. Calls after the first return quickly with no effect.

GimpUi.int_adjustment_update(adjustment)

Parameters:

adjustment (Gtk.Adjustment) – A Gtk.Adjustment.

Returns:

A return location for the adjustment's value.

Return type:

data: int

Note that the Gtk.Adjustment's value (which is a float) will be rounded with RINT().

GimpUi.int_radio_group_set_active(radio_button, item_data)

Parameters:

• radio_button (Gtk.RadioButton) – Pointer to a Gtk.RadioButton.

• item_data (int) – The item_data of the radio button you want to select.

Calls Gtk.ToggleButton.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.

GimpUi.monitor_get_color_profile(monitor)

Parameters:

monitor (Gdk.Monitor) – a Gdk.Monitor

Returns:

the monitor’s Gimp.ColorProfile, or None.

Return type:

Gimp.ColorProfile or None

This function returns the Gimp.ColorProfile of monitor or None if there is no profile configured.

New in version 3.0.

GimpUi.proc_view_new(procedure_name)

Parameters:

procedure_name (str) – The name of a procedure.

Returns:

a new widget providing a view on a GIMP procedure

Return type:

Gtk.Widget

New in version 2.4.

GimpUi.prop_boolean_combo_box_new(config, property_name, true_text, false_text)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property controlled by combo box.

• true_text (str) – Label used for entry corresponding to True value.

• false_text (str) – Label used for entry corresponding to False value.

Returns:

The newly created Gtk.ComboBox widget.

Return type:

Gtk.Widget

Creates a Gtk.ComboBox 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.

New in version 2.4.

GimpUi.prop_boolean_radio_frame_new(config, property_name, title, true_text, false_text)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property controlled by the radio buttons.

• title (str or None) – Label for the frame.

• true_text (str) – Label for the button corresponding to True.

• false_text (str) – Label for the button corresponding to False.

Returns:

A GimpUi.Frame containing the radio buttons.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_brush_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Brush] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.BrushChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.BrushChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_check_button_new(config, property_name, label)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property controlled by checkbutton.

• label (str or None) – Label to give checkbutton (including mnemonic).

Returns:

The newly created Gtk.CheckButton widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_choice_combo_box_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of Gimp.Choice property controlled by combo box.

Returns:

The newly created GimpUi.StringComboBox widget.

Return type:

Gtk.Widget

Creates a GimpUi.StringComboBox widget to display and set the specified property.

GimpUi.prop_choice_radio_frame_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of Gimp.Choice property controlled by radio buttons.

Returns:

The newly created GimpUi.IntRadioFrame widget.

Return type:

Gtk.Widget

Creates a [class`GimpUi`.IntRadioFrame] widget to display and set the specified [class`Gimp`.Choice] property.

GimpUi.prop_color_area_new(config, property_name, width, height, type)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of Gegl.Color property.

• width (int) – Width of color area.

• height (int) – Height of color area.

• type (GimpUi.ColorAreaType) – How transparency is represented.

Returns:

A new GimpUi.ColorArea widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_color_select_new(config, property_name, width, height, type)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of [class`Gegl`.Color] property.

• width (int) – Width of the colorpreview in pixels.

• height (int) – Height of the colorpreview in pixels.

• type (GimpUi.ColorAreaType) – How transparency is represented.

Returns:

A new GimpUi.ColorButton widget.

Return type:

Gtk.Widget

Creates a GimpUi.ColorButton to set and display the value of a color property.

New in version 3.0.

GimpUi.prop_coordinates_connect(config, x_property_name, y_property_name, unit_property_name, sizeentry, chainbutton, xresolution, yresolution)

Parameters:

• config (GObject.Object) –

• x_property_name (str) –

• y_property_name (str) –

• unit_property_name (str) –

• sizeentry (Gtk.Widget) –

• chainbutton (Gtk.Widget) –

• xresolution (float) –

• yresolution (float) –

Return type:

bool

GimpUi.prop_coordinates_new(config, x_property_name, y_property_name, unit_property_name, unit_format, update_policy, xresolution, yresolution, has_chainbutton)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• x_property_name (str) – Name of int or double property for X coordinate.

• y_property_name (str) – Name of int or double property for Y coordinate.

• unit_property_name (str) – Name of unit property.

• unit_format (str) – A printf-like unit-format string as is used with gimp_unit_menu_new().

• update_policy (GimpUi.SizeEntryUpdatePolicy) – How the automatic pixel <-> real-world-unit calculations should be done.

• xresolution (float) – The resolution (in dpi) for the X coordinate.

• yresolution (float) – The resolution (in dpi) for the Y coordinate.

• has_chainbutton (bool) – Whether to add a chainbutton to the size entry.

Returns:

A new GimpUi.SizeEntry widget.

Return type:

Gtk.Widget

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

If unit_format is None, the unit will default to inch. Otherwise it must be the name of a property of type Gimp.ParamUnit:

New in version 2.4.

GimpUi.prop_drawable_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Drawable] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.DrawableChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.DrawableChooser] controlled by the specified property.

New in version 3.0.

Deprecated since version 3.2: Use GimpUi.prop_item_chooser_new().

GimpUi.prop_entry_new(config, property_name, max_len)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of string property.

• max_len (int) – Maximum allowed length of string.

Returns:

A new Gtk.Entry widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_enum_check_button_new(config, property_name, label, false_value, true_value)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by checkbutton.

• label (str or None) – Label to give checkbutton (including mnemonic).

• false_value (int) – Enum value corresponding to unchecked state.

• true_value (int) – Enum value corresponding to checked state.

Returns:

The newly created Gtk.CheckButton widget.

Return type:

Gtk.Widget

Creates a Gtk.CheckButton 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 None, the property_name's nick will be used as label of the returned button.

New in version 2.4.

GimpUi.prop_enum_combo_box_new(config, property_name, minimum, maximum)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by combo box.

• minimum (int) – Smallest allowed value of enum.

• maximum (int) – Largest allowed value of enum.

Returns:

The newly created GimpUi.EnumComboBox widget.

Return type:

Gtk.Widget

Creates a GimpUi.IntComboBox 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.

New in version 2.4.

GimpUi.prop_enum_icon_box_new(config, property_name, icon_prefix, minimum, maximum)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by the radio buttons.

• icon_prefix (str) – The prefix of the group of icon names to use.

• minimum (int) – Smallest value of enum to be included.

• maximum (int) – Largest value of enum to be included.

Returns:

A #libgimpwidgets-gimpenumiconbox containing the radio buttons.

Return type:

Gtk.Widget

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 GimpUi.enum_icon_box_new() for more information.

New in version 2.10.

GimpUi.prop_enum_label_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property to be displayed.

Returns:

The newly created GimpUi.EnumLabel widget.

Return type:

Gtk.Widget

New in version 2.4.

GimpUi.prop_enum_radio_box_new(config, property_name, minimum, maximum)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by the radio buttons.

• minimum (int) – Smallest value of enum to be included.

• maximum (int) – Largest value of enum to be included.

Returns:

A Gtk.Box containing the radio buttons.

Return type:

Gtk.Widget

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 GimpUi.prop_enum_radio_frame_new() instead of this function.

New in version 2.4.

GimpUi.prop_enum_radio_frame_new(config, property_name, title, minimum, maximum)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by the radio buttons.

• title (str or None) – Label for the frame holding the buttons

• minimum (int) – Smallest value of enum to be included.

• maximum (int) – Largest value of enum to be included.

Returns:

A GimpUi.Frame containing the radio buttons.

Return type:

Gtk.Widget

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 None, the property_name's nick will be used as label of the returned frame.

New in version 2.4.

GimpUi.prop_expander_new(config, property_name, label)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property.

• label (str or None) – Label for expander.

Returns:

A new Gtk.Expander widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_file_chooser_button_new(config, property_name, title, action)

Parameters:

• config (GObject.Object) – object to which property is attached.

• property_name (str) – name of path property.

• title (str or None) – the title of the browse dialog.

• action (Gtk.FileChooserAction) – the open mode for the widget.

Returns:

A new Gtk.FileChooserButton.

Return type:

Gtk.Widget

Creates a Gtk.FileChooserButton to edit the specified path property. property_name must represent either a GIMP_PARAM_SPEC_CONFIG_PATH or a G_PARAM_SPEC_OBJECT where value_type == G_TYPE_FILE.

Note that Gtk.FileChooserButton implements the Gtk.FileChooser interface; you can use the Gtk.FileChooser API with it.

New in version 2.4.

GimpUi.prop_file_chooser_button_new_with_dialog(config, property_name, dialog)

Parameters:

• config (GObject.Object) – object to which property is attached.

• property_name (str) – name of path property.

• dialog (Gtk.Widget) – the Gtk.FileChooserDialog widget to use.

Returns:

A new Gtk.FileChooserButton.

Return type:

Gtk.Widget

Creates a Gtk.FileChooserButton to edit the specified path property.

The button uses dialog as it’s file-picking window. Note that dialog must be a Gtk.FileChooserDialog (or subclass) and must not have Gtk.DialogFlags.DESTROY_WITH_PARENT set.

Note that Gtk.FileChooserButton implements the Gtk.FileChooser interface; you can use the Gtk.FileChooser API with it.

New in version 2.4.

GimpUi.prop_file_chooser_new(config, property_name, label, title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a %GimpParamSpecFile property.

• label (str or None) – Label of the widget.

• title (str or None) – Title of the file dialog.

Returns:

A new Gtk.FileChooserButton.

Return type:

Gtk.Widget

Creates a [class`GimpUi`.FileChooser] to edit the specified file property. property_name must be a %GimpParamSpecFile with an action other than [enum`Gimp`.FileChooserAction.ANY].

If label is None, property_name's nick text will be used instead.

New in version 3.0.

GimpUi.prop_font_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Font] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.FontChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.FontChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_gradient_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Gradient] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.GradientChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.GradientChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_hscale_new(config, property_name, step_increment, page_increment, digits)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of integer or double property controlled by the scale.

• step_increment (float) – Step size.

• page_increment (float) – Page size.

• digits (int) – Number of digits after decimal point to display.

Returns:

A new Gtk.Scale.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_icon_image_new(config, property_name, icon_size)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of string property.

• icon_size (Gtk.IconSize) – Size of desired icon image.

Returns:

A new Gtk.Image widget.

Return type:

Gtk.Widget

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.

New in version 2.10.

GimpUi.prop_image_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Image] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.ImageChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.ImageChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_int_combo_box_new(config, property_name, store)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of int property controlled by combo box.

• store (GimpUi.IntStore) – GimpUi.IntStore holding list of labels, values, etc.

Returns:

The newly created GimpUi.IntComboBox widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_int_radio_frame_new(config, property_name, title, store)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of enum property controlled by the radio buttons.

• title (str or None) – Label for the frame holding the buttons

• store (GimpUi.IntStore) – GimpUi.IntStore holding list of labels, values, etc.

Returns:

A GimpUi.Frame containing the radio buttons.

Return type:

Gtk.Widget

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

New in version 3.0.

GimpUi.prop_item_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Item] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.ItemChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.ItemChooser] controlled by the specified property.

New in version 3.2.

GimpUi.prop_label_color_new(config, property_name, editable)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of RGB property.

• editable (bool) – Whether the widget should allow color editability.

Returns:

A new GimpUi.LabelColor widget.

Return type:

Gtk.Widget

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

New in version 3.0.

GimpUi.prop_label_entry_new(config, property_name, max_len)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of string property.

• max_len (int) – Maximum allowed length of string (set to negative for no maximum).

Returns:

A new Gtk.Entry widget.

Return type:

Gtk.Widget

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

New in version 3.0.

GimpUi.prop_label_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of string property.

Returns:

A new Gtk.Label widget.

Return type:

Gtk.Widget

Creates a Gtk.Label 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 GimpUi.prop_entry_new() instead.

New in version 2.4.

GimpUi.prop_label_spin_new(config, property_name, digits)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) –

• digits (int) – Number of digits after decimal point to display.

Returns:

A new #libgimpwidgets-gimpspinbutton.

Return type:

Gtk.Widget

Creates a GimpUi.LabelSpin to set and display the value of the specified double property.

New in version 2.4.

GimpUi.prop_memsize_entry_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of memsize property.

Returns:

A new GimpUi.MemsizeEntry.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_palette_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Palette] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.PaletteChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.PaletteChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_path_editor_new(config, path_property_name, writable_property_name, filechooser_title)

Parameters:

• config (GObject.Object) – object to which property is attached.

• path_property_name (str) – name of path property.

• writable_property_name (str) – name of writable path property.

• filechooser_title (str) – window title of Gtk.FileChooserDialog widget.

Returns:

A new GimpUi.PathEditor.

Return type:

Gtk.Widget

Creates a GimpUi.PathEditor to edit the specified path and writable path properties.

GimpUi.prop_pattern_chooser_new(config, property_name, chooser_title)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of a [class`Gimp`.Pattern] property.

• chooser_title (str or None) – title for the poppable dialog.

Returns:

A new [class`GimpUi`.PatternChooser].

Return type:

Gtk.Widget

Creates a [class`GimpUi`.PatternChooser] controlled by the specified property.

New in version 3.0.

GimpUi.prop_pointer_combo_box_new(config, property_name, store)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of GObject.GType/object property controlled by combo box.

• store (GimpUi.IntStore) – GimpUi.IntStore holding list of labels, values, etc.

Returns:

The newly created GimpUi.IntComboBox widget.

Return type:

Gtk.Widget

Creates a GimpUi.IntComboBox widget to display and set the specified property. The contents of the widget are determined by store, which should be created using GimpUi.IntStore.new(). Values are GObject.GType/object data, and therefore must be stored in the “user-data” column, instead of the usual “value” column.

New in version 2.10.

GimpUi.prop_scale_entry_new(config, property_name, label, factor, limit_scale, lower_limit, upper_limit)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of integer or double property controlled by the scale.

• label (str or None) – The text for the Gtk.Label which will appear left of the Gtk.Scale.

• factor (float) – Optional multiplier to convert property_name's range into the GimpUi.ScaleEntry's range. The common usage is to set 1.0. For non-double properties, no other values than 1.0 are acceptable.

• limit_scale (bool) – False if the range of possible values of the Gtk.Scale should be the same as of the Gtk.SpinButton.

• lower_limit (float) – The scale’s lower boundary if scale_limits is True.

• upper_limit (float) – The scale’s upper boundary if scale_limits is True.

Returns:

The newly allocated GimpUi.ScaleEntry.

Return type:

Gtk.Widget

Creates a GimpUi.ScaleEntry (slider and spin button) to set and display the value of a specified int or double property with sensible default settings depending on the range (decimal places, increments, etc.). These settings can be overridden by the relevant widget methods.

If label is None, the property_name's nick will be used as label of the returned object.

If factor is not 1.0, the widget’s range will be computed based of property_name's range multiplied by factor. A typical usage would be to display a [0.0, 1.0] range as [0.0, 100.0] by setting 100.0 as factor.

See GimpUi.ScaleEntry.set_bounds() for more information on limit_scale, lower_limit and upper_limit.

New in version 2.4.

GimpUi.prop_size_entry_new(config, property_name, property_is_pixel, unit_property_name, unit_format, update_policy, resolution)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of int or double property.

• property_is_pixel (bool) – When True, the property value is in pixels, and in the selected unit otherwise.

• unit_property_name (str) – Name of unit property.

• unit_format (str) – A printf-like unit-format string as is used with gimp_unit_menu_new().

• update_policy (GimpUi.SizeEntryUpdatePolicy) – How the automatic pixel <-> real-world-unit calculations should be done.

• resolution (float) – The resolution (in dpi) for the field.

Returns:

A new GimpUi.SizeEntry widget.

Return type:

Gtk.Widget

Creates a GimpUi.SizeEntry 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 GimpUi.prop_coordinates_new() to create a size entry holding two values.

New in version 2.4.

GimpUi.prop_spin_button_new(config, property_name, step_increment, page_increment, digits)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of double property controlled by the spin button.

• step_increment (float) – Step size.

• page_increment (float) – Page size.

• digits (int) – Number of digits after decimal point to display.

Returns:

A new #libgimpwidgets-gimpspinbutton.

Return type:

Gtk.Widget

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

If you wish to change the widget’s range relatively to the property_name's range, use GimpUi.prop_widget_set_factor().

New in version 2.4.

GimpUi.prop_spin_scale_new(config, property_name, step_increment, page_increment, digits)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of double or int property controlled by the spin button.

• step_increment (float) – Step size.

• page_increment (float) – Page size.

• digits (int) – Number of digits after decimal point to display. This is only used for double properties. In case of int properties, digits = 0 is implied.

Returns:

A new #libgimpwidgets-gimpspinbutton.

Return type:

Gtk.Widget

Creates a spin scale to set and display the value of the specified int or double property.

By default, the property_name's nick will be used as label of the returned widget. Use GimpUi.SpinScale.set_label() to change this.

If you wish to change the widget’s range relatively to the property_name's range, use GimpUi.prop_widget_set_factor().

New in version 3.0.

GimpUi.prop_string_combo_box_new(config, property_name, model, id_column, label_column)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of int property controlled by combo box.

• model (Gtk.TreeModel) – Gtk.TreeStore holding list of values

• id_column (int) – column in store that holds string IDs

• label_column (int) – column in store that holds labels to use in the combo-box

Returns:

The newly created GimpUi.StringComboBox widget.

Return type:

Gtk.Widget

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

New in version 2.4.

GimpUi.prop_switch_new(config, property_name, label)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property controlled by checkbutton.

• label (str) – Label to give checkbutton (including mnemonic).

Returns:

The newly created box containing a Gtk.Switch.

label_out:

The generated Gtk.Label

switch_out:

The generated Gtk.Switch

Return type:

(Gtk.Widget, label_out: Gtk.Widget, switch_out: Gtk.Widget)

Creates a Gtk.Box with a switch and a label that displays and sets the specified boolean property. If label is None, the property_name's nick will be used as label.

New in version 3.0.

GimpUi.prop_text_buffer_new(config, property_name, max_len)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of string property.

• max_len (int) – Maximum allowed length of text (in characters).

Returns:

A new Gtk.TextBuffer.

Return type:

Gtk.TextBuffer

Creates a Gtk.TextBuffer 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 GimpUi.prop_entry_new() instead. See Gtk.TextView 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.

New in version 2.4.

GimpUi.prop_toggle_new(config, property_name, icon_name, label)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of boolean property controlled by the toggle button.

• icon_name (str) – Icon to display in the toggle.

• label (str) – Label to give the toggle (including mnemonic).

Returns:

The newly Gtk.ToggleButton.

image_out:

The generated Gtk.Image if icon_name was not None.

Return type:

(Gtk.Widget, image_out: Gtk.Widget)

Creates a [class`Gtk`.ToggleButton] that sets the specified boolean property.

If icon_name is None, label will be used. If label is None too, the property_name's nick will be used as label.

New in version 3.2.

GimpUi.prop_unit_combo_box_new(config, property_name)

Parameters:

• config (GObject.Object) – Object to which property is attached.

• property_name (str) – Name of Unit property.

Returns:

A new GimpUi.UnitComboBox widget.

Return type:

Gtk.Widget

Creates a GimpUi.UnitComboBox to set and display the value of a Unit property. See GimpUi.UnitComboBox.new() for more information.

New in version 2.8.

GimpUi.prop_widget_set_factor(widget, factor, step_increment, page_increment, digits)

Parameters:

• widget (Gtk.Widget) – Property widget.

• factor (float) – Multiplier to convert the widget's range and map appropriately to the property’s range it is associated to.

• step_increment (float) – Step size.

• page_increment (float) – Page size.

• digits (int) – Number of digits after decimal point to display.

Change the display factor of the property widget relatively to the property it was bound to. Currently the only types of widget accepted as input are those created by GimpUi.prop_spin_scale_new() and GimpUi.prop_spin_button_new().

If factor is 1.0, then the config property and the widget display map exactly.

If factor is not 1.0, the widget’s range will be computed based of property_name's range multiplied by factor. A typical usage would be to display a [0.0, 1.0] range as [0.0, 100.0] by setting 100.0 as factor. This function can only be used with double properties.

The step_increment and page_increment can be set to new increments you want to get for this new range. If you set them to 0.0 or negative values, new increments will be computed based on the new factor and previous factor.

New in version 3.0.

GimpUi.query_boolean_box(title, parent, help_func, help_id, icon_name, message, true_button, false_button, object, signal, callback, *data)

Parameters:

• title (str) – The query box dialog’s title.

• parent (Gtk.Widget) – The dialog’s parent widget.

• help_func (GimpUi.HelpFunc) – The help function to show this dialog’s help page.

• help_id (str) – A string identifying this dialog’s help page.

• icon_name (str) – An icon name to specify an icon to appear on the left on the dialog’s message.

• message (str) – A string which will be shown in the query box.

• true_button (str) – The string to be shown in the dialog’s left button.

• false_button (str) – The string to be shown in the dialog’s right button.

• object (GObject.Object) – The object this query box is associated with.

• signal (str) – The object’s signal which will cause the query box to be closed.

• callback (GimpUi.QueryBooleanCallback) – The function which will be called when the user clicks one of the buttons.

• data (object or None) – The callback’s user data.

Returns:

A pointer to the new Gtk.Dialog.

Return type:

Gtk.Widget

Creates a new Gtk.Dialog that asks the user to do a boolean decision.

GimpUi.query_double_box(title, parent, help_func, help_id, message, initial, lower, upper, digits, object, signal, callback, *data)

Parameters:

• title (str) – The query box dialog’s title.

• parent (Gtk.Widget) – The dialog’s parent widget.

• help_func (GimpUi.HelpFunc) – The help function to show this dialog’s help page.

• help_id (str) – A string identifying this dialog’s help page.

• message (str) – A string which will be shown above the dialog’s entry widget.

• initial (float) – The initial value.

• lower (float) – The lower boundary of the range of possible values.

• upper (float) – The upper boundray of the range of possible values.

• digits (int) – The number of decimal digits the Gtk.SpinButton will provide.

• object (GObject.Object) – The object this query box is associated with.

• signal (str) – The object’s signal which will cause the query box to be closed.

• callback (GimpUi.QueryDoubleCallback) – The function which will be called when the user selects “OK”.

• data (object or None) – The callback’s user data.

Returns:

A pointer to the new Gtk.Dialog.

Return type:

Gtk.Widget

Creates a new Gtk.Dialog that queries the user for a double value.

GimpUi.query_int_box(title, parent, help_func, help_id, message, initial, lower, upper, object, signal, callback, *data)

Parameters:

• title (str) – The query box dialog’s title.

• parent (Gtk.Widget) – The dialog’s parent widget.

• help_func (GimpUi.HelpFunc) – The help function to show this dialog’s help page.

• help_id (str) – A string identifying this dialog’s help page.

• message (str) – A string which will be shown above the dialog’s entry widget.

• initial (int) – The initial value.

• lower (int) – The lower boundary of the range of possible values.

• upper (int) – The upper boundray of the range of possible values.

• object (GObject.Object) – The object this query box is associated with.

• signal (str) – The object’s signal which will cause the query box to be closed.

• callback (GimpUi.QueryIntCallback) – The function which will be called when the user selects “OK”.

• data (object or None) – The callback’s user data.

Returns:

A pointer to the new Gtk.Dialog.

Return type:

Gtk.Widget

Creates a new Gtk.Dialog that queries the user for an integer value.

GimpUi.query_size_box(title, parent, help_func, help_id, message, initial, lower, upper, digits, unit, resolution, dot_for_dot, object, signal, callback, *data)

Parameters:

• title (str) – The query box dialog’s title.

• parent (Gtk.Widget) – The dialog’s parent widget.

• help_func (GimpUi.HelpFunc) – The help function to show this dialog’s help page.

• help_id (str) – A string identifying this dialog’s help page.

• message (str) – A string which will be shown above the dialog’s entry widget.

• initial (float) – The initial value.

• lower (float) – The lower boundary of the range of possible values.

• upper (float) – The upper boundray of the range of possible values.

• digits (int) – The number of decimal digits the GimpUi.SizeEntry provide in “pixel” mode.

• unit (Gimp.Unit) – The unit initially shown by the #GimpUnitMenu.

• resolution (float) – The resolution (in dpi) which will be used for pixel/unit calculations.

• dot_for_dot (bool) – True if the #GimpUnitMenu’s initial unit should be “pixels”.

• object (GObject.Object) – The object this query box is associated with.

• signal (str) – The object’s signal which will cause the query box to be closed.

• callback (GimpUi.QuerySizeCallback) – The function which will be called when the user selects “OK”.

• data (object or None) – The callback’s user data.

Returns:

A pointer to the new Gtk.Dialog.

Return type:

Gtk.Widget

Creates a new Gtk.Dialog that queries the user for a size using a GimpUi.SizeEntry.

GimpUi.query_string_box(title, parent, help_func, help_id, message, initial, object, signal, callback, *data)

Parameters:

• title (str) – The query box dialog’s title.

• parent (Gtk.Widget) – The dialog’s parent widget.

• help_func (GimpUi.HelpFunc) – The help function to show this dialog’s help page.

• help_id (str) – A string identifying this dialog’s help page.

• message (str) – A string which will be shown above the dialog’s entry widget.

• initial (str) – The initial value.

• object (GObject.Object) – The object this query box is associated with.

• signal (str) – The object’s signal which will cause the query box to be closed.

• callback (GimpUi.QueryStringCallback) – The function which will be called when the user selects “OK”.

• data (object or None) – The callback’s user data.

Returns:

A pointer to the new Gtk.Dialog.

Return type:

Gtk.Widget

Creates a new Gtk.Dialog that queries the user for a string value.

GimpUi.radio_button_update(widget)

Parameters:

widget (Gtk.Widget) – A Gtk.RadioButton.

Returns:

A return location for the value of GPOINTER_TO_INT (g_object_get_data (@widget, "gimp-item-data")).

Return type:

data: int

GimpUi.random_seed_new(seed, random_seed)

Parameters:

• seed (int) – A pointer to the variable which stores the random seed.

• random_seed (bool) – A pointer to a boolean indicating whether seed should be initialised randomly or not.

Returns:

A Gtk.Box containing a Gtk.SpinButton for the seed and a Gtk.Button for setting a random seed.

Return type:

Gtk.Widget

Creates a widget that allows the user to control how the random number generator is initialized.

GimpUi.scroll_adjustment_values(sevent, hadj, vadj)

Parameters:

• sevent (Gdk.EventScroll) – A Gdk.EventScroll

• hadj (Gtk.Adjustment or None) – Horizontal adjustment

• vadj (Gtk.Adjustment or None) – Vertical adjustment

Returns:

hvalue:

Return location for horizontal value, or None

vvalue:

Return location for vertical value, or None

Return type:

(hvalue: float, vvalue: float)

GimpUi.standard_help_func(help_id, help_data)

Parameters:

• help_id (str) – A unique help identifier.

• help_data (object or None) – The help_data passed to GimpUi.help_connect().

This is the standard GIMP help function which does nothing but calling Gimp.help(). It is the right function to use in almost all cases.

GimpUi.toggle_button_update(widget)

Parameters:

widget (Gtk.Widget) – A Gtk.ToggleButton.

Returns:

A return location for the value of Gtk.ToggleButton.get_active().

Return type:

data: bool

GimpUi.uint_adjustment_update(adjustment)

Parameters:

adjustment (Gtk.Adjustment) – A Gtk.Adjustment.

Returns:

A return location for the adjustment's value.

Return type:

data: int

Note that the Gtk.Adjustment's value (which is a float) will be rounded with (int) (value + 0.5).

GimpUi.widget_animation_enabled()

Returns:

True if the user has animations enabled on their system

Return type:

bool

This function attempts to read the user’s system preference for showing animation. It can be used to turn off or hide unnecessary animations such as the scrolling credits or Easter Egg animations.

New in version 3.0.

GimpUi.widget_free_native_handle(widget, window_handle)

Parameters:

• widget (Gtk.Widget) – a widget we got a handle for.

• window_handle (GLib.Bytes) – same pointer previously passed to [func`GimpUi`.widget_set_native_handle].

Returns:

same pointer previously passed to [func`GimpUi`.widget_set_native_handle].

Return type:

window_handle: GLib.Bytes

Disposes a widget’s native window handle created, possibly asynchronously, by a previous call to [func`GimpUi`.widget_set_native_handle].

Depending on the platform, this function may also execute other necessary clean up so you should call it and not simply free the [struct`GLib`.Bytes] yourself.

You should call this function in the dispose() implementation of your custom widget **before** chaining up with the parent class’ dispose() call. The first call to the parent’s dispose() will destroy the GdkWindow which will prevent this function to do part of its cleanup when run after. This may result in crashes on some platforms.

This is safe to call even if deferenced window_handle is None, i.e. that you don’t have to check if the window handle was actually set.

New in version 3.0.

GimpUi.widget_get_color_profile(widget)

Parameters:

widget (Gtk.Widget) – a Gtk.Widget

Returns:

widget's monitor’s Gimp.ColorProfile, or None.

Return type:

Gimp.ColorProfile or None

This function returns the Gimp.ColorProfile of the monitor widget is currently displayed on, or None if there is no profile configured.

New in version 3.0.

GimpUi.widget_get_color_transform(widget, config, src_profile, src_format, dest_format, softproof_profile, proof_intent, proof_bpc)

Parameters:

• widget (Gtk.Widget) – a Gtk.Widget

• config (Gimp.ColorConfig) – a Gimp.ColorConfig

• src_profile (Gimp.ColorProfile) – a Gimp.ColorProfile

• src_format (Babl.Object) – Babl.Object format for the transform’s source pixels

• dest_format (Babl.Object) – Babl.Object format for the transforms’s destination pixels

• softproof_profile (Gimp.ColorProfile) –

• proof_intent (Gimp.ColorRenderingIntent) –

• proof_bpc (bool) –

Returns:

the Gimp.ColorTransform.

Return type:

Gimp.ColorTransform or None

This function returns the Gimp.ColorTransform that transforms pixels from src_profile to the profile of the Gdk.Monitor the widget is displayed on.

New in version 2.10.

GimpUi.widget_get_monitor(widget)

Parameters:

widget (Gtk.Widget) – a Gtk.Widget.

Returns:

the Gdk.Monitor where widget is current displayed on.

Return type:

Gdk.Monitor

GimpUi.widget_get_render_space(widget, config)

Parameters:

• widget (Gtk.Widget) –

• config (Gimp.ColorConfig) –

Return type:

Babl.Object

GimpUi.widget_set_native_handle(widget, window_handle)

Parameters:

• widget (Gtk.Widget) – a widget to get a handle for.

• window_handle (GLib.Bytes) – pointer to store the native handle as a [struct`GLib`.Bytes].

Returns:

pointer to store the native handle as a [struct`GLib`.Bytes].

Return type:

window_handle: GLib.Bytes

This function is to be used in custom widget construction to store the window handle representing widget into window_handle so that it can later be reused to set other windows as transient to this one (even across processes, such as in-between plug-ins), e.g. using [func`GimpUi`.window_set_transient_for].

Depending on the platform, the actual content of window_handle can be various types and should therefore be considered an opaque data. Moreover it may be filled asynchronously in a callback, so you should not assume that window_handle is set after running this function.

This convenience function is safe to use even before widget is visible as it will set the handle once it is mapped.

Free window_handle on dispose() or finalize() with [func`GimpUi`.widget_free_native_handle].

New in version 3.0.

GimpUi.widget_track_monitor(widget, monitor_changed_callback, *user_data)

Parameters:

• widget (Gtk.Widget) – a Gtk.Widget

• monitor_changed_callback (GObject.Callback) – the callback when widget's monitor changes

• user_data (object or None) – data passed to monitor_changed_callback

This function behaves as if Gtk.Widget had a signal

GtkWidget::monitor_changed(Gtk.Widget *widget, object user_data)

That is emitted whenever widget's toplevel window is moved from one monitor to another. This function automatically connects to the right toplevel Gtk.Window, even across moving widget between toplevel windows.

Note that this function tracks the toplevel, not widget itself, so all a window’s widgets are always considered to be on the same monitor. This is because this function is mainly used for fetching the new monitor’s color profile, and it makes little sense to use different profiles for the widgets of one window.

New in version 2.10.

GimpUi.widgets_error_quark()

Returns:

the #GQuark that defines the GIMP widgets error domain.

Return type:

int

This function is never called directly. Use GIMP_WIDGETS_ERROR() instead.

GimpUi.window_set_transient(window)

Parameters:

window (Gtk.Window) – the Gtk.Window that should become transient

Indicates to the window manager that window is a transient dialog associated with the GIMP window that the plug-in has been started from. See also GimpUi.window_set_transient_for_display().

New in version 2.4.

GimpUi.window_set_transient_for(window, handle)

Parameters:

• window (Gtk.Window) – the Gtk.Window that should become transient

• handle (GLib.Bytes) – handle of the window that should become the parent

Indicates to the window manager that window is a transient dialog to the window identified by handle.

Note that handle is an opaque data, which you should not try to construct yourself or make sense of. It may be different things depending on the OS or even the display server. You should only use a handle returned by [func`Gimp`.progress_get_window_handle], [method`Gimp`.:ref:xlib.Display.get_window_handle <xlib.Display.fields>] or [method`GimpUi`.Dialog.get_native_handle].

Most of the time you will want to use the convenience function [func`GimpUi`.window_set_transient].

New in version 3.0.

GimpUi.window_set_transient_for_display(window, display)

Parameters:

• window (Gtk.Window) – the Gtk.Window that should become transient

• display (Gimp.Display) – display of the image window that should become the parent

Indicates to the window manager that window is a transient dialog associated with the GIMP image window that is identified by its display. See [method`Gdk`.Window.set_transient_for] for more information.

Most of the time you will want to use the convenience function [func`GimpUi`.window_set_transient].

New in version 2.4.

GimpUi.zoom_button_new(model, zoom_type, icon_size)

Parameters:

• model (GimpUi.ZoomModel) – a GimpUi.ZoomModel

• zoom_type (GimpUi.ZoomType) –

• icon_size (Gtk.IconSize) – use 0 for a button with text labels

Returns:

a newly created Gtk.Button

Since GIMP 2.4

Return type:

Gtk.Widget