Callbacks¶

	`AssistantPageFunc` (current_page, *data)
	`CellAllocCallback` (renderer, cell_area, cell_background, *data)
	`CellCallback` (renderer, *data)
	`CellLayoutDataFunc` (cell_layout, cell, tree_model, iter, *data)
	`CustomAllocateFunc` (widget, width, height, baseline)
	`CustomFilterFunc` (item, *user_data)
	`CustomMeasureFunc` (widget, orientation, for_size)
	`CustomRequestModeFunc` (widget)
	`DrawingAreaDrawFunc` (drawing_area, cr, width, height, *user_data)
	`EntryCompletionMatchFunc` (completion, key, iter, *user_data)
	`ExpressionNotify` (*user_data)
	`FlowBoxCreateWidgetFunc` (item, *user_data)
	`FlowBoxFilterFunc` (child, *user_data)
	`FlowBoxForeachFunc` (box, child, *user_data)
	`FlowBoxSortFunc` (child1, child2, *user_data)
	`FontFilterFunc` (family, face, *data)
	`IconViewForeachFunc` (icon_view, path, *data)
	`ListBoxCreateWidgetFunc` (item, *user_data)
	`ListBoxFilterFunc` (row, *user_data)
	`ListBoxForeachFunc` (box, row, *user_data)
	`ListBoxSortFunc` (row1, row2, *user_data)
	`ListBoxUpdateHeaderFunc` (row, before, *user_data)
	`MapListModelMapFunc` (item, *user_data)
	`MenuButtonCreatePopupFunc` (menu_button, *user_data)
	`PageSetupDoneFunc` (page_setup, *data)
	`PrintJobCompleteFunc` (print_job, user_data, error)
	`PrintSettingsFunc` (key, value, *user_data)
	`PrinterFunc` (printer, *data)
	`ScaleFormatValueFunc` (scale, value, *user_data)
	`ShortcutFunc` (widget, args, *user_data)
	`TextCharPredicate` (ch, *user_data)
	`TextTagTableForeach` (tag, *data)
	`TickCallback` (widget, frame_clock, *user_data)
	`TreeCellDataFunc` (tree_column, cell, tree_model, iter, *data)
	`TreeIterCompareFunc` (model, a, b, *user_data)
	`TreeListModelCreateModelFunc` (item, *user_data)
	`TreeModelFilterModifyFunc` (model, iter, column, *data)
	`TreeModelFilterVisibleFunc` (model, iter, *data)
	`TreeModelForeachFunc` (model, path, iter, *data)
	`TreeSelectionForeachFunc` (model, path, iter, *data)
	`TreeSelectionFunc` (selection, model, path, path_currently_selected, *data)
	`TreeViewColumnDropFunc` (tree_view, column, prev_column, next_column, *data)
	`TreeViewMappingFunc` (tree_view, path, *user_data)
	`TreeViewRowSeparatorFunc` (model, iter, *data)
	`TreeViewSearchEqualFunc` (model, column, key, iter, *search_data)
	`WidgetActionActivateFunc` (widget, action_name, parameter)

Details¶

Gtk.AssistantPageFunc(current_page, *data)¶

Parameters:

current_page (int) – The page number used to calculate the next page.
data (object or None) – user data.

Returns:

The next page number

Return type:

int

Type of callback used to calculate the next page in a GtkAssistant.

It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button.

See [method`Gtk`.Assistant.set_forward_page_func].

Gtk.CellAllocCallback(renderer, cell_area, cell_background, *data)¶

Parameters:

renderer (Gtk.CellRenderer) – the cell renderer to operate on
cell_area (Gdk.Rectangle) – the area allocated to renderer inside the rectangle provided to Gtk.CellArea.foreach_alloc().
cell_background (Gdk.Rectangle) – the background area for renderer inside the background area provided to Gtk.CellArea.foreach_alloc().
data (object or None) – user-supplied data

Returns:

True to stop iterating over cells.

Return type:

bool

The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a GtkCellArea, see Gtk.CellArea.foreach_alloc().

Gtk.CellCallback(renderer, *data)¶

Parameters:

renderer (Gtk.CellRenderer) – the cell renderer to operate on
data (object or None) – user-supplied data

Returns:

True to stop iterating over cells.

Return type:

bool

The type of the callback functions used for iterating over the cell renderers of a GtkCellArea, see Gtk.CellArea.foreach().

Gtk.CellLayoutDataFunc(cell_layout, cell, tree_model, iter, *data)¶

Parameters:

cell_layout (Gtk.CellLayout) – a GtkCellLayout
cell (Gtk.CellRenderer) – the cell renderer whose value is to be set
tree_model (Gtk.TreeModel) – the model
iter (Gtk.TreeIter) – a GtkTreeIter indicating the row to set the value for
data (object or None) – user data passed to Gtk.CellLayout.set_cell_data_func()

A function which should set the value of cell_layout’s cell renderer(s) as appropriate.

Gtk.CustomAllocateFunc(widget, width, height, baseline)¶

Parameters:

widget (Gtk.Widget) – the widget to allocate
width (int) – the new width of the widget
height (int) – the new height of the widget
baseline (int) – the new baseline of the widget, or -1

A function to be used by GtkCustomLayout to allocate a widget.

Gtk.CustomFilterFunc(item, *user_data)¶

Parameters:

item (GObject.Object) – The item to be matched
user_data (object or None) – user data

Returns:

True to keep the item around

Return type:

bool

User function that is called to determine if the item should be matched.

If the filter matches the item, this function must return True. If the item should be filtered out, False must be returned.

Gtk.CustomMeasureFunc(widget, orientation, for_size)¶

Parameters:

widget (Gtk.Widget) – the widget to be measured
orientation (Gtk.Orientation) – the direction to be measured
for_size (int) – the size to be measured for

Returns:

minimum:: the measured minimum size of the widget
natural:: the measured natural size of the widget
minimum_baseline:: the measured minimum baseline of the widget
natural_baseline:: the measured natural baseline of the widget

Return type:

(minimum: int, natural: int, minimum_baseline: int, natural_baseline: int)

A function to be used by GtkCustomLayout to measure a widget.

Gtk.CustomRequestModeFunc(widget)¶

Parameters:: widget (Gtk.Widget) – the widget to be queried
Returns:: the size request mode
Return type:: Gtk.SizeRequestMode

Queries a widget for its preferred size request mode.

Gtk.DrawingAreaDrawFunc(drawing_area, cr, width, height, *user_data)¶

Parameters:

drawing_area (Gtk.DrawingArea) – the GtkDrawingArea to redraw
cr (cairo.Context) – the context to draw to
width (int) – the actual width of the contents. This value will be at least as wide as Gtk.DrawingArea :width.
height (int) – the actual height of the contents. This value will be at least as wide as Gtk.DrawingArea :height.
user_data (object or None) – user data

Whenever drawing_area needs to redraw, this function will be called.

This function should exclusively redraw the contents of the drawing area and must not call any widget functions that cause changes.

Gtk.EntryCompletionMatchFunc(completion, key, iter, *user_data)¶

Parameters:

completion (Gtk.EntryCompletion) – the GtkEntryCompletion
key (str) – the string to match, normalized and case-folded
iter (Gtk.TreeIter) – a GtkTreeIter indicating the row to match
user_data (object or None) – user data given to Gtk.EntryCompletion.set_match_func()

Returns:

True if iter should be displayed as a possible completion for key

Return type:

bool

A function which decides whether the row indicated by iter matches a given key, and should be displayed as a possible completion for key.

Note that key is normalized and case-folded (see GLib.utf8_normalize() and GLib.utf8_casefold()). If this is not appropriate, match functions have access to the unmodified key via gtk_editable_get_text (GTK_EDITABLE (gtk_entry_completion_get_entry ())).

Gtk.ExpressionNotify(*user_data)¶

Parameters:: user_data (object or None) – data passed to Gtk.Expression.watch()

Callback called by Gtk.Expression.watch() when the expression value changes.

Gtk.FlowBoxCreateWidgetFunc(item, *user_data)¶

Parameters:

item (GObject.Object) – the item from the model for which to create a widget for
user_data (object or None) – user data from Gtk.FlowBox.bind_model()

Returns:

a GtkWidget that represents item

Return type:

Gtk.Widget

Called for flow boxes that are bound to a GListModel.

This function is called for each item that gets added to the model.

Gtk.FlowBoxFilterFunc(child, *user_data)¶

Parameters:

child (Gtk.FlowBoxChild) – a GtkFlowBoxChild that may be filtered
user_data (object or None) – user data

Returns:

True if the row should be visible, False otherwise

Return type:

bool

A function that will be called whenever a child changes or is added.

It lets you control if the child should be visible or not.

Gtk.FlowBoxForeachFunc(box, child, *user_data)¶

Parameters:

box (Gtk.FlowBox) – a GtkFlowBox
child (Gtk.FlowBoxChild) – a GtkFlowBoxChild
user_data (object or None) – user data

A function used by Gtk.FlowBox.selected_foreach().

It will be called on every selected child of the box.

Gtk.FlowBoxSortFunc(child1, child2, *user_data)¶

Parameters:

child1 (Gtk.FlowBoxChild) – the first child
child2 (Gtk.FlowBoxChild) – the second child
user_data (object or None) – user data

Returns:

< 0 if child1 should be before child2, 0 if they are equal, and > 0 otherwise

Return type:

int

A function to compare two children to determine which should come first.

Gtk.FontFilterFunc(family, face, *data)¶

Parameters:

family (Pango.FontFamily) – a PangoFontFamily
face (Pango.FontFace) – a PangoFontFace belonging to family
data (object or None) – user data passed to Gtk.FontChooser.set_filter_func()

Returns:

True if the font should be displayed

Return type:

bool

The type of function that is used for deciding what fonts get shown in a GtkFontChooser.

See [method`Gtk`.FontChooser.set_filter_func].

Gtk.IconViewForeachFunc(icon_view, path, *data)¶

Parameters:

icon_view (Gtk.IconView) – a GtkIconView
path (Gtk.TreePath) – The GtkTreePath of a selected row
data (object or None) – user data

A function used by Gtk.IconView.selected_foreach() to map all selected rows.

It will be called on every selected row in the view.

Gtk.ListBoxCreateWidgetFunc(item, *user_data)¶

Parameters:

item (GObject.Object) – the item from the model for which to create a widget for
user_data (object or None) – user data

Returns:

a GtkWidget that represents item

Return type:

Gtk.Widget

Called for list boxes that are bound to a GListModel with Gtk.ListBox.bind_model() for each item that gets added to the model.

If the widget returned is not a Gtk.ListBoxRow widget, then the widget will be inserted as the child of an intermediate Gtk.ListBoxRow.

Gtk.ListBoxFilterFunc(row, *user_data)¶

Parameters:

row (Gtk.ListBoxRow) – the row that may be filtered
user_data (object or None) – user data

Returns:

True if the row should be visible, False otherwise

Return type:

bool

Will be called whenever the row changes or is added and lets you control if the row should be visible or not.

Gtk.ListBoxForeachFunc(box, row, *user_data)¶

Parameters:

box (Gtk.ListBox) – a GtkListBox
row (Gtk.ListBoxRow) – a GtkListBoxRow
user_data (object or None) – user data

A function used by Gtk.ListBox.selected_foreach().

It will be called on every selected child of the box.

Gtk.ListBoxSortFunc(row1, row2, *user_data)¶

Parameters:

row1 (Gtk.ListBoxRow) – the first row
row2 (Gtk.ListBoxRow) – the second row
user_data (object or None) – user data

Returns:

< 0 if row1 should be before row2, 0 if they are equal and > 0 otherwise

Return type:

int

Compare two rows to determine which should be first.

Gtk.ListBoxUpdateHeaderFunc(row, before, *user_data)¶

Parameters:

row (Gtk.ListBoxRow) – the row to update
before (Gtk.ListBoxRow or None) – the row before row, or None if it is first
user_data (object or None) – user data

Whenever row changes or which row is before row changes this is called, which lets you update the header on row.

You may remove or set a new one via [method`Gtk`.ListBoxRow.set_header] or just change the state of the current header widget.

Gtk.MapListModelMapFunc(item, *user_data)¶

Parameters:

item (GObject.Object) – The item to map
user_data (object or None) – user data

Returns:

The item to map to

Return type:

GObject.Object

User function that is called to map an item of the original model to an item expected by the map model.

The returned items must conform to the item type of the model they are used with.

Gtk.MenuButtonCreatePopupFunc(menu_button, *user_data)¶

Parameters:

menu_button (Gtk.MenuButton) – the GtkMenuButton
user_data (object or None) – User data passed to Gtk.MenuButton.set_create_popup_func()

User-provided callback function to create a popup for a GtkMenuButton on demand.

This function is called when the popup of menu_button is shown, but none has been provided via [method`Gtk`.MenuButton.set_popover] or [method`Gtk`.MenuButton.set_menu_model].

Gtk.PageSetupDoneFunc(page_setup, *data)¶

Parameters:

page_setup (Gtk.PageSetup) – the GtkPageSetup that has been passed to Gtk.print_run_page_setup_dialog_async()
data (object or None) – user data that has been passed to Gtk.print_run_page_setup_dialog_async()

The type of function that is passed to Gtk.print_run_page_setup_dialog_async().

This function will be called when the page setup dialog is dismissed, and also serves as destroy notify for data.

Gtk.PrintJobCompleteFunc(print_job, user_data, error)¶

Parameters:

print_job (Gtk.PrintJob) – the GtkPrintJob
user_data (object or None) – user data that has been passed to Gtk.PrintJob.send()
error (GLib.Error) – a GError that contains error information if the sending of the print job failed, otherwise None

The type of callback that is passed to Gtk.PrintJob.send().

It is called when the print job has been completely sent.

Gtk.PrintSettingsFunc(key, value, *user_data)¶

Parameters:

key (str) –
value (str) –
user_data (object or None) –

Gtk.PrinterFunc(printer, *data)¶

Parameters:

printer (Gtk.Printer) – a GtkPrinter
data (object or None) – user data passed to Gtk.enumerate_printers()

Returns:

True to stop the enumeration, False to continue

Return type:

bool

The type of function passed to Gtk.enumerate_printers().

Note that you need to ref printer, if you want to keep a reference to it after the function has returned.

Gtk.ScaleFormatValueFunc(scale, value, *user_data)¶

Parameters:

scale (Gtk.Scale) – The GtkScale
value (float) – The numeric value to format
user_data (object or None) – user data

Returns:

A newly allocated string describing a textual representation of the given numerical value.

Return type:

str

Gtk.ShortcutFunc(widget, args, *user_data)¶

Parameters:

widget (Gtk.Widget) – The widget passed to the activation
args (GLib.Variant or None) – The arguments passed to the activation
user_data (object or None) – The user data provided when activating the action

Returns:

True if the action was successful.

Return type:

bool

Prototype for shortcuts based on user callbacks.

Gtk.TextCharPredicate(ch, *user_data)¶

Parameters:

ch (str) – a Unicode code point
user_data (object or None) – data passed to the callback

Returns:

True if the predicate is satisfied, and the iteration should stop, and False otherwise

Return type:

bool

The predicate function used by Gtk.TextIter.forward_find_char() and Gtk.TextIter.backward_find_char().

Gtk.TextTagTableForeach(tag, *data)¶

Parameters:

tag (Gtk.TextTag) – the GtkTextTag
data (object or None) – data passed to Gtk.TextTagTable.foreach()

A function used with Gtk.TextTagTable.foreach(), to iterate over every GtkTextTag inside a GtkTextTagTable.

Gtk.TickCallback(widget, frame_clock, *user_data)¶

Parameters:

widget (Gtk.Widget) – the widget
frame_clock (Gdk.FrameClock) – the frame clock for the widget (same as calling Gtk.Widget.get_frame_clock())
user_data (object or None) – user data passed to Gtk.Widget.add_tick_callback().

Returns:

GLib.SOURCE_CONTINUE if the tick callback should continue to be called, GLib.SOURCE_REMOVE if the tick callback should be removed.

Return type:

bool

Callback type for adding a function to update animations. See Gtk.Widget.add_tick_callback().

Gtk.TreeCellDataFunc(tree_column, cell, tree_model, iter, *data)¶

Parameters:

tree_column (Gtk.TreeViewColumn) – A GtkTreeViewColumn
cell (Gtk.CellRenderer) – The GtkCellRenderer that is being rendered by tree_column
tree_model (Gtk.TreeModel) – The GtkTreeModel being rendered
iter (Gtk.TreeIter) – A GtkTreeIter of the current row rendered
data (object or None) – user data

A function to set the properties of a cell instead of just using the straight mapping between the cell and the model.

This function is useful for customizing the cell renderer. For example, a function might get an* integer from the tree_model, and render it to the “text” attribute of “cell” by converting it to its written equivalent.

Gtk.TreeIterCompareFunc(model, a, b, *user_data)¶

Parameters:

model (Gtk.TreeModel) – The GtkTreeModel the comparison is within
a (Gtk.TreeIter) – A GtkTreeIter in model
b (Gtk.TreeIter) – Another GtkTreeIter in model
user_data (object or None) – Data passed when the compare func is assigned e.g. by Gtk.TreeSortable.set_sort_func()

Returns:

a negative integer, zero or a positive integer depending on whether a sorts before, with or after b

Return type:

int

A Gtk.TreeIterCompareFunc should return a negative integer, zero, or a positive integer if a sorts before b, a sorts with b, or a sorts after b respectively.

If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the GtkTreeSortable behaves as expected, the Gtk.TreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive.

For example, if model is a product catalogue, then a compare function for the “price” column could be one which returns price_of(@a) - price_of(@b).

Gtk.TreeListModelCreateModelFunc(item, *user_data)¶

Parameters:

item (GObject.Object) – The item that is being expanded
user_data (object or None) – User data passed when registering the function

Returns:

The model tracking the children of item or None if item can never have children

Return type:

Gio.ListModel or None

Prototype of the function called to create new child models when Gtk.TreeListRow.set_expanded() is called.

This function can return None to indicate that item is guaranteed to be a leaf node and will never have children. If it does not have children but may get children later, it should return an empty model that is filled once children arrive.

Gtk.TreeModelFilterModifyFunc(model, iter, column, *data)¶

Parameters:

model (Gtk.TreeModel) – the GtkTreeModelFilter
iter (Gtk.TreeIter) – a GtkTreeIter pointing to the row whose display values are determined
column (int) – the column whose display value is determined
data (object or None) – user data given to Gtk.TreeModelFilter.set_modify_func()

Returns:

A GValue which is already initialized for with the correct type for the column column.

Return type:

value: GObject.Value

A function which calculates display values from raw values in the model. It must fill value with the display value for the column column in the row indicated by iter.

Since this function is called for each data access, it’s not a particularly efficient operation.

Gtk.TreeModelFilterVisibleFunc(model, iter, *data)¶

Parameters:

model (Gtk.TreeModel) – the child model of the GtkTreeModelFilter
iter (Gtk.TreeIter) – a GtkTreeIter pointing to the row in model whose visibility is determined
data (object or None) – user data given to Gtk.TreeModelFilter.set_visible_func()

Returns:

Whether the row indicated by iter is visible.

Return type:

bool

A function which decides whether the row indicated by iter is visible.

Gtk.TreeModelForeachFunc(model, path, iter, *data)¶

Parameters:

model (Gtk.TreeModel) – the GtkTreeModel being iterated
path (Gtk.TreePath) – the current GtkTreePath
iter (Gtk.TreeIter) – the current GtkTreeIter
data (object or None) – The user data passed to Gtk.TreeModel.foreach()

Returns:

True to stop iterating, False to continue

Return type:

bool

Type of the callback passed to Gtk.TreeModel.foreach() to iterate over the rows in a tree model.

Gtk.TreeSelectionForeachFunc(model, path, iter, *data)¶

Parameters:

model (Gtk.TreeModel) – The GtkTreeModel being viewed
path (Gtk.TreePath) – The GtkTreePath of a selected row
iter (Gtk.TreeIter) – A GtkTreeIter pointing to a selected row
data (object or None) – user data

A function used by Gtk.TreeSelection.selected_foreach() to map all selected rows. It will be called on every selected row in the view.

Gtk.TreeSelectionFunc(selection, model, path, path_currently_selected, *data)¶

Parameters:

selection (Gtk.TreeSelection) – A GtkTreeSelection
model (Gtk.TreeModel) – A GtkTreeModel being viewed
path (Gtk.TreePath) – The GtkTreePath of the row in question
path_currently_selected (bool) – True, if the path is currently selected
data (object or None) – user data

Returns:

True, if the selection state of the row can be toggled

Return type:

bool

A function used by Gtk.TreeSelection.set_select_function() to filter whether or not a row may be selected. It is called whenever a row’s state might change.

A return value of True indicates to selection that it is okay to change the selection.

Gtk.TreeViewColumnDropFunc(tree_view, column, prev_column, next_column, *data)¶

Parameters:

tree_view (Gtk.TreeView) – A GtkTreeView
column (Gtk.TreeViewColumn) – The GtkTreeViewColumn being dragged
prev_column (Gtk.TreeViewColumn) – A GtkTreeViewColumn on one side of column
next_column (Gtk.TreeViewColumn) – A GtkTreeViewColumn on the other side of column
data (object or None) – user data

Returns:

True, if column can be dropped in this spot

Return type:

bool

Function type for determining whether column can be dropped in a particular spot (as determined by prev_column and next_column). In left to right locales, prev_column is on the left of the potential drop spot, and next_column is on the right. In right to left mode, this is reversed. This function should return True if the spot is a valid drop spot. Please note that returning True does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user.

Gtk.TreeViewMappingFunc(tree_view, path, *user_data)¶

Parameters:

tree_view (Gtk.TreeView) – A GtkTreeView
path (Gtk.TreePath) – The path that’s expanded
user_data (object or None) – user data

Function used for Gtk.TreeView.map_expanded_rows().

Gtk.TreeViewRowSeparatorFunc(model, iter, *data)¶

Parameters:

model (Gtk.TreeModel) – the GtkTreeModel
iter (Gtk.TreeIter) – a GtkTreeIter pointing at a row in model
data (object or None) – user data

Returns:

True if the row is a separator

Return type:

bool

Function type for determining whether the row pointed to by iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the GtkTreeViewRowSeparatorFunc returns.

Gtk.TreeViewSearchEqualFunc(model, column, key, iter, *search_data)¶

Parameters:

model (Gtk.TreeModel) – the GtkTreeModel being searched
column (int) – the search column set by Gtk.TreeView.set_search_column()
key (str) – the key string to compare with
iter (Gtk.TreeIter) – a GtkTreeIter pointing the row of model that should be compared with key.
search_data (object or None) – user data from Gtk.TreeView.set_search_equal_func()

Returns:

False if the row matches, True otherwise.

Return type:

bool

A function used for checking whether a row in model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect, though it has some similarity to strcmp() returning 0 for equal strings.

Gtk.WidgetActionActivateFunc(widget, action_name, parameter)¶

Parameters:

widget (Gtk.Widget) – the widget to which the action belongs
action_name (str) – the action name
parameter (GLib.Variant or None) – parameter for activation

The type of the callback functions used for activating actions installed with Gtk.WidgetClass.install_action().

The parameter must match the parameter_type of the action.