Gtk.WidgetClass

Fields

Name	Type	Access	Description
activate_signal	int	r	The signal to emit when a widget of this class is activated, Gtk.Widget.activate() handles the emission. Implementation of this signal is optional.
adjust_baseline_allocation	object	r
adjust_baseline_request	object	r
adjust_size_allocation	object	r	Convert an initial size allocation assigned by a Gtk.Container using Gtk.Widget.size_allocate(), into an actual size allocation to be used by the widget. adjust_size_allocation adjusts to a child widget’s actual allocation from what a parent container computed for the child. The adjusted allocation must be entirely within the original allocation. In any custom implementation, chain up to the default Gtk.Widget implementation of this method, which applies the margin and alignment properties of Gtk.Widget. Chain up before performing your own adjustments so your own adjustments remove more allocation after the Gtk.Widget base class has already removed margin and alignment. The natural size passed in should be adjusted in the same way as the allocated size, which allows adjustments to perform alignments or other changes based on natural size.
adjust_size_request	object	r	Convert an initial size request from a widget’s Gtk.SizeRequestMode virtual method implementations into a size request to be used by parent containers in laying out the widget. adjust_size_request adjusts from a child widget’s original request to what a parent container should use for layout. The for_size argument will be -1 if the request should not be for a particular size in the opposing orientation, i.e. if the request is not height-for-width or width-for-height. If for_size is greater than -1, it is the proposed allocation in the opposing orientation that we need the request for. Implementations of adjust_size_request should chain up to the default implementation, which applies Gtk.Widget’s margin properties and imposes any values from Gtk.Widget.set_size_request(). Chaining up should be last, after your subclass adjusts the request, so Gtk.Widget can apply constraints and add the margin properly.
button_press_event	object	r	Signal will be emitted when a button (typically from a mouse) is pressed.
button_release_event	object	r	Signal will be emitted when a button (typically from a mouse) is released.
can_activate_accel	object	r	Signal allows applications and derived widgets to override the default Gtk.Widget handling for determining whether an accelerator can be activated.
child_notify	object	r	Signal emitted for each child property that has changed on an object.
composited_changed	object	r	Signal emitted when the composited status of widgets screen changes. See Gdk.Screen.is_composited().
compute_expand	object	r	Computes whether a container should give this widget extra space when possible.
configure_event	object	r	Signal will be emitted when the size, position or stacking of the widget’s window has changed.
damage_event	object	r	Signal emitted when a redirected window belonging to widget gets drawn into.
delete_event	object	r	Signal emitted if a user requests that a toplevel window is closed.
destroy	object	r	Signals that all holders of a reference to the widget should release the reference that they hold.
destroy_event	object	r	Signal is emitted when a Gdk.Window is destroyed.
direction_changed	object	r	Signal emitted when the text direction of a widget changes.
dispatch_child_properties_changed	object	r	Seldomly overidden.
drag_begin	object	r	Signal emitted on the drag source when a drag is started.
drag_data_delete	object	r	Signal emitted on the drag source when a drag with the action Gdk.DragAction.MOVE is successfully completed.
drag_data_get	object	r	Signal emitted on the drag source when the drop site requests the data which is dragged.
drag_data_received	object	r	Signal emitted on the drop site when the dragged data has been received.
drag_drop	object	r	Signal emitted on the drop site when the user drops the data onto the widget.
drag_end	object	r	Signal emitted on the drag source when a drag is finished.
drag_failed	object	r	Signal emitted on the drag source when a drag has failed.
drag_leave	object	r	Signal emitted on the drop site when the cursor leaves the widget.
drag_motion	object	r	signal emitted on the drop site when the user moves the cursor over the widget during a drag.
draw	object	r	Signal emitted when a widget is supposed to render itself.
enter_notify_event	object	r	Signal event will be emitted when the pointer enters the widget’s window.
event	object	r	The GTK+ main loop will emit three signals for each GDK event delivered to a widget: one generic ::event signal, another, more specific, signal that matches the type of event delivered (e.g. “key-press-event”) and finally a generic “event-after” signal.
focus	object	r
focus_in_event	object	r	Signal emitted when the keyboard focus enters the widget’s window.
focus_out_event	object	r	Signal emitted when the keyboard focus leaves the widget’s window.
get_accessible	object	r	Returns the accessible object that describes the widget to an assistive technology.
get_preferred_height	object	r	This is called by containers to obtain the minimum and natural height of a widget. A widget that does not actually trade any height for width or width for height only has to implement these two virtual methods (Gtk.Widget.do_get_preferred_width() and Gtk.Widget.do_get_preferred_height()).
get_preferred_height_and_baseline_for_width	object	r
get_preferred_height_for_width	object	r	This is similar to Gtk.Widget.do_get_preferred_height() except that it is passed a contextual width to request height for. By implementing this virtual method it is possible for a Gtk.Label to tell its parent how much height would be required if the label were to be allocated a said width.
get_preferred_width	object	r	This is called by containers to obtain the minimum and natural width of a widget. A widget will never be allocated a width less than its minimum and will only ever be allocated a width greater than the natural width once all of the said widget’s siblings have received their natural widths. Furthermore, a widget will only ever be allocated a width greater than its natural width if it was configured to receive extra expand space from its parent container.
get_preferred_width_for_height	object	r	This is analogous to Gtk.Widget.do_get_preferred_height_for_width() except that it operates in the oposite orientation. It’s rare that a widget actually does Gtk.SizeRequestMode.WIDTH_FOR_HEIGHT requests but this can happen when, for example, a widget or container gets additional columns to compensate for a smaller allocated height.
get_request_mode	object	r	This allows a widget to tell its parent container whether it prefers to be allocated in Gtk.SizeRequestMode.HEIGHT_FOR_WIDTH or Gtk.SizeRequestMode.WIDTH_FOR_HEIGHT mode. Gtk.SizeRequestMode.HEIGHT_FOR_WIDTH means the widget prefers to have Gtk.Widget.do_get_preferred_width() called and then Gtk.Widget.do_get_preferred_height_for_width(). Gtk.SizeRequestMode.CONSTANT_SIZE disables any height-for-width or width-for-height geometry management for a said widget and is the default return. It’s important to note (as described below) that any widget which trades height-for-width or width-for-height must respond properly to both of the virtual methods Gtk.Widget.do_get_preferred_height_for_width() and Gtk.Widget.do_get_preferred_width_for_height() since it might be queried in either Gtk.SizeRequestMode by its parent container.
grab_broken_event	object	r	Signal emitted when a pointer or keyboard grab on a window belonging to widget gets broken.
grab_focus	object	r	Causes widget to have the keyboard focus for the Gtk.Window it’s inside.
grab_notify	object	r	Signal emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed.
hide	object	r	Signal emitted when widget is hidden.
hierarchy_changed	object	r	Signal emitted when the anchored state of a widget changes.
key_press_event	object	r	Signal emitted when a key is pressed.
key_release_event	object	r	Signal is emitted when a key is released.
keynav_failed	object	r	Signal emitted if keyboard navigation fails.
leave_notify_event	object	r	Will be emitted when the pointer leaves the widget’s window.
map	object	r	Signal emitted when widget is going to be mapped, that is when the widget is visible (which is controlled with Gtk.Widget.set_visible()) and all its parents up to the toplevel widget are also visible.
map_event	object	r	Signal emitted when the widget’s window is mapped.
mnemonic_activate	object	r	Activates the widget if group_cycling is False, and just grabs the focus if group_cycling is True.
motion_notify_event	object	r	Signal emitted when the pointer moves over the widget’s Gdk.Window.
move_focus	object	r	Signal emitted when a change of focus is requested
parent_class	GObject.InitiallyUnownedClass	r	The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a Gtk.WidgetClass pointer to be cast to a GObject.ObjectClass pointer.
parent_set	object	r	Signal emitted when a new parent has been set on a widget.
popup_menu	object	r	Signal emitted whenever a widget should pop up a context menu.
property_notify_event	object	r	Signal will be emitted when a property on the widget’s window has been changed or deleted.
proximity_in_event	object	r
proximity_out_event	object	r
query_tooltip	object	r	Signal emitted when “has-tooltip” is True and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode.
queue_draw_region	object	r	Invalidates the area of widget defined by region by calling Gdk.Window.invalidate_region() on the widget’s window and all its child windows.
realize	object	r	Signal emitted when widget is associated with a Gdk.Window, which means that Gtk.Widget.realize() has been called or the widget has been mapped (that is, it is going to be drawn).
screen_changed	object	r	Signal emitted when the screen of a widget has changed.
scroll_event	object	r	Signal emitted when a button in the 4 to 7 range is pressed.
selection_clear_event	object	r	Signal will be emitted when the the widget’s window has lost ownership of a selection.
selection_get	object	r
selection_notify_event	object	r
selection_received	object	r
selection_request_event	object	r	Signal will be emitted when another client requests ownership of the selection owned by the widget’s window.
show	object	r	Signal emitted when widget is shown
show_all	object	r	Recursively shows a widget, and any child widgets (if the widget is a container).
show_help	object	r
size_allocate	object	r	Signal emitted to get the widget allocation.
state_changed	object	r	Signal emitted when the widget state changes. Deprecated: 3.0
state_flags_changed	object	r	Signal emitted when the widget state changes, see Gtk.Widget.get_state_flags().
style_set	object	r	Signal emitted when a new style has been set on a widget. Deprecated: 3.0
style_updated	object	r	Signal emitted when the Gtk.StyleContext of a widget is changed.
touch_event	object	r	Signal emitted when a touch event happens
unmap	object	r	Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden.
unmap_event	object	r	Signal will be emitted when the widget’s window is unmapped.
unrealize	object	r	Signal emitted when the Gdk.Window associated with widget is destroyed, which means that Gtk.Widget.unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden).
visibility_notify_event	object	r	Signal emitted when the widget’s window is obscured or unobscured.
window_state_event	object	r	Signal emitted when the state of the toplevel window associated to the widget changes.

Methods

	bind_template_callback_full (callback_name, callback_symbol)
	bind_template_child_full (name, internal_child, struct_offset)
	find_style_property (property_name)
	get_css_name ()
	install_style_property (pspec)
	list_style_properties ()
	set_accessible_role (role)
	set_accessible_type (type)
	set_connect_func (connect_func, *connect_data)
	set_css_name (name)
	set_template (template_bytes)
	set_template_from_resource (resource_name)

Details

class Gtk.WidgetClass

bind_template_callback_full(callback_name, callback_symbol)

Parameters:

• callback_name (str) – The name of the callback as expected in the template XML

• callback_symbol (GObject.Callback) – The callback symbol

Declares a callback_symbol to handle callback_name from the template XML defined for widget_type. See Gtk.Builder.add_callback_symbol().

Note that this must be called from a composite widget classes class initializer after calling Gtk.WidgetClass.set_template().

New in version 3.10.

bind_template_child_full(name, internal_child, struct_offset)

Parameters:

• name (str) – The “id” of the child defined in the template XML

• internal_child (bool) – Whether the child should be accessible as an “internal-child” when this class is used in Gtk.Builder XML

• struct_offset (int) – The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer.

Automatically assign an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via Gtk.Widget.get_template_child().

The struct can point either into the public instance, then you should use G_STRUCT_OFFSET(WidgetType, member) for struct_offset, or in the private struct, then you should use G_PRIVATE_OFFSET(WidgetType, member).

An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when GObject.Object.do_dispose() runs on your instance and if a struct_offset that is != 0 is specified, then the automatic location in your instance public or private data will be set to None. You can however access an automated child pointer the first time your classes GObject.Object.do_dispose() runs, or alternatively in Gtk.Widget.do_destroy().

If internal_child is specified, Gtk.Buildable.do_get_internal_child() will be automatically implemented by the Gtk.Widget class so there is no need to implement it manually.

The wrapper macros gtk_widget_class_bind_template_child(), gtk_widget_class_bind_template_child_internal(), gtk_widget_class_bind_template_child_private() and gtk_widget_class_bind_template_child_internal_private() might be more convenient to use.

Note that this must be called from a composite widget classes class initializer after calling Gtk.WidgetClass.set_template().

New in version 3.10.

find_style_property(property_name)

Parameters:

property_name (str) – the name of the style property to find

Returns:

the GObject.ParamSpec of the style property or None if class has no style property with that name.

Return type:

GObject.ParamSpec

Finds a style property of a widget class by name.

New in version 2.2.

get_css_name()

Returns:

the CSS name of the given class

Return type:

str

Gets the name used by this class for matching in CSS code. See Gtk.WidgetClass.set_css_name() for details.

New in version 3.20.

install_style_property(pspec)

Parameters:

pspec (GObject.ParamSpec) – the GObject.ParamSpec for the property

Installs a style property on a widget class. The parser for the style property is determined by the value type of pspec.

list_style_properties()

Returns:

a newly allocated array of GObject.ParamSpec. The array must be freed with GLib.free().

Return type:

[GObject.ParamSpec]

Returns all style properties of a widget class.

New in version 2.2.

set_accessible_role(role)

Parameters:

role (Atk.Role) – The role to use for accessibles created for self

Sets the default Atk.Role to be set on accessibles created for widgets of self. Accessibles may decide to not honor this setting if their role reporting is more refined. Calls to Gtk.WidgetClass.set_accessible_type() will reset this value.

In cases where you want more fine-grained control over the role of accessibles created for self, you should provide your own accessible type and use Gtk.WidgetClass.set_accessible_type() instead.

If role is Atk.Role.INVALID, the default role will not be changed and the accessible’s default role will be used instead.

This function should only be called from class init functions of widgets.

New in version 3.2.

set_accessible_type(type)

Parameters:

type (GObject.GType) – The object type that implements the accessible for self

Sets the type to be used for creating accessibles for widgets of self. The given type must be a subtype of the type used for accessibles of the parent class.

This function should only be called from class init functions of widgets.

New in version 3.2.

set_connect_func(connect_func, *connect_data)

Parameters:

• connect_func (Gtk.BuilderConnectFunc) – The Gtk.BuilderConnectFunc to use when connecting signals in the class template

• connect_data (object or None) – The data to pass to connect_func

For use in language bindings, this will override the default Gtk.BuilderConnectFunc to be used when parsing Gtk.Builder XML from this class’s template data.

Note that this must be called from a composite widget classes class initializer after calling Gtk.WidgetClass.set_template().

New in version 3.10.

set_css_name(name)

Parameters:

name (str) – name to use

Sets the name to be used for CSS matching of widgets.

If this function is not called for a given class, the name of the parent class is used.

New in version 3.20.

set_template(template_bytes)

Parameters:

template_bytes (GLib.Bytes) – A GLib.Bytes holding the Gtk.Builder XML

This should be called at class initialization time to specify the Gtk.Builder XML to be used to extend a widget.

For convenience, Gtk.WidgetClass.set_template_from_resource() is also provided.

Note that any class that installs templates must call Gtk.Widget.init_template() in the widget’s instance initializer.

New in version 3.10.

set_template_from_resource(resource_name)

Parameters:

resource_name (str) – The name of the resource to load the template from

A convenience function to call Gtk.WidgetClass.set_template().

Note that any class that installs templates must call Gtk.Widget.init_template() in the widget’s instance initializer.

New in version 3.10.