Class: Gtk::Widget

Inherits:
GObject::InitiallyUnowned
  • Object
show all
Defined in:
(unknown)

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.default_direction ⇒ Gtk::TextDirection

Obtains the current default reading direction.

See [funcGtk.Widget.set_default_direction].

Returns:

.default_direction=(dir) ⇒ nil

Sets the default reading direction for widgets.

See [methodGtk.Widget.set_direction].

Parameters:

  • dir (Gtk::TextDirection) —

    the new default direction. This cannot be %GTK_TEXT_DIR_NONE.

Returns:

  • (nil)

Instance Method Details

#accessible_role ⇒ Gtk::AccessibleRole

Retrieves the accessible role used by the given GtkWidget class.

Different accessible roles have different states, and are rendered differently by assistive technologies.

See also: [methodGtk.Accessible.get_accessible_role].

Returns:

#accessible_role=(accessible_role) ⇒ nil

Sets the accessible role used by the given GtkWidget class.

Different accessible roles have different states, and are rendered differently by assistive technologies.

Parameters:

Returns:

  • (nil)

#action_set_enabled(action_name, enabled) ⇒ nil

Enable or disable an action installed with gtk_widget_class_install_action().

Parameters:

  • action_name (String) —

    action name, such as "clipboard.paste"

  • enabled (Boolean) —

    whether the action is now enabled

Returns:

  • (nil)

#activate ⇒ Boolean

For widgets that can be “activated” (buttons, menu items, etc.), this function activates them.

The activation will emit the signal set using [methodGtk.WidgetClass.set_activate_signal] during class initialization.

Activation is what happens when you press Enter on a widget during key navigation.

If you wish to handle the activation keybinding yourself, it is recommended to use [methodGtk.WidgetClass.add_shortcut] with an action created with [ctorGtk.SignalAction.new].

If widget isn't activatable, the function returns false.

Returns:

  • (Boolean) —

    true if the widget was activatable

#activate_action(name, format_string, array) ⇒ Boolean

Looks up the action in the action groups associated with widget and its ancestors, and activates it.

This is a wrapper around [methodGtk.Widget.activate_action_variant] that constructs the args variant according to format_string.

Parameters:

  • name (String) —

    the name of the action to activate

  • format_string (String) —

    GVariant format string for arguments

  • array (Array) —

    arguments, as given by format string

Returns:

  • (Boolean) —

    true if the action was activated, false if the action does not exist

#activate_action_variant(name, args) ⇒ Boolean

Looks up the action in the action groups associated with widget and its ancestors, and activates it.

If the action is in an action group added with [methodGtk.Widget.insert_action_group], the name is expected to be prefixed with the prefix that was used when the group was inserted.

The arguments must match the actions expected parameter type, as returned by g_action_get_parameter_type().

Parameters:

  • name (String) —

    the name of the action to activate

  • args (GLib::Variant) —

    parameters to use

Returns:

  • (Boolean) —

    true if the action was activated, false if the action does not exist.

#activate_default ⇒ nil

Activates the default.activate action from widget.

Returns:

  • (nil)

#activate_signal ⇒ Integer

Retrieves the signal id for the activation signal.

the activation signal is set using [methodGtk.WidgetClass.set_activate_signal].

Returns:

  • (Integer) —

    a signal id, or 0 if the widget class does not specify an activation signal

#activate_signal=(signal_id) ⇒ nil

Sets the GtkWidgetClass.activate_signal field with the given signal_id.

The signal will be emitted when calling [methodGtk.Widget.activate].

The signal_id must have been registered with g_signal_new() or g_signal_newv() before calling this function.

Parameters:

  • signal_id (Integer) —

    the id for the activate signal

Returns:

  • (nil)

#activate_signal_from_name=(signal_name) ⇒ nil

Sets the GtkWidgetClass.activate_signal field with the signal id for the given signal_name.

The signal will be emitted when calling [methodGtk.Widget.activate].

The signal_name of widget_type must have been registered with g_signal_new() or g_signal_newv() before calling this function.

Parameters:

  • signal_name (String) —

    the name of the activate signal of widget_type

Returns:

  • (nil)

#add_binding(keyval, mods, callback, format_string, array) ⇒ nil

Creates a new shortcut for widget_class that calls the given callback with arguments read according to format_string.

The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around [methodGtk.WidgetClass.add_shortcut] and must be called during class initialization. It does not provide for user_data, if you need that, you will have to use [methodGtk.WidgetClass.add_shortcut] with a custom shortcut.

Parameters:

  • keyval (Integer) —

    key value of binding to install

  • mods (Gdk::ModifierType) —

    key modifier of binding to install

  • callback (Gtk::ShortcutFunc) —

    the callback to call upon activation

  • format_string (String) —

    GVariant format string for arguments or nil for no arguments

  • array (Array) —

    arguments, as given by format string

Returns:

  • (nil)

#add_binding_action(keyval, mods, action_name, format_string, array) ⇒ nil

Creates a new shortcut for widget_class that activates the given action_name with arguments read according to format_string.

The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around [methodGtk.WidgetClass.add_shortcut] and must be called during class initialization.

Parameters:

  • keyval (Integer) —

    key value of binding to install

  • mods (Gdk::ModifierType) —

    key modifier of binding to install

  • action_name (String) —

    the action to activate

  • format_string (String) —

    GVariant format string for arguments or nil for no arguments

  • array (Array) —

    arguments, as given by format string

Returns:

  • (nil)

#add_binding_signal(keyval, mods, signal, format_string, array) ⇒ nil

Creates a new shortcut for widget_class that emits the given action signal with arguments read according to format_string.

The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around [methodGtk.WidgetClass.add_shortcut] and must be called during class initialization.

Parameters:

  • keyval (Integer) —

    key value of binding to install

  • mods (Gdk::ModifierType) —

    key modifier of binding to install

  • signal (String) —

    the signal to execute

  • format_string (String) —

    GVariant format string for arguments or nil for no arguments

  • array (Array) —

    arguments, as given by format string

Returns:

  • (nil)

#add_controller(controller) ⇒ nil

Adds controller to widget so that it will receive events.

You will usually want to call this function right after creating any kind of [classGtk.EventController].

Parameters:

Returns:

  • (nil)

#add_css_class(css_class) ⇒ nil

Adds a style class to widget.

After calling this function, the widget’s style will match for css_class, according to CSS matching rules.

Use [methodGtk.Widget.remove_css_class] to remove the style again.

Parameters:

  • css_class (String) —

    The style class to add to widget, without the leading '.' used for notation of style classes

Returns:

  • (nil)

#add_mnemonic_label(label) ⇒ nil

Adds a widget to the list of mnemonic labels for this widget.

See [methodGtk.Widget.list_mnemonic_labels]. Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well.

Parameters:

  • label (Gtk::Widget) —

    a GtkWidget that acts as a mnemonic label for widget

Returns:

  • (nil)

#add_shortcut(shortcut) ⇒ nil

Installs a shortcut in widget_class.

Every instance created for widget_class or its subclasses will inherit this shortcut and trigger it.

Shortcuts added this way will be triggered in the %GTK_PHASE_BUBBLE phase, which means they may also trigger if child widgets have focus.

This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed.

Parameters:

Returns:

  • (nil)

#add_tick_callback(callback, user_data, notify) ⇒ Integer

Queues an animation frame update and adds a callback to be called before each frame.

Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a GtkLabel), then you will have to call [methodGtk.Widget.queue_resize] or [methodGtk.Widget.queue_draw] yourself.

[methodGdk.FrameClock.get_frame_time] should generally be used for timing continuous animations and [methodGdk.FrameTimings.get_predicted_presentation_time] if you are trying to display isolated frames at particular times.

This is a more convenient alternative to connecting directly to the [signalGdk.FrameClock::update] signal of GdkFrameClock, since you don't have to worry about when a GdkFrameClock is assigned to a widget.

Parameters:

  • callback (Gtk::TickCallback) —

    function to call for updating animations

  • user_data (GObject) —

    data to pass to callback

  • notify (GLib::DestroyNotify) —

    function to call to free user_data when the callback is removed.

Returns:

  • (Integer) —

    an id for the connection of this callback. Remove the callback by passing the id returned from this function to [methodGtk.Widget.remove_tick_callback]

#allocate(width, height, baseline, transform) ⇒ nil

This function is only used by GtkWidget subclasses, to assign a size, position and (optionally) baseline to their child widgets.

In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size.

For a version that does not take a transform, see [methodGtk.Widget.size_allocate].

Parameters:

  • width (Integer) —

    New width of widget

  • height (Integer) —

    New height of widget

  • baseline (Integer) —

    New baseline of widget, or -1

  • transform (Gsk::Transform) —

    Transformation to be applied to widget

Returns:

  • (nil)

#allocated_baseline ⇒ Integer

Returns the baseline that has currently been allocated to widget.

This function is intended to be used when implementing handlers for the GtkWidgetClass.snapshot() function, and when allocating child widgets in GtkWidgetClass.size_allocate().

Returns:

  • (Integer) —

    the baseline of the widget, or -1 if none

#allocated_height ⇒ Integer

Returns the height that has currently been allocated to widget.

To learn more about widget sizes, see the coordinate system overview.

Returns:

  • (Integer) —

    the height of the widget

#allocated_width ⇒ Integer

Returns the width that has currently been allocated to widget.

To learn more about widget sizes, see the coordinate system overview.

Returns:

  • (Integer) —

    the width of the widget

#baseline ⇒ Integer

Returns the baseline that has currently been allocated to widget.

This function is intended to be used when implementing handlers for the GtkWidgetClass.snapshot() function, and when allocating child widgets in GtkWidgetClass.size_allocate().

Returns:

  • (Integer) —

    the baseline of the widget, or -1 if none

#bind_template_callback_full(callback_name, callback_symbol) ⇒ nil

Declares a callback_symbol to handle callback_name from the template XML defined for widget_type.

This function is not supported after [methodGtk.WidgetClass.set_template_scope] has been used on widget_class. See [methodGtk.BuilderCScope.add_callback_symbol].

Note that this must be called from a composite widget classes class initializer after calling [methodGtk.WidgetClass.set_template].

Parameters:

  • callback_name (String) —

    The name of the callback as expected in the template XML

  • callback_symbol (GObject::Callback) —

    The callback symbol

Returns:

  • (nil)

#bind_template_child_full(name, internal_child, struct_offset) ⇒ nil

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 [methodGtk.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 GObjectClass.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 nil. You can however access an automated child pointer the first time your classes GObjectClass.dispose() runs, or alternatively in [signalGtk.Widget::destroy].

If internal_child is specified, [vfuncGtk.Buildable.get_internal_child] will be automatically implemented by the GtkWidget class so there is no need to implement it manually.

The wrapper macros [funcGtk.widget_class_bind_template_child], [funcGtk.widget_class_bind_template_child_internal], [funcGtk.widget_class_bind_template_child_private] and [funcGtk.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 [methodGtk.WidgetClass.set_template].

Parameters:

  • name (String) —

    The “id” of the child defined in the template XML

  • internal_child (Boolean) —

    Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML

  • struct_offset (Gtk::gssize) —

    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.

Returns:

  • (nil)

#can_focus ⇒ Boolean

Determines whether the input focus can enter widget or any of its children.

See [methodGtk.Widget.set_focusable].

Returns:

  • (Boolean) —

    true if the input focus can enter widget, false otherwise

#can_focus=(can_focus) ⇒ Boolean

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Parameters:

  • can_focus (Boolean)

Returns:

  • (Boolean) —

    can-focus

  • (Boolean) —

    can-focus

#can_focus? ⇒ Boolean

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Returns:

  • (Boolean) —

    can-focus

#can_target ⇒ Boolean

Queries whether widget can be the target of pointer events.

Returns:

  • (Boolean) —

    true if widget can receive pointer events

#can_target=(can_target) ⇒ Boolean

Whether the widget can receive pointer events.

Parameters:

  • can_target (Boolean)

Returns:

  • (Boolean) —

    can-target

  • (Boolean) —

    can-target

#can_target? ⇒ Boolean

Whether the widget can receive pointer events.

Returns:

  • (Boolean) —

    can-target

#child_focus(direction) ⇒ Boolean

Called by widgets as the user moves around the window using keyboard shortcuts.

The direction argument indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward).

This function calls the [vfuncGtk.Widget.focus] virtual function; widgets can override the virtual function in order to implement appropriate focus behavior.

The default focus() virtual function for a widget should return TRUE if moving in direction left the focus on a focusable location inside that widget, and FALSE if moving in direction moved the focus outside the widget. When returning TRUE, widgets normally call [methodGtk.Widget.grab_focus] to place the focus accordingly; when returning FALSE, they don’t modify the current focus location.

This function is used by custom widget implementations; if you're writing an app, you’d use [methodGtk.Widget.grab_focus] to move the focus to a particular widget.

Parameters:

Returns:

  • (Boolean) —

    true if focus ended up inside widget

#child_visible ⇒ Boolean

Gets the value set with gtk_widget_set_child_visible().

If you feel a need to use this function, your code probably needs reorganization.

This function is only useful for container implementations and should never be called by an application.

Returns:

  • (Boolean) —

    true if the widget is mapped with the parent.

#child_visible=(child_visible) ⇒ nil

Sets whether widget should be mapped along with its parent.

The child visibility can be set for widget before it is added to a container with [methodGtk.Widget.set_parent], to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of true when the widget is removed from a container.

Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself.

This function is only useful for container implementations and should never be called by an application.

Parameters:

  • child_visible (Boolean) —

    if true, widget should be mapped along with its parent.

Returns:

  • (nil)

#clipboard ⇒ Gdk::Clipboard

Gets the clipboard object for widget.

This is a utility function to get the clipboard object for the GdkDisplay that widget is using.

Note that this function always works, even when widget is not realized yet.

Returns:

  • (Gdk::Clipboard) —

    the appropriate clipboard object

#compute_bounds(target, out_bounds) ⇒ Boolean

Computes the bounds for widget in the coordinate space of target.

The bounds of widget are (the bounding box of) the region that it is expected to draw in. See the coordinate system overview to learn more.

If the operation is successful, true is returned. If widget has no bounds or the bounds cannot be expressed in target's coordinate space (for example if both widgets are in different windows), false is returned and bounds is set to the zero rectangle.

It is valid for widget and target to be the same widget.

Parameters:

  • target (Gtk::Widget) —

    the GtkWidget

  • out_bounds (Graphene::Rect) —

    the rectangle taking the bounds

Returns:

  • (Boolean) —

    true if the bounds could be computed

#compute_expand(orientation) ⇒ Boolean

Computes whether a container should give this widget extra space when possible.

Containers should check this, rather than looking at [methodGtk.Widget.get_hexpand] or [methodGtk.Widget.get_vexpand].

This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded.

The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do.

Parameters:

Returns:

  • (Boolean) —

    whether widget tree rooted here should be expanded

#compute_point(target, point, out_point) ⇒ Boolean

Translates the given point in widget's coordinates to coordinates relative to target’s coordinate system.

In order to perform this operation, both widgets must share a common ancestor.

Parameters:

  • target (Gtk::Widget) —

    the GtkWidget to transform into

  • point (Graphene::Point) —

    a point in widget's coordinate system

  • out_point (Graphene::Point) —

    Set to the corresponding coordinates in target's coordinate system

Returns:

  • (Boolean) —

    true if the point could be determined, false on failure. In this case, 0 is stored in out_point.

#compute_transform(target, out_transform) ⇒ Boolean

Computes a matrix suitable to describe a transformation from widget's coordinate system into target's coordinate system.

The transform can not be computed in certain cases, for example when widget and target do not share a common ancestor. In that case out_transform gets set to the identity matrix.

To learn more about widget coordinate systems, see the coordinate system overview.

Parameters:

  • target (Gtk::Widget) —

    the target widget that the matrix will transform to

  • out_transform (Graphene::Matrix) —

    location to store the final transformation

Returns:

  • (Boolean) —

    true if the transform could be computed, false otherwise

#contains(x, y) ⇒ Boolean

Tests if the point at (x, y) is contained in widget.

The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of widget's content area.

Parameters:

  • x (Float) —

    X coordinate to test, relative to widget's origin

  • y (Float) —

    Y coordinate to test, relative to widget's origin

Returns:

  • (Boolean) —

    true if widget contains (x, y).

#create_pango_context ⇒ Pango::Context

Creates a new PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget.

See also [methodGtk.Widget.get_pango_context].

Returns:

  • (Pango::Context) —

    the new PangoContext

#create_pango_layout(text) ⇒ Pango::Layout

Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.

If you keep a PangoLayout created in this way around, you need to re-create it when the widget PangoContext is replaced. This can be tracked by listening to changes of the [propertyGtk.Widget:root] property on the widget.

Parameters:

  • text (String) —

    text to set on the layout

Returns:

  • (Pango::Layout) —

    the new PangoLayout

#css_classes ⇒ Gtk::

A list of css classes applied to this widget.

Returns:

  • (Gtk::) —

    css-classes

#css_classes=(css_classes) ⇒ Gtk::

A list of css classes applied to this widget.

Parameters:

Returns:

#css_name ⇒ String

Gets the name used by this class for matching in CSS code.

See [methodGtk.WidgetClass.set_css_name] for details.

Returns:

  • (String) —

    the CSS name of the given class

#css_name=(name) ⇒ nil

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

If this function is not called for a given class, the name set on the parent class is used. By default, GtkWidget uses the name "widget".

Parameters:

  • name (String) —

    name to use

Returns:

  • (nil)

#cursor ⇒ Gdk::Cursor

The cursor used by widget.

Returns:

  • (Gdk::Cursor) —

    cursor

#cursor=(cursor) ⇒ Gdk::Cursor

The cursor used by widget.

Parameters:

  • cursor (Gdk::Cursor)

Returns:

  • (Gdk::Cursor) —

    cursor

  • (Gdk::Cursor) —

    cursor

#cursor_from_name=(name) ⇒ nil

Sets a named cursor to be shown when pointer devices point towards widget.

This is a utility function that creates a cursor via [ctorGdk.Cursor.new_from_name] and then sets it on widget with [methodGtk.Widget.set_cursor]. See those functions for details.

On top of that, this function allows name to be nil, which will do the same as calling [methodGtk.Widget.set_cursor] with a nil cursor.

Parameters:

  • name (String) —

    The name of the cursor

Returns:

  • (nil)

#direction ⇒ Gtk::TextDirection

Gets the reading direction for a particular widget.

See [methodGtk.Widget.set_direction].

Returns:

#direction=(dir) ⇒ nil

Sets the reading direction on a particular widget.

This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification).

If the direction is set to %GTK_TEXT_DIR_NONE, then the value set by [funcGtk.Widget.set_default_direction] will be used.

Parameters:

Returns:

  • (nil)

#display ⇒ Gdk::Display

Get the GdkDisplay for the toplevel window associated with this widget.

This function can only be called after the widget has been added to a widget hierarchy with a GtkWindow at the top.

In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

Returns:

  • (Gdk::Display) —

    the GdkDisplay for the toplevel for this widget.

#dispose_template(widget_type) ⇒ nil

Clears the template children for the given widget.

This function is the opposite of [methodGtk.Widget.init_template], and it is used to clear all the template children from a widget instance. If you bound a template child to a field in the instance structure, or in the instance private data structure, the field will be set to NULL after this function returns.

You should call this function inside the GObjectClass.dispose() implementation of any widget that called gtk_widget_init_template(). Typically, you will want to call this function last, right before chaining up to the parent type's dispose implementation, e.g.

static void
some_widget_dispose (GObject *gobject)
{
  SomeWidget *self = SOME_WIDGET (gobject);

  // Clear the template data for SomeWidget
  gtk_widget_dispose_template (GTK_WIDGET (self), SOME_TYPE_WIDGET);

  G_OBJECT_CLASS (some_widget_parent_class)->dispose (gobject);
}

Parameters:

  • widget_type (GLib::Type) —

    the type of the widget to finalize the template for

Returns:

  • (nil)

#drag_check_threshold(start_x, start_y, current_x, current_y) ⇒ Boolean

Checks to see if a drag movement has passed the GTK drag threshold.

Parameters:

  • start_x (Integer) —

    X coordinate of start of drag

  • start_y (Integer) —

    Y coordinate of start of drag

  • current_x (Integer) —

    current X coordinate

  • current_y (Integer) —

    current Y coordinate

Returns:

  • (Boolean) —

    true if the drag threshold has been passed.

#error_bell ⇒ nil

Notifies the user about an input-related error on this widget.

If the [propertyGtk.Settings:gtk-error-bell] setting is true, it calls [methodGdk.Surface.beep], otherwise it does nothing.

Note that the effect of [methodGdk.Surface.beep] can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

Returns:

  • (nil)

#first_child ⇒ Gtk::Widget

Returns the widget’s first child.

This API is primarily meant for widget implementations.

Returns:

#focus_child ⇒ Gtk::Widget

Returns the current focus child of widget.

Returns:

#focus_child=(child) ⇒ nil

Set child as the current focus child of widget.

This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [methodGtk.Widget.grab_focus] on it.

Parameters:

  • child (Gtk::Widget) —

    a direct child widget of widget or nil to unset the focus child of widget

Returns:

  • (nil)

#focus_on_click ⇒ Boolean

Returns whether the widget should grab focus when it is clicked with the mouse.

See [methodGtk.Widget.set_focus_on_click].

Returns:

  • (Boolean) —

    true if the widget should grab focus when it is clicked with the mouse

#focus_on_click=(focus_on_click) ⇒ Boolean

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Parameters:

  • focus_on_click (Boolean)

Returns:

  • (Boolean) —

    focus-on-click

  • (Boolean) —

    focus-on-click

#focus_on_click? ⇒ Boolean

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Returns:

  • (Boolean) —

    focus-on-click

#focusable ⇒ Boolean

Determines whether widget can own the input focus.

See [methodGtk.Widget.set_focusable].

Returns:

  • (Boolean) —

    true if widget can own the input focus, false otherwise

#focusable=(focusable) ⇒ Boolean

Whether this widget itself will accept the input focus.

Parameters:

  • focusable (Boolean)

Returns:

  • (Boolean) —

    focusable

  • (Boolean) —

    focusable

#focusable? ⇒ Boolean

Whether this widget itself will accept the input focus.

Returns:

  • (Boolean) —

    focusable

#font_map ⇒ Pango::FontMap

Gets the font map of widget.

See [methodGtk.Widget.set_font_map].

Returns:

  • (Pango::FontMap) —

    A PangoFontMap

#font_map=(font_map) ⇒ nil

Sets the font map to use for Pango rendering.

The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, e.g. when you need to add application-specific fonts to the set of available fonts.

When not set, the widget will inherit the font map from its parent.

Parameters:

  • font_map (Pango::FontMap) —

    a PangoFontMap, or nil to unset any previously set font map

Returns:

  • (nil)

#font_options ⇒ cairo::FontOptions

Returns the cairo_font_options_t of widget.

Seee [methodGtk.Widget.set_font_options].

Returns:

  • (cairo::FontOptions) —

    the cairo_font_options_t of widget

#font_options=(options) ⇒ nil

Sets the cairo_font_options_t used for Pango rendering in this widget.

When not set, the default font options for the GdkDisplay will be used.

Parameters:

  • options (cairo::FontOptions) —

    a cairo_font_options_t to unset any previously set default font options

Returns:

  • (nil)

#frame_clock ⇒ Gdk::FrameClock

Obtains the frame clock for a widget.

The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call [methodGdk.FrameClock.get_frame_time], in order to get a time to use for animating. For example you might record the start of the animation with an initial value from [methodGdk.FrameClock.get_frame_time], and then update the animation by calling [methodGdk.FrameClock.get_frame_time] again during each repaint.

[methodGdk.FrameClock.request_phase] will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use [methodGtk.Widget.queue_draw] which invalidates the widget (thus scheduling it to receive a draw on the next frame). gtk_widget_queue_draw() will also end up requesting a frame on the appropriate frame clock.

A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock.

Unrealized widgets do not have a frame clock.

Returns:

  • (Gdk::FrameClock) —

    a GdkFrameClock

#get_allocation(allocation) ⇒ nil

Retrieves the widget’s allocation.

Note, when implementing a layout container: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent typically calls [methodGtk.Widget.size_allocate] with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. [methodGtk.Widget.get_allocation] returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the [methodGtk.Widget.size_allocate] allocation, however.

So a layout container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned.

Parameters:

  • allocation (Gtk::Allocation) —

    a pointer to a GtkAllocation to copy to

Returns:

  • (nil)

#get_ancestor(widget_type) ⇒ Gtk::Widget

Gets the first ancestor of widget with type widget_type.

For example, gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first GtkBox that’s an ancestor of widget. No reference will be added to the returned widget; it should not be unreferenced.

Note that unlike [methodGtk.Widget.is_ancestor], this function considers widget to be an ancestor of itself.

Parameters:

  • widget_type (GLib::Type) —

    ancestor type

Returns:

#get_color(color) ⇒ nil

Gets the current foreground color for the widget’s CSS style.

This function should only be used in snapshot implementations that need to do custom drawing with the foreground color.

Parameters:

  • color (Gdk::RGBA) —

    return location for the color

Returns:

  • (nil)

#get_preferred_size(minimum_size, natural_size) ⇒ nil

Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.

This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkFixed.

Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width.

Use [methodGtk.Widget.measure] if you want to support baseline alignment.

Parameters:

  • minimum_size (Gtk::Requisition) —

    location for storing the minimum size

  • natural_size (Gtk::Requisition) —

    location for storing the natural size

Returns:

  • (nil)

#get_size(orientation) ⇒ Integer

Returns the content width or height of the widget.

Which dimension is returned depends on orientation.

This is equivalent to calling [methodGtk.Widget.get_width] for %GTK_ORIENTATION_HORIZONTAL or [methodGtk.Widget.get_height] for %GTK_ORIENTATION_VERTICAL, but can be used when writing orientation-independent code, such as when implementing [ifaceGtk.Orientable] widgets.

To learn more about widget sizes, see the coordinate system overview.

Parameters:

Returns:

  • (Integer) —

    The size of widget in orientation.

#get_size_request(width, height) ⇒ nil

Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request().

A value of -1 stored in width or height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See [methodGtk.Widget.set_size_request]. To get the size a widget will actually request, call [methodGtk.Widget.measure] instead of this function.

Parameters:

  • width (Integer) —

    return location for width

  • height (Integer) —

    return location for height

Returns:

  • (nil)

#get_template_child(widget_type, name) ⇒ GObject::Object

Fetch an object build from the template XML for widget_type in this widget instance.

This will only report children which were previously declared with [methodGtk.WidgetClass.bind_template_child_full] or one of its variants.

This function is only meant to be called for code which is private to the widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets.

Parameters:

  • widget_type (GLib::Type) —

    The GType to get a template child for

  • name (String) —

    The “id” of the child defined in the template XML

Returns:

  • (GObject::Object) —

    The object built in the template XML with the id name

#grab_focus ⇒ Boolean

Causes widget to have the keyboard focus for the GtkWindow it's inside.

If widget is not focusable, or its [vfuncGtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of widget that is focusable, it will not take focus and false will be returned.

Calling [methodGtk.Widget.grab_focus] on an already focused widget is allowed, should not have an effect, and return true.

Returns:

  • (Boolean) —

    true if focus is now inside widget.

#halign ⇒ Gtk::Align

How to distribute horizontal space if widget gets extra space.

Returns:

#halign=(halign) ⇒ Gtk::Align

How to distribute horizontal space if widget gets extra space.

Parameters:

Returns:

#has_css_class(css_class) ⇒ Boolean

Returns whether css_class is currently applied to widget.

Parameters:

  • css_class (String) —

    A style class, without the leading '.' used for notation of style classes

Returns:

  • (Boolean) —

    true if css_class is currently applied to widget, false otherwise.

#has_default ⇒ Boolean

Determines whether widget is the current default widget within its toplevel.

Returns:

  • (Boolean) —

    true if widget is the current default widget within its toplevel, false otherwise

#has_default=(has_default) ⇒ Boolean

Whether the widget is the default widget.

Parameters:

  • has_default (Boolean)

Returns:

  • (Boolean) —

    has-default

  • (Boolean) —

    has-default

#has_default? ⇒ Boolean

Whether the widget is the default widget.

Returns:

  • (Boolean) —

    has-default

#has_focus ⇒ Boolean

Determines if the widget has the global input focus.

See [methodGtk.Widget.is_focus] for the difference between having the global input focus, and only having the focus within a toplevel.

Returns:

  • (Boolean) —

    true if the widget has the global input focus.

#has_focus=(has_focus) ⇒ Boolean

Whether the widget has the input focus.

Parameters:

  • has_focus (Boolean)

Returns:

  • (Boolean) —

    has-focus

  • (Boolean) —

    has-focus

#has_focus? ⇒ Boolean

Whether the widget has the input focus.

Returns:

  • (Boolean) —

    has-focus

#has_tooltip ⇒ Boolean

Returns the current value of the has-tooltip property.

Returns:

  • (Boolean) —

    current value of has-tooltip on widget.

#has_tooltip=(has_tooltip) ⇒ Boolean

Enables or disables the emission of the ::query-tooltip signal on widget.

A value of true indicates that widget can have a tooltip, in this case the widget will be queried using [signalGtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not.

Parameters:

  • has_tooltip (Boolean)

Returns:

  • (Boolean) —

    has-tooltip

  • (Boolean) —

    has-tooltip

#has_tooltip? ⇒ Boolean

Enables or disables the emission of the ::query-tooltip signal on widget.

A value of true indicates that widget can have a tooltip, in this case the widget will be queried using [signalGtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not.

Returns:

  • (Boolean) —

    has-tooltip

#has_visible_focus ⇒ Boolean

Determines if the widget should show a visible indication that it has the global input focus.

This is a convenience function that takes into account whether focus indication should currently be shown in the toplevel window of widget. See [methodGtk.Window.get_focus_visible] for more information about focus indication.

To find out if the widget has the global input focus, use [methodGtk.Widget.has_focus].

Returns:

  • (Boolean) —

    true if the widget should display a “focus rectangle”

#height ⇒ Integer

Returns the content height of the widget.

This function returns the height passed to its size-allocate implementation, which is the height you should be using in [vfuncGtk.Widget.snapshot].

For pointer events, see [methodGtk.Widget.contains].

To learn more about widget sizes, see the coordinate system overview.

Returns:

  • (Integer) —

    The height of widget

#height_request ⇒ Integer

Override for height request of the widget.

If this is -1, the natural request will be used.

Returns:

  • (Integer) —

    height-request

#height_request=(height_request) ⇒ Integer

Override for height request of the widget.

If this is -1, the natural request will be used.

Parameters:

  • height_request (Integer)

Returns:

  • (Integer) —

    height-request

  • (Integer) —

    height-request

#hexpand ⇒ Boolean

Gets whether the widget would like any available extra horizontal space.

When a user resizes a GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.

Containers should use [methodGtk.Widget.compute_expand] rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also.

This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand.

Returns:

  • (Boolean) —

    whether hexpand flag is set

#hexpand=(hexpand) ⇒ Boolean

Whether to expand horizontally.

Parameters:

  • hexpand (Boolean)

Returns:

  • (Boolean) —

    hexpand

  • (Boolean) —

    hexpand

#hexpand? ⇒ Boolean

Whether to expand horizontally.

Returns:

  • (Boolean) —

    hexpand

#hexpand_set ⇒ Boolean

Gets whether gtk_widget_set_hexpand() has been used to explicitly set the expand flag on this widget.

If [propertyGtk.Widget:hexpand] property is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.

There are few reasons to use this function, but it’s here for completeness and consistency.

Returns:

  • (Boolean) —

    whether hexpand has been explicitly set

#hexpand_set=(hexpand_set) ⇒ Boolean

Whether to use the hexpand property.

Parameters:

  • hexpand_set (Boolean)

Returns:

  • (Boolean) —

    hexpand-set

  • (Boolean) —

    hexpand-set

#hexpand_set? ⇒ Boolean

Whether to use the hexpand property.

Returns:

  • (Boolean) —

    hexpand-set

#hide ⇒ nil

Reverses the effects of gtk_widget_show().

This is causing the widget to be hidden (invisible to the user).

Returns:

  • (nil)

#in_destruction ⇒ Boolean

Returns whether the widget is currently being destroyed.

This information can sometimes be used to avoid doing unnecessary work.

Returns:

  • (Boolean) —

    true if widget is being destroyed

#init_template ⇒ nil

Creates and initializes child widgets defined in templates.

This function must be called in the instance initializer for any class which assigned itself a template using [methodGtk.WidgetClass.set_template].

It is important to call this function in the instance initializer of a GtkWidget subclass and not in GObject.constructed() or GObject.constructor() for two reasons:

  • derived widgets will assume that the composite widgets defined by its parent classes have been created in their relative instance initializers
  • when calling g_object_new() on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to g_object_new() should take precedence over properties set in the private template XML

A good rule of thumb is to call this function as the first thing in an instance initialization function.

Returns:

  • (nil)

#insert_action_group(name, group) ⇒ nil

Inserts group into widget.

Children of widget that implement [ifaceGtk.Actionable] can then be associated with actions in group by setting their “action-name” to prefix.action-name.

Note that inheritance is defined for individual actions. I.e. even if you insert a group with prefix prefix, actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name.

If group is nil, a previously inserted group for name is removed from widget.

Parameters:

  • name (String) —

    the prefix for actions in group

  • group (Gio::ActionGroup) —

    a GActionGroup, or nil to remove the previously inserted group for name

Returns:

  • (nil)

#insert_after(parent, previous_sibling) ⇒ nil

Inserts widget into the child widget list of parent.

It will be placed after previous_sibling, or at the beginning if previous_sibling is nil.

After calling this function, gtk_widget_get_prev_sibling(widget) will return previous_sibling.

If parent is already set as the parent widget of widget, this function can also be used to reorder widget in the child widget list of parent.

This API is primarily meant for widget implementations; if you are just using a widget, you must use its own API for adding children.

Parameters:

  • parent (Gtk::Widget) —

    the parent GtkWidget to insert widget into

  • previous_sibling (Gtk::Widget) —

    the new previous sibling of widget

Returns:

  • (nil)

#insert_before(parent, next_sibling) ⇒ nil

Inserts widget into the child widget list of parent.

It will be placed before next_sibling, or at the end if next_sibling is nil.

After calling this function, gtk_widget_get_next_sibling(widget) will return next_sibling.

If parent is already set as the parent widget of widget, this function can also be used to reorder widget in the child widget list of parent.

This API is primarily meant for widget implementations; if you are just using a widget, you must use its own API for adding children.

Parameters:

  • parent (Gtk::Widget) —

    the parent GtkWidget to insert widget into

  • next_sibling (Gtk::Widget) —

    the new next sibling of widget

Returns:

  • (nil)

#install_action(action_name, parameter_type, activate) ⇒ nil

This should be called at class initialization time to specify actions to be added for all instances of this class.

Actions installed by this function are stateless. The only state they have is whether they are enabled or not (which can be changed with [methodGtk.Widget.action_set_enabled]).

Parameters:

  • action_name (String) —

    a prefixed action name, such as "clipboard.paste"

  • parameter_type (String) —

    the parameter type

  • activate (Gtk::WidgetActionActivateFunc) —

    callback to use when the action is activated

Returns:

  • (nil)

#install_property_action(action_name, property_name) ⇒ nil

Installs an action called action_name on widget_class and binds its state to the value of the property_name property.

This function will perform a few sanity checks on the property selected via property_name. Namely, the property must exist, must be readable, writable and must not be construct-only. There are also restrictions on the type of the given property, it must be boolean, int, unsigned int, double or string. If any of these conditions are not met, a critical warning will be printed and no action will be added.

The state type of the action matches the property type.

If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property.

Parameters:

  • action_name (String) —

    name of the action

  • property_name (String) —

    name of the property in instances of widget_class or any parent class.

Returns:

  • (nil)

#is_ancestor(ancestor) ⇒ Boolean

Determines whether widget is somewhere inside ancestor, possibly with intermediate containers.

Parameters:

Returns:

  • (Boolean) —

    true if ancestor contains widget as a child, grandchild, great grandchild, etc.

#is_drawable ⇒ Boolean

Determines whether widget can be drawn to.

A widget can be drawn if it is mapped and visible.

Returns:

  • (Boolean) —

    true if widget is drawable, false otherwise

#is_focus ⇒ Boolean

Determines if the widget is the focus widget within its toplevel.

This does not mean that the [propertyGtk.Widget:has-focus] property is necessarily set; [propertyGtk.Widget:has-focus] will only be set if the toplevel widget additionally has the global input focus.

Returns:

  • (Boolean) —

    true if the widget is the focus widget.

#is_sensitive ⇒ Boolean

Returns the widget’s effective sensitivity.

This means it is sensitive itself and also its parent widget is sensitive.

Returns:

  • (Boolean) —

    true if the widget is effectively sensitive

#is_visible ⇒ Boolean

Determines whether the widget and all its parents are marked as visible.

This function does not check if the widget is obscured in any way.

See also [methodGtk.Widget.get_visible] and [methodGtk.Widget.set_visible].

Returns:

  • (Boolean) —

    true if the widget and all its parents are visible

#keynav_failed(direction) ⇒ Boolean

Emits the ::keynav-failed signal on the widget.

This function should be called whenever keyboard navigation within a single widget hits a boundary.

The return value of this function should be interpreted in a way similar to the return value of [methodGtk.Widget.child_focus]. When true is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [methodGtk.Widget.child_focus] on the widget’s toplevel.

The default [signalGtk.Widget::keynav-failed] handler returns false for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of GtkDirectionType it returns true.

Whenever the default handler returns true, it also calls [methodGtk.Widget.error_bell] to notify the user of the failed keyboard navigation.

A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of [classGtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.

Parameters:

Returns:

  • (Boolean) —

    true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).

#last_child ⇒ Gtk::Widget

Returns the widget’s last child.

This API is primarily meant for widget implementations.

Returns:

#layout_manager ⇒ Gtk::LayoutManager

The GtkLayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Returns:

#layout_manager=(layout_manager) ⇒ Gtk::LayoutManager

The GtkLayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Parameters:

Returns:

#layout_manager_type ⇒ GLib::Type

Retrieves the type of the [classGtk.LayoutManager] used by widgets of class widget_class.

See also: [methodGtk.WidgetClass.set_layout_manager_type].

Returns:

  • (GLib::Type) —

    type of a GtkLayoutManager subclass, or %G_TYPE_INVALID

#layout_manager_type=(type) ⇒ nil

Sets the type to be used for creating layout managers for widgets of widget_class.

The given type must be a subtype of [classGtk.LayoutManager].

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

Parameters:

  • type (GLib::Type) —

    The object type that implements the GtkLayoutManager for widget_class

Returns:

  • (nil)

#list_mnemonic_labels ⇒ GLib::List<Gtk::Widget>

Returns the widgets for which this widget is the target of a mnemonic.

Typically, these widgets will be labels. See, for example, [methodGtk.Label.set_mnemonic_widget].

The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call g_list_foreach (result, (GFunc)g_object_ref, NULL) first, and then unref all the widgets afterwards.

Returns:

  • (GLib::List<Gtk::Widget>) —

    the list of mnemonic labels; free this list with g_list_free() when you are done with it.

#map ⇒ nil

Causes a widget to be mapped if it isn’t already.

This function is only for use in widget implementations.

Returns:

  • (nil)

#mapped ⇒ Boolean

Whether the widget is mapped.

Returns:

  • (Boolean) —

    true if the widget is mapped, false otherwise.

#margin_bottom ⇒ Integer

Margin on bottom side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Returns:

  • (Integer) —

    margin-bottom

#margin_bottom=(margin_bottom) ⇒ Integer

Margin on bottom side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Parameters:

  • margin_bottom (Integer)

Returns:

  • (Integer) —

    margin-bottom

  • (Integer) —

    margin-bottom

#margin_end ⇒ Integer

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Returns:

  • (Integer) —

    margin-end

#margin_end=(margin_end) ⇒ Integer

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Parameters:

  • margin_end (Integer)

Returns:

  • (Integer) —

    margin-end

  • (Integer) —

    margin-end

#margin_start ⇒ Integer

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Returns:

  • (Integer) —

    margin-start

#margin_start=(margin_start) ⇒ Integer

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Parameters:

  • margin_start (Integer)

Returns:

  • (Integer) —

    margin-start

  • (Integer) —

    margin-start

#margin_top ⇒ Integer

Margin on top side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Returns:

  • (Integer) —

    margin-top

#margin_top=(margin_top) ⇒ Integer

Margin on top side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [methodGtk.Widget.set_size_request] for example.

Parameters:

  • margin_top (Integer)

Returns:

  • (Integer) —

    margin-top

  • (Integer) —

    margin-top

#measure(orientation, for_size, minimum, natural, minimum_baseline, natural_baseline) ⇒ nil

Measures widget in the orientation orientation and for the given for_size.

As an example, if orientation is %GTK_ORIENTATION_HORIZONTAL and for_size is 300, this functions will compute the minimum and natural width of widget if it is allocated at a height of 300 pixels.

See GtkWidget’s geometry management section for a more details on implementing GtkWidgetClass.measure().

Parameters:

  • orientation (Gtk::Orientation) —

    the orientation to measure

  • for_size (Integer) —

    Size for the opposite of orientation, i.e. if orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed.

  • minimum (Integer) —

    location to store the minimum size

  • natural (Integer) —

    location to store the natural size

  • minimum_baseline (Integer) —

    location to store the baseline position for the minimum size, or -1 to report no baseline

  • natural_baseline (Integer) —

    location to store the baseline position for the natural size, or -1 to report no baseline

Returns:

  • (nil)

#mnemonic_activate(group_cycling) ⇒ Boolean

Emits the ::mnemonic-activate signal.

See [signalGtk.Widget::mnemonic-activate].

Parameters:

  • group_cycling (Boolean) —

    true if there are other widgets with the same mnemonic

Returns:

  • (Boolean) —

    true if the signal has been handled

#name ⇒ String

The name of the widget.

Returns:

  • (String) —

    name

#name=(name) ⇒ String

The name of the widget.

Parameters:

  • name (String)

Returns:

  • (String) —

    name

  • (String) —

    name

#native ⇒ Gtk::Native

Returns the nearest GtkNative ancestor of widget.

This function will return nil if the widget is not contained inside a widget tree with a native ancestor.

GtkNative widgets will return themselves here.

Returns:

#next_sibling ⇒ Gtk::Widget

Returns the widget’s next sibling.

This API is primarily meant for widget implementations.

Returns:

#observe_children ⇒ Gio::ListModel

Returns a GListModel to track the children of widget.

Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Returns:

  • (Gio::ListModel) —

    a GListModel tracking widget's children

#observe_controllers ⇒ Gio::ListModel

Returns a GListModel to track the [classGtk.EventController]s of widget.

Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Returns:

  • (Gio::ListModel) —

    a GListModel tracking widget's controllers

#opacity ⇒ Float

The requested opacity of the widget.

Returns:

  • (Float) —

    opacity

#opacity=(opacity) ⇒ Float

The requested opacity of the widget.

Parameters:

  • opacity (Float)

Returns:

  • (Float) —

    opacity

  • (Float) —

    opacity

#overflow ⇒ Gtk::Overflow

How content outside the widget's content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Returns:

#overflow=(overflow) ⇒ Gtk::Overflow

How content outside the widget's content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Parameters:

Returns:

#pango_context ⇒ Pango::Context

Gets a PangoContext with the appropriate font map, font description, and base direction for this widget.

Unlike the context returned by [methodGtk.Widget.create_pango_context], this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by listening to changes of the [propertyGtk.Widget:root] property on the widget.

Returns:

  • (Pango::Context) —

    the PangoContext for the widget.

#parent ⇒ Gtk::Widget

The parent widget of this widget.

Returns:

#parent=(parent) ⇒ Gtk::Widget

The parent widget of this widget.

Parameters:

Returns:

#pick(x, y, flags) ⇒ Gtk::Widget

Finds the descendant of widget closest to the point (x, y).

The point must be given in widget coordinates, so (0, 0) is assumed to be the top left of widget's content area.

Usually widgets will return nil if the given coordinate is not contained in widget checked via [methodGtk.Widget.contains]. Otherwise they will recursively try to find a child that does not return nil. Widgets are however free to customize their picking algorithm.

This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events.

Parameters:

  • x (Float) —

    X coordinate to test, relative to widget's origin

  • y (Float) —

    Y coordinate to test, relative to widget's origin

  • flags (Gtk::PickFlags) —

    Flags to influence what is picked

Returns:

  • (Gtk::Widget) —

    The widget descendant at the given point

#prev_sibling ⇒ Gtk::Widget

Returns the widget’s previous sibling.

This API is primarily meant for widget implementations.

Returns:

#primary_clipboard ⇒ Gdk::Clipboard

Gets the primary clipboard of widget.

This is a utility function to get the primary clipboard object for the GdkDisplay that widget is using.

Note that this function always works, even when widget is not realized yet.

Returns:

  • (Gdk::Clipboard) —

    the appropriate clipboard object

#query_action(index_, owner, action_name, parameter_type, property_name) ⇒ Boolean

Returns details about the index_-th action that has been installed for widget_class during class initialization.

See [methodGtk.WidgetClass.install_action] for details on how to install actions.

Note that this function will also return actions defined by parent classes. You can identify those by looking at owner.

Parameters:

  • index_ (Integer) —

    position of the action to query

  • owner (GLib::Type) —

    return location for the type where the action was defined

  • action_name (String) —

    return location for the action name

  • parameter_type (GLib::VariantType) —

    return location for the parameter type

  • property_name (String) —

    return location for the property name

Returns:

  • (Boolean) —

    true if the action was found, false if index_ is out of range

#queue_allocate ⇒ nil

Flags the widget for a rerun of the [vfuncGtk.Widget.size_allocate] function.

Use this function instead of [methodGtk.Widget.queue_resize] when the widget's size request didn't change but it wants to reposition its contents.

An example user of this function is [methodGtk.Widget.set_halign].

This function is only for use in widget implementations.

Returns:

  • (nil)

#queue_draw ⇒ nil

Schedules this widget to be redrawn in the paint phase of the current or the next frame.

This means widget's [vfuncGtk.Widget.snapshot] implementation will be called.

Returns:

  • (nil)

#queue_resize ⇒ nil

Flags a widget to have its size renegotiated.

This should be called when a widget for some reason has a new size request. For example, when you change the text in a [classGtk.Label], the label queues a resize to ensure there’s enough space for the new text.

Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the [vfuncGtk.Widget.size_allocate] virtual method. Calls to gtk_widget_queue_resize() from inside [vfuncGtk.Widget.size_allocate] will be silently ignored.

This function is only for use in widget implementations.

Returns:

  • (nil)

#realize ⇒ nil

Creates the GDK resources associated with a widget.

Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically.

Realizing a widget requires all the widget’s parent widgets to be realized; calling this function realizes the widget’s parents in addition to widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen.

This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signalGtk.Widget::realize].

Returns:

  • (nil)

#realized ⇒ Boolean

Determines whether widget is realized.

Returns:

  • (Boolean) —

    true if widget is realized, false otherwise

#receives_default ⇒ Boolean

Determines whether widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default.

See [methodGtk.Widget.set_receives_default].

Returns:

  • (Boolean) —

    true if widget acts as the default widget when focused, false otherwise

#receives_default=(receives_default) ⇒ Boolean

Whether the widget will receive the default action when it is focused.

Parameters:

  • receives_default (Boolean)

Returns:

  • (Boolean) —

    receives-default

  • (Boolean) —

    receives-default

#receives_default? ⇒ Boolean

Whether the widget will receive the default action when it is focused.

Returns:

  • (Boolean) —

    receives-default

#remove_controller(controller) ⇒ nil

Removes controller from widget, so that it doesn't process events anymore.

It should not be used again.

Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function.

Parameters:

Returns:

  • (nil)

#remove_css_class(css_class) ⇒ nil

Removes a style from widget.

After this, the style of widget will stop matching for css_class.

Parameters:

  • css_class (String) —

    The style class to remove from widget, without the leading '.' used for notation of style classes

Returns:

  • (nil)

#remove_mnemonic_label(label) ⇒ nil

Removes a widget from the list of mnemonic labels for this widget.

See [methodGtk.Widget.list_mnemonic_labels]. The widget must have previously been added to the list with [methodGtk.Widget.add_mnemonic_label].

Parameters:

  • label (Gtk::Widget) —

    a GtkWidget that was previously set as a mnemonic label for widget with [methodGtk.Widget.add_mnemonic_label]

Returns:

  • (nil)

#remove_tick_callback(id) ⇒ nil

Removes a tick callback previously registered with gtk_widget_add_tick_callback().

Parameters:

  • id (Integer) —

    an id returned by [methodGtk.Widget.add_tick_callback]

Returns:

  • (nil)

#request_mode ⇒ Gtk::SizeRequestMode

Gets whether the widget prefers a height-for-width layout or a width-for-height layout.

Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities.

Returns:

#root ⇒ Gtk::Root

The GtkRoot widget of the widget tree containing this widget.

This will be nil if the widget is not contained in a root widget.

Returns:

#root=(root) ⇒ Gtk::Root

The GtkRoot widget of the widget tree containing this widget.

This will be nil if the widget is not contained in a root widget.

Parameters:

Returns:

#scale_factor ⇒ Integer

The scale factor of the widget.

Returns:

  • (Integer) —

    scale-factor

#scale_factor=(scale_factor) ⇒ Integer

The scale factor of the widget.

Parameters:

  • scale_factor (Integer)

Returns:

  • (Integer) —

    scale-factor

  • (Integer) —

    scale-factor

#sensitive ⇒ Boolean

Returns the widget’s sensitivity.

This function returns the value that has been set using [methodGtk.Widget.set_sensitive]).

The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See [methodGtk.Widget.is_sensitive].

Returns:

  • (Boolean) —

    true if the widget is sensitive

#sensitive=(sensitive) ⇒ Boolean

Whether the widget responds to input.

Parameters:

  • sensitive (Boolean)

Returns:

  • (Boolean) —

    sensitive

  • (Boolean) —

    sensitive

#sensitive? ⇒ Boolean

Whether the widget responds to input.

Returns:

  • (Boolean) —

    sensitive

#set_size_request(width, height) ⇒ nil

Sets the minimum size of a widget.

That is, the widget’s size request will be at least width by height. You can use this function to force a widget to be larger than it normally would be.

In most cases, [methodGtk.Window.set_default_size] is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request.

Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct.

The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested.

If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead.

The size request set here does not include any margin from the properties [propertyGtk.Widget:margin-start], [propertyGtk.Widget:margin-end], [propertyGtk.Widget:margin-top], and [propertyGtk.Widget:margin-bottom], but it does include pretty much all other padding or border properties set by any subclass of GtkWidget.

Parameters:

  • width (Integer) —

    width widget should request, or -1 to unset

  • height (Integer) —

    height widget should request, or -1 to unset

Returns:

  • (nil)

#set_state_flags(flags, clear) ⇒ nil

Turns on flag values in the current widget state.

Typical widget states are insensitive, prelighted, etc.

This function accepts the values %GTK_STATE_FLAG_DIR_LTR and %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's direction, use [methodGtk.Widget.set_direction].

This function is for use in widget implementations.

Parameters:

  • flags (Gtk::StateFlags) —

    State flags to turn on

  • clear (Boolean) —

    Whether to clear state before turning on flags

Returns:

  • (nil)

#settings ⇒ Gtk::Settings

Gets the settings object holding the settings used for this widget.

Note that this function can only be called when the GtkWidget is attached to a toplevel, since the settings object is specific to a particular GdkDisplay. If you want to monitor the widget for changes in its settings, connect to the notify::display signal.

Returns:

#should_layout ⇒ Boolean

Returns whether widget should contribute to the measuring and allocation of its parent.

This is false for invisible children, but also for children that have their own surface.

Returns:

  • (Boolean) —

    true if child should be included in measuring and allocating

#show ⇒ nil

Flags a widget to be displayed.

Any widget that isn’t shown will not appear on the screen.

Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen.

When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped.

Returns:

  • (nil)

#size_allocate(allocation, baseline) ⇒ nil

Allocates widget with a transformation that translates the origin to the position in allocation.

This is a simple form of [methodGtk.Widget.allocate].

Parameters:

  • allocation (Gtk::Allocation) —

    position and size to be allocated to widget

  • baseline (Integer) —

    The baseline of the child, or -1

Returns:

  • (nil)

#snapshot_child(child, snapshot) ⇒ nil

Snapshot the a child of widget.

When a widget receives a call to the snapshot function, it must send synthetic [vfuncGtk.Widget.snapshot] calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its [vfuncGtk.Widget.snapshot] function, calls gtk_widget_snapshot_child() once for each child, passing in the snapshot the widget received.

gtk_widget_snapshot_child() takes care of translating the origin of snapshot, and deciding whether the child needs to be snapshot.

This function does nothing for children that implement GtkNative.

Parameters:

  • child (Gtk::Widget) —

    a child of widget

  • snapshot (Gtk::Snapshot) —

    GtkSnapshot as passed to the widget. In particular, no calls to gtk_snapshot_translate() or other transform calls should have been made.

Returns:

  • (nil)

#state_flags ⇒ Gtk::StateFlags

Returns the widget state as a flag set.

It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if widget itself is sensitive.

Also note that if you are looking for a way to obtain the [flagsGtk.StateFlags] to pass to a [classGtk.StyleContext] method, you should look at [methodGtk.StyleContext.get_state].

Returns:

#style_context ⇒ Gtk::StyleContext

Returns the style context associated to widget.

The returned object is guaranteed to be the same for the lifetime of widget.

Returns:

#template=(template_bytes) ⇒ nil

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

For convenience, [methodGtk.WidgetClass.set_template_from_resource] is also provided.

Note that any class that installs templates must call [methodGtk.Widget.init_template] in the widget’s instance initializer.

Parameters:

  • template_bytes (GLib::Bytes) —

    A GBytes holding the GtkBuilder XML

Returns:

  • (nil)

#template_from_resource=(resource_name) ⇒ nil

A convenience function that calls [methodGtk.WidgetClass.set_template] with the contents of a GResource.

Note that any class that installs templates must call [methodGtk.Widget.init_template] in the widget’s instance initializer.

Parameters:

  • resource_name (String) —

    The name of the resource to load the template from

Returns:

  • (nil)

#template_scope=(scope) ⇒ nil

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

Note that this must be called from a composite widget classes class initializer after calling [methodGtk.WidgetClass.set_template].

Parameters:

  • scope (Gtk::BuilderScope) —

    The GtkBuilderScope to use when loading the class template

Returns:

  • (nil)

#tooltip_markup ⇒ String

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see [methodGtk.Tooltip.set_markup].

This is a convenience property which will take care of getting the tooltip shown if the given string is not nil: [propertyGtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signalGtk.Widget::query-tooltip] in the default signal handler.

Note that if both [propertyGtk.Widget:tooltip-text] and [propertyGtk.Widget:tooltip-markup] are set, the last one wins.

Returns:

  • (String) —

    tooltip-markup

#tooltip_markup=(tooltip_markup) ⇒ String

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see [methodGtk.Tooltip.set_markup].

This is a convenience property which will take care of getting the tooltip shown if the given string is not nil: [propertyGtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signalGtk.Widget::query-tooltip] in the default signal handler.

Note that if both [propertyGtk.Widget:tooltip-text] and [propertyGtk.Widget:tooltip-markup] are set, the last one wins.

Parameters:

  • tooltip_markup (String)

Returns:

  • (String) —

    tooltip-markup

  • (String) —

    tooltip-markup

#tooltip_text ⇒ String

Sets the text of tooltip to be the given string.

Also see [methodGtk.Tooltip.set_text].

This is a convenience property which will take care of getting the tooltip shown if the given string is not nil: [propertyGtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signalGtk.Widget::query-tooltip] in the default signal handler.

Note that if both [propertyGtk.Widget:tooltip-text] and [propertyGtk.Widget:tooltip-markup] are set, the last one wins.

Returns:

  • (String) —

    tooltip-text

#tooltip_text=(tooltip_text) ⇒ String

Sets the text of tooltip to be the given string.

Also see [methodGtk.Tooltip.set_text].

This is a convenience property which will take care of getting the tooltip shown if the given string is not nil: [propertyGtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signalGtk.Widget::query-tooltip] in the default signal handler.

Note that if both [propertyGtk.Widget:tooltip-text] and [propertyGtk.Widget:tooltip-markup] are set, the last one wins.

Parameters:

  • tooltip_text (String)

Returns:

  • (String) —

    tooltip-text

  • (String) —

    tooltip-text

#translate_coordinates(dest_widget, src_x, src_y, dest_x, dest_y) ⇒ Boolean

Translate coordinates relative to src_widget’s allocation to coordinates relative to dest_widget’s allocations.

In order to perform this operation, both widget must share a common ancestor.

Parameters:

  • dest_widget (Gtk::Widget) —

    a GtkWidget

  • src_x (Float) —

    X position relative to src_widget

  • src_y (Float) —

    Y position relative to src_widget

  • dest_x (Float) —

    location to store X position relative to dest_widget

  • dest_y (Float) —

    location to store Y position relative to dest_widget

Returns:

  • (Boolean) —

    false if src_widget and dest_widget have no common ancestor. In this case, 0 is stored in *dest_x and *dest_y. Otherwise true.

#trigger_tooltip_query ⇒ nil

Triggers a tooltip query on the display where the toplevel of widget is located.

Returns:

  • (nil)

#unmap ⇒ nil

Causes a widget to be unmapped if it’s currently mapped.

This function is only for use in widget implementations.

Returns:

  • (nil)

#unparent ⇒ nil

Dissociate widget from its parent.

This function is only for use in widget implementations, typically in dispose.

Returns:

  • (nil)

#unrealize ⇒ nil

Causes a widget to be unrealized (frees all GDK resources associated with the widget).

This function is only useful in widget implementations.

Returns:

  • (nil)

#unset_state_flags(flags) ⇒ nil

Turns off flag values for the current widget state.

See [methodGtk.Widget.set_state_flags].

This function is for use in widget implementations.

Parameters:

Returns:

  • (nil)

#valign ⇒ Gtk::Align

How to distribute vertical space if widget gets extra space.

Returns:

#valign=(valign) ⇒ Gtk::Align

How to distribute vertical space if widget gets extra space.

Parameters:

Returns:

#vexpand ⇒ Boolean

Gets whether the widget would like any available extra vertical space.

See [methodGtk.Widget.get_hexpand] for more detail.

Returns:

  • (Boolean) —

    whether vexpand flag is set

#vexpand=(vexpand) ⇒ Boolean

Whether to expand vertically.

Parameters:

  • vexpand (Boolean)

Returns:

  • (Boolean) —

    vexpand

  • (Boolean) —

    vexpand

#vexpand? ⇒ Boolean

Whether to expand vertically.

Returns:

  • (Boolean) —

    vexpand

#vexpand_set ⇒ Boolean

Gets whether gtk_widget_set_vexpand() has been used to explicitly set the expand flag on this widget.

See [methodGtk.Widget.get_hexpand_set] for more detail.

Returns:

  • (Boolean) —

    whether vexpand has been explicitly set

#vexpand_set=(vexpand_set) ⇒ Boolean

Whether to use the vexpand property.

Parameters:

  • vexpand_set (Boolean)

Returns:

  • (Boolean) —

    vexpand-set

  • (Boolean) —

    vexpand-set

#vexpand_set? ⇒ Boolean

Whether to use the vexpand property.

Returns:

  • (Boolean) —

    vexpand-set

#visible ⇒ Boolean

Determines whether the widget is visible.

If you want to take into account whether the widget’s parent is also marked as visible, use [methodGtk.Widget.is_visible] instead.

This function does not check if the widget is obscured in any way.

See [methodGtk.Widget.set_visible].

Returns:

  • (Boolean) —

    true if the widget is visible

#visible=(visible) ⇒ Boolean

Whether the widget is visible.

Parameters:

  • visible (Boolean)

Returns:

  • (Boolean) —

    visible

  • (Boolean) —

    visible

#visible? ⇒ Boolean

Whether the widget is visible.

Returns:

  • (Boolean) —

    visible

#width ⇒ Integer

Returns the content width of the widget.

This function returns the width passed to its size-allocate implementation, which is the width you should be using in [vfuncGtk.Widget.snapshot].

For pointer events, see [methodGtk.Widget.contains].

To learn more about widget sizes, see the coordinate system overview.

Returns:

  • (Integer) —

    The width of widget

#width_request ⇒ Integer

Override for width request of the widget.

If this is -1, the natural request will be used.

Returns:

  • (Integer) —

    width-request

#width_request=(width_request) ⇒ Integer

Override for width request of the widget.

If this is -1, the natural request will be used.

Parameters:

  • width_request (Integer)

Returns:

  • (Integer) —

    width-request

  • (Integer) —

    width-request