Trait gtk4::prelude::WidgetExt

pub trait WidgetExt: IsA<Widget> + Sealed + 'static {
    // Provided methods
    fn action_set_enabled(&self, action_name: &str, enabled: bool) { ... }
    fn activate(&self) -> bool { ... }
    fn activate_action(
        &self,
        name: &str,
        args: Option<&Variant>
    ) -> Result<(), BoolError> { ... }
    fn activate_default(&self) { ... }
    fn add_controller(&self, controller: impl IsA<EventController>) { ... }
    fn add_css_class(&self, css_class: &str) { ... }
    fn add_mnemonic_label(&self, label: &impl IsA<Widget>) { ... }
    fn allocate(
        &self,
        width: i32,
        height: i32,
        baseline: i32,
        transform: Option<Transform>
    ) { ... }
    fn child_focus(&self, direction: DirectionType) -> bool { ... }
    fn compute_bounds(&self, target: &impl IsA<Widget>) -> Option<Rect> { ... }
    fn compute_expand(&self, orientation: Orientation) -> bool { ... }
    fn compute_point(
        &self,
        target: &impl IsA<Widget>,
        point: &Point
    ) -> Option<Point> { ... }
    fn compute_transform(&self, target: &impl IsA<Widget>) -> Option<Matrix> { ... }
    fn contains(&self, x: f64, y: f64) -> bool { ... }
    fn create_pango_context(&self) -> Context { ... }
    fn create_pango_layout(&self, text: Option<&str>) -> Layout { ... }
    fn drag_check_threshold(
        &self,
        start_x: i32,
        start_y: i32,
        current_x: i32,
        current_y: i32
    ) -> bool { ... }
    fn error_bell(&self) { ... }
    fn allocated_baseline(&self) -> i32 { ... }
    fn allocated_height(&self) -> i32 { ... }
    fn allocated_width(&self) -> i32 { ... }
    fn allocation(&self) -> Allocation { ... }
    fn ancestor(&self, widget_type: Type) -> Option<Widget> { ... }
    fn baseline(&self) -> i32 { ... }
    fn can_focus(&self) -> bool { ... }
    fn can_target(&self) -> bool { ... }
    fn is_child_visible(&self) -> bool { ... }
    fn clipboard(&self) -> Clipboard { ... }
    fn color(&self) -> RGBA { ... }
    fn css_classes(&self) -> Vec<GString> { ... }
    fn css_name(&self) -> GString { ... }
    fn cursor(&self) -> Option<Cursor> { ... }
    fn direction(&self) -> TextDirection { ... }
    fn display(&self) -> Display { ... }
    fn first_child(&self) -> Option<Widget> { ... }
    fn focus_child(&self) -> Option<Widget> { ... }
    fn gets_focus_on_click(&self) -> bool { ... }
    fn is_focusable(&self) -> bool { ... }
    fn font_map(&self) -> Option<FontMap> { ... }
    fn font_options(&self) -> Option<FontOptions> { ... }
    fn frame_clock(&self) -> Option<FrameClock> { ... }
    fn halign(&self) -> Align { ... }
    fn has_tooltip(&self) -> bool { ... }
    fn height(&self) -> i32 { ... }
    fn hexpands(&self) -> bool { ... }
    fn is_hexpand_set(&self) -> bool { ... }
    fn last_child(&self) -> Option<Widget> { ... }
    fn layout_manager(&self) -> Option<LayoutManager> { ... }
    fn is_mapped(&self) -> bool { ... }
    fn margin_bottom(&self) -> i32 { ... }
    fn margin_end(&self) -> i32 { ... }
    fn margin_start(&self) -> i32 { ... }
    fn margin_top(&self) -> i32 { ... }
    fn widget_name(&self) -> GString { ... }
    fn native(&self) -> Option<Native> { ... }
    fn next_sibling(&self) -> Option<Widget> { ... }
    fn opacity(&self) -> f64 { ... }
    fn overflow(&self) -> Overflow { ... }
    fn pango_context(&self) -> Context { ... }
    fn parent(&self) -> Option<Widget> { ... }
    fn preferred_size(&self) -> (Requisition, Requisition) { ... }
    fn prev_sibling(&self) -> Option<Widget> { ... }
    fn primary_clipboard(&self) -> Clipboard { ... }
    fn is_realized(&self) -> bool { ... }
    fn receives_default(&self) -> bool { ... }
    fn request_mode(&self) -> SizeRequestMode { ... }
    fn root(&self) -> Option<Root> { ... }
    fn scale_factor(&self) -> i32 { ... }
    fn get_sensitive(&self) -> bool { ... }
    fn settings(&self) -> Settings { ... }
    fn size(&self, orientation: Orientation) -> i32 { ... }
    fn size_request(&self) -> (i32, i32) { ... }
    fn state_flags(&self) -> StateFlags { ... }
    fn style_context(&self) -> StyleContext { ... }
    fn tooltip_markup(&self) -> Option<GString> { ... }
    fn tooltip_text(&self) -> Option<GString> { ... }
    fn valign(&self) -> Align { ... }
    fn vexpands(&self) -> bool { ... }
    fn is_vexpand_set(&self) -> bool { ... }
    fn get_visible(&self) -> bool { ... }
    fn width(&self) -> i32 { ... }
    fn grab_focus(&self) -> bool { ... }
    fn has_css_class(&self, css_class: &str) -> bool { ... }
    fn has_default(&self) -> bool { ... }
    fn has_focus(&self) -> bool { ... }
    fn has_visible_focus(&self) -> bool { ... }
    fn hide(&self) { ... }
    fn in_destruction(&self) -> bool { ... }
    fn insert_action_group(
        &self,
        name: &str,
        group: Option<&impl IsA<ActionGroup>>
    ) { ... }
    fn insert_after(
        &self,
        parent: &impl IsA<Widget>,
        previous_sibling: Option<&impl IsA<Widget>>
    ) { ... }
    fn insert_before(
        &self,
        parent: &impl IsA<Widget>,
        next_sibling: Option<&impl IsA<Widget>>
    ) { ... }
    fn is_ancestor(&self, ancestor: &impl IsA<Widget>) -> bool { ... }
    fn is_drawable(&self) -> bool { ... }
    fn is_focus(&self) -> bool { ... }
    fn is_sensitive(&self) -> bool { ... }
    fn is_visible(&self) -> bool { ... }
    fn keynav_failed(&self, direction: DirectionType) -> bool { ... }
    fn list_mnemonic_labels(&self) -> Vec<Widget> { ... }
    fn map(&self) { ... }
    fn measure(
        &self,
        orientation: Orientation,
        for_size: i32
    ) -> (i32, i32, i32, i32) { ... }
    fn mnemonic_activate(&self, group_cycling: bool) -> bool { ... }
    fn observe_children(&self) -> ListModel { ... }
    fn observe_controllers(&self) -> ListModel { ... }
    fn pick(&self, x: f64, y: f64, flags: PickFlags) -> Option<Widget> { ... }
    fn queue_allocate(&self) { ... }
    fn queue_draw(&self) { ... }
    fn queue_resize(&self) { ... }
    fn realize(&self) { ... }
    fn remove_controller(&self, controller: &impl IsA<EventController>) { ... }
    fn remove_css_class(&self, css_class: &str) { ... }
    fn remove_mnemonic_label(&self, label: &impl IsA<Widget>) { ... }
    fn set_can_focus(&self, can_focus: bool) { ... }
    fn set_can_target(&self, can_target: bool) { ... }
    fn set_child_visible(&self, child_visible: bool) { ... }
    fn set_css_classes(&self, classes: &[&str]) { ... }
    fn set_cursor(&self, cursor: Option<&Cursor>) { ... }
    fn set_cursor_from_name(&self, name: Option<&str>) { ... }
    fn set_direction(&self, dir: TextDirection) { ... }
    fn set_focus_child(&self, child: Option<&impl IsA<Widget>>) { ... }
    fn set_focus_on_click(&self, focus_on_click: bool) { ... }
    fn set_focusable(&self, focusable: bool) { ... }
    fn set_font_map(&self, font_map: Option<&impl IsA<FontMap>>) { ... }
    fn set_font_options(&self, options: Option<&FontOptions>) { ... }
    fn set_halign(&self, align: Align) { ... }
    fn set_has_tooltip(&self, has_tooltip: bool) { ... }
    fn set_hexpand(&self, expand: bool) { ... }
    fn set_hexpand_set(&self, set: bool) { ... }
    fn set_layout_manager(
        &self,
        layout_manager: Option<impl IsA<LayoutManager>>
    ) { ... }
    fn set_margin_bottom(&self, margin: i32) { ... }
    fn set_margin_end(&self, margin: i32) { ... }
    fn set_margin_start(&self, margin: i32) { ... }
    fn set_margin_top(&self, margin: i32) { ... }
    fn set_widget_name(&self, name: &str) { ... }
    fn set_opacity(&self, opacity: f64) { ... }
    fn set_overflow(&self, overflow: Overflow) { ... }
    fn set_parent(&self, parent: &impl IsA<Widget>) { ... }
    fn set_receives_default(&self, receives_default: bool) { ... }
    fn set_sensitive(&self, sensitive: bool) { ... }
    fn set_size_request(&self, width: i32, height: i32) { ... }
    fn set_state_flags(&self, flags: StateFlags, clear: bool) { ... }
    fn set_tooltip_markup(&self, markup: Option<&str>) { ... }
    fn set_tooltip_text(&self, text: Option<&str>) { ... }
    fn set_valign(&self, align: Align) { ... }
    fn set_vexpand(&self, expand: bool) { ... }
    fn set_vexpand_set(&self, set: bool) { ... }
    fn set_visible(&self, visible: bool) { ... }
    fn should_layout(&self) -> bool { ... }
    fn show(&self) { ... }
    fn size_allocate(&self, allocation: &Allocation, baseline: i32) { ... }
    fn snapshot_child(
        &self,
        child: &impl IsA<Widget>,
        snapshot: &impl IsA<Snapshot>
    ) { ... }
    fn translate_coordinates(
        &self,
        dest_widget: &impl IsA<Widget>,
        src_x: f64,
        src_y: f64
    ) -> Option<(f64, f64)> { ... }
    fn trigger_tooltip_query(&self) { ... }
    fn unmap(&self) { ... }
    fn unparent(&self) { ... }
    fn unrealize(&self) { ... }
    fn unset_state_flags(&self, flags: StateFlags) { ... }
    fn height_request(&self) -> i32 { ... }
    fn set_height_request(&self, height_request: i32) { ... }
    fn width_request(&self) -> i32 { ... }
    fn set_width_request(&self, width_request: i32) { ... }
    fn connect_destroy<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_direction_changed<F: Fn(&Self, TextDirection) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_hide<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_keynav_failed<F: Fn(&Self, DirectionType) -> Propagation + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_map<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_mnemonic_activate<F: Fn(&Self, bool) -> Propagation + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_move_focus<F: Fn(&Self, DirectionType) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn emit_move_focus(&self, direction: DirectionType) { ... }
    fn connect_query_tooltip<F: Fn(&Self, i32, i32, bool, &Tooltip) -> bool + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_realize<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_show<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_state_flags_changed<F: Fn(&Self, StateFlags) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_unmap<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_unrealize<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { ... }
    fn connect_can_focus_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_can_target_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_css_classes_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_cursor_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_focus_on_click_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_focusable_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_halign_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_has_default_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_has_focus_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_has_tooltip_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_height_request_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_hexpand_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_hexpand_set_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_layout_manager_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_margin_bottom_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_margin_end_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_margin_start_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_margin_top_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_name_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_opacity_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_overflow_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_parent_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_receives_default_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_root_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_scale_factor_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_sensitive_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_tooltip_markup_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_tooltip_text_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_valign_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_vexpand_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_vexpand_set_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_visible_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
    fn connect_width_request_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F
    ) -> SignalHandlerId { ... }
}

Trait containing all Widget methods.

Implementors

ActionBar, Actionable, AppChooserButton, AppChooserWidget, AppChooser, AspectFrame, Box, Button, Calendar, CellEditable, CellView, CenterBox, CheckButton, ColorButton, ColorChooserWidget, ColorDialogButton, ColumnView, ComboBox, DragIcon, DrawingArea, DropDown, EditableLabel, Editable, Entry, Expander, FileChooserWidget, Fixed, FlowBoxChild, FlowBox, FontButton, FontChooserWidget, FontDialogButton, Frame, GLArea, GraphicsOffload, Grid, HeaderBar, IconView, Image, InfoBar, Inscription, Label, LevelBar, ListBase, ListBoxRow, ListBox, MediaControls, MenuButton, Native, Notebook, Overlay, Paned, PasswordEntry, Picture, PopoverMenuBar, Popover, ProgressBar, Range, Revealer, Root, ScaleButton, Scrollbar, ScrolledWindow, SearchBar, SearchEntry, Separator, ShortcutLabel, ShortcutsShortcut, SpinButton, Spinner, StackSidebar, StackSwitcher, Stack, Statusbar, Switch, TextView, Text, TreeExpander, TreeView, Video, Viewport, Widget, WindowControls, WindowHandle, Window

Provided Methods

fn action_set_enabled(&self, action_name: &str, enabled: bool)

Enable or disable an action installed with gtk_widget_class_install_action().

action_name

action name, such as “clipboard.paste”

enabled

whether the action is now enabled

fn activate(&self) -> bool

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

The activation will emit the signal set using WidgetClassExt::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 WidgetClassExt::add_shortcut() with an action created with SignalAction::new().

If @self isn’t activatable, the function returns false.

Returns

true if the widget was activatable

fn activate_action( &self, name: &str, args: Option<&Variant> ) -> Result<(), BoolError>

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

If the action is in an action group added with 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().

name

the name of the action to activate

args

parameters to use

Returns

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

fn activate_default(&self)

Activates the default.activate action from @self.

fn add_controller(&self, controller: impl IsA<EventController>)

Adds @controller to @self so that it will receive events.

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

controller

a EventController that hasn’t been added to a widget yet

fn add_css_class(&self, css_class: &str)

Adds a style class to @self.

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

Use remove_css_class() to remove the style again.

css_class

The style class to add to @self, without the leading ‘.’ used for notation of style classes

fn add_mnemonic_label(&self, label: &impl IsA<Widget>)

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

See 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.

label

a Widget that acts as a mnemonic label for @self

fn allocate( &self, width: i32, height: i32, baseline: i32, transform: Option<Transform> )

This function is only used by Widget 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 size_allocate().

width

New width of @self

height

New height of @self

baseline

New baseline of @self, or -1

transform

Transformation to be applied to @self

fn child_focus(&self, direction: DirectionType) -> bool

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 WidgetImpl::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 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 grab_focus() to move the focus to a particular widget.

direction

direction of focus movement

Returns

true if focus ended up inside @self

fn compute_bounds(&self, target: &impl IsA<Widget>) -> Option<Rect>

Computes the bounds for @self 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 @self 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 @self and @target to be the same widget.

target

the Widget

Returns

true if the bounds could be computed

out_bounds

the rectangle taking the bounds

fn compute_expand(&self, orientation: Orientation) -> bool

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

Containers should check this, rather than looking at hexpands() or vexpands().

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.

orientation

expand direction

Returns

whether widget tree rooted here should be expanded

fn compute_point( &self, target: &impl IsA<Widget>, point: &Point ) -> Option<Point>

Translates the given @point in @self’s coordinates to coordinates relative to @target’s coordinate system.

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

target

the Widget to transform into

point

a point in @self’s coordinate system

Returns

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

out_point

Set to the corresponding coordinates in @target’s coordinate system

fn compute_transform(&self, target: &impl IsA<Widget>) -> Option<Matrix>

Computes a matrix suitable to describe a transformation from @self’s coordinate system into @target’s coordinate system.

The transform can not be computed in certain cases, for example when @self 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.

target

the target widget that the matrix will transform to

Returns

true if the transform could be computed, false otherwise

out_transform

location to store the final transformation

fn contains(&self, x: f64, y: f64) -> bool

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

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

x

X coordinate to test, relative to @self’s origin

y

Y coordinate to test, relative to @self’s origin

Returns

true if @self contains (@x, @y).

fn create_pango_context(&self) -> Context

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

See also pango_context().

Returns

the new pango::Context

fn create_pango_layout(&self, text: Option<&str>) -> Layout

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

If you keep a pango::Layout created in this way around, you need to re-create it when the widget pango::Context is replaced. This can be tracked by listening to changes of the root property on the widget.

text

text to set on the layout

Returns

the new pango::Layout

fn drag_check_threshold( &self, start_x: i32, start_y: i32, current_x: i32, current_y: i32 ) -> bool

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

start_x

X coordinate of start of drag

start_y

Y coordinate of start of drag

current_x

current X coordinate

current_y

current Y coordinate

Returns

true if the drag threshold has been passed.

fn error_bell(&self)

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

If the gtk-error-bell setting is true, it calls Gdk::Surface::beep(), otherwise it does nothing.

Note that the effect of Gdk::Surface::beep() can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

fn allocated_baseline(&self) -> i32

👎Deprecated: Since 4.12

Returns the baseline that has currently been allocated to @self.

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

Deprecated since 4.12

Use baseline() instead

Returns

the baseline of the @self, or -1 if none

fn allocated_height(&self) -> i32

👎Deprecated: Since 4.12

Returns the height that has currently been allocated to @self.

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

Deprecated since 4.12

Use height() instead

Returns

the height of the @self

fn allocated_width(&self) -> i32

👎Deprecated: Since 4.12

Returns the width that has currently been allocated to @self.

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

Deprecated since 4.12

Use width() instead

Returns

the width of the @self

fn allocation(&self) -> Allocation

👎Deprecated: Since 4.12

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 size_allocate() with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. allocation() returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the 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.

Deprecated since 4.12

Use compute_bounds(), width() or height() instead.

Returns

allocation

a pointer to a GtkAllocation to copy to

fn ancestor(&self, widget_type: Type) -> Option<Widget>

Gets the first ancestor of @self with type @widget_type.

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

Note that unlike is_ancestor(), this function considers @self to be an ancestor of itself.

widget_type

ancestor type

Returns

the ancestor widget

fn baseline(&self) -> i32

Available on crate feature v4_12 only.

Returns the baseline that has currently been allocated to @self.

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

Returns

the baseline of the @self, or -1 if none

fn can_focus(&self) -> bool

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

See set_focusable().

Returns

true if the input focus can enter @self, false otherwise

fn can_target(&self) -> bool

Queries whether @self can be the target of pointer events.

Returns

true if @self can receive pointer events

fn is_child_visible(&self) -> bool

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

true if the widget is mapped with the parent.

fn clipboard(&self) -> Clipboard

Gets the clipboard object for @self.

This is a utility function to get the clipboard object for the gdk::Display that @self is using.

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

Returns

the appropriate clipboard object

fn color(&self) -> RGBA

Available on crate feature v4_10 only.

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.

Returns

color

return location for the color

fn css_classes(&self) -> Vec<GString>

Returns the list of style classes applied to @self.

Returns

a None-terminated list of css classes currently applied to @self. The returned list must freed using g_strfreev().

fn css_name(&self) -> GString

Returns the CSS name that is used for @self.

Returns

the CSS name

fn cursor(&self) -> Option<Cursor>

Queries the cursor set on @self.

See set_cursor() for details.

Returns

the cursor currently in use or None if the cursor is inherited

fn direction(&self) -> TextDirection

Gets the reading direction for a particular widget.

See set_direction().

Returns

the reading direction for the widget.

fn display(&self) -> Display

Get the gdk::Display 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 Window 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

the gdk::Display for the toplevel for this widget.

fn first_child(&self) -> Option<Widget>

Returns the widget’s first child.

This API is primarily meant for widget implementations.

Returns

The widget’s first child

fn focus_child(&self) -> Option<Widget>

Returns the current focus child of @self.

Returns

The current focus child of @self

fn gets_focus_on_click(&self) -> bool

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

See set_focus_on_click().

Returns

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

fn is_focusable(&self) -> bool

Determines whether @self can own the input focus.

See set_focusable().

Returns

true if @self can own the input focus, false otherwise

fn font_map(&self) -> Option<FontMap>

Gets the font map of @self.

See set_font_map().

Returns

A pango::FontMap

fn font_options(&self) -> Option<FontOptions>

👎Deprecated: Since 4.16

Returns the cairo::FontOptions of widget.

Seee set_font_options().

Deprecated since 4.16

Returns

the cairo::FontOptions of widget

fn frame_clock(&self) -> Option<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 FrameClock::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 FrameClock::frame_time(), and then update the animation by calling FrameClock::frame_time() again during each repaint.

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

a gdk::FrameClock

fn halign(&self) -> Align

Gets the horizontal alignment of @self.

For backwards compatibility reasons this method will never return one of the baseline alignments, but instead it will convert it to GTK_ALIGN_FILL or GTK_ALIGN_CENTER.

Baselines are not supported for horizontal alignment.

Returns

the horizontal alignment of @self

fn has_tooltip(&self) -> bool

Returns the current value of the has-tooltip property.

Returns

current value of has-tooltip on @self.

fn height(&self) -> i32

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 WidgetImpl::snapshot().

For pointer events, see contains().

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

Returns

The height of @self

fn hexpands(&self) -> bool

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

When a user resizes a Window, 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 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

whether hexpand flag is set

fn is_hexpand_set(&self) -> bool

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

If 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

whether hexpand has been explicitly set

fn last_child(&self) -> Option<Widget>

Returns the widget’s last child.

This API is primarily meant for widget implementations.

Returns

The widget’s last child

fn layout_manager(&self) -> Option<LayoutManager>

Retrieves the layout manager used by @self.

See set_layout_manager().

Returns

a LayoutManager

fn is_mapped(&self) -> bool

Whether the widget is mapped.

Returns

true if the widget is mapped, false otherwise.

fn margin_bottom(&self) -> i32

Gets the bottom margin of @self.

Returns

The bottom margin of @self

fn margin_end(&self) -> i32

Gets the end margin of @self.

Returns

The end margin of @self

fn margin_start(&self) -> i32

Gets the start margin of @self.

Returns

The start margin of @self

fn margin_top(&self) -> i32

Gets the top margin of @self.

Returns

The top margin of @self

fn widget_name(&self) -> GString

Retrieves the name of a widget.

See set_widget_name() for the significance of widget names.

Returns

name of the widget. This string is owned by GTK and should not be modified or freed

fn native(&self) -> Option<Native>

Returns the nearest Native ancestor of @self.

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

Native widgets will return themselves here.

Returns

the Native ancestor of @self

fn next_sibling(&self) -> Option<Widget>

Returns the widget’s next sibling.

This API is primarily meant for widget implementations.

Returns

The widget’s next sibling

fn opacity(&self) -> f64

#Fetches the requested opacity for this widget.

See set_opacity().

Returns

the requested opacity for this widget.

fn overflow(&self) -> Overflow

Returns the widget’s overflow value.

Returns

The widget’s overflow.

fn pango_context(&self) -> Context

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

Unlike the context returned by 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 root property on the widget.

Returns

the pango::Context for the widget.

fn parent(&self) -> Option<Widget>

Returns the parent widget of @self.

Returns

the parent widget of @self

fn preferred_size(&self) -> (Requisition, Requisition)

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 Fixed.

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 measure() if you want to support baseline alignment.

Returns

minimum_size

location for storing the minimum size

natural_size

location for storing the natural size

fn prev_sibling(&self) -> Option<Widget>

Returns the widget’s previous sibling.

This API is primarily meant for widget implementations.

Returns

The widget’s previous sibling

fn primary_clipboard(&self) -> Clipboard

Gets the primary clipboard of @self.

This is a utility function to get the primary clipboard object for the gdk::Display that @self is using.

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

Returns

the appropriate clipboard object

fn is_realized(&self) -> bool

Determines whether @self is realized.

Returns

true if @self is realized, false otherwise

fn receives_default(&self) -> bool

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

See set_receives_default().

Returns

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

fn request_mode(&self) -> 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

The SizeRequestMode preferred by @self.

fn root(&self) -> Option<Root>

Returns the Root widget of @self.

This function will return None if the widget is not contained inside a widget tree with a root widget.

Root widgets will return themselves here.

Returns

the root widget of @self

fn scale_factor(&self) -> i32

Retrieves the internal scale factor that maps from window coordinates to the actual device pixels.

On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2).

See Gdk::Surface::get_scale_factor().

Returns

the scale factor for @self

fn get_sensitive(&self) -> bool

Returns the widget’s sensitivity.

This function returns the value that has been set using set_sensitive()).

The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See is_sensitive().

Returns

true if the widget is sensitive

fn settings(&self) -> Settings

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

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

Returns

the relevant Settings object

fn size(&self, orientation: Orientation) -> i32

Returns the content width or height of the widget.

Which dimension is returned depends on @orientation.

This is equivalent to calling width() for Orientation::Horizontal or height() for Orientation::Vertical, but can be used when writing orientation-independent code, such as when implementing Orientable widgets.

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

orientation

the orientation to query

Returns

The size of @self in @orientation.

fn size_request(&self) -> (i32, i32)

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 set_size_request(). To get the size a widget will actually request, call measure() instead of this function.

Returns

width

return location for width

height

return location for height

fn state_flags(&self) -> StateFlags

Returns the widget state as a flag set.

It is worth mentioning that the effective StateFlags::INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if @self itself is sensitive.

Also note that if you are looking for a way to obtain the StateFlags to pass to a StyleContext method, you should look at StyleContextExt::state().

Returns

The state flags for widget

fn style_context(&self) -> StyleContext

👎Deprecated: Since 4.10

Returns the style context associated to @self.

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

Deprecated since 4.10

Style contexts will be removed in GTK 5

Returns

the widget’s StyleContext

fn tooltip_markup(&self) -> Option<GString>

Gets the contents of the tooltip for @self.

If the tooltip has not been set using set_tooltip_markup(), this function returns None.

Returns

the tooltip text

fn tooltip_text(&self) -> Option<GString>

Gets the contents of the tooltip for @self.

If the @self’s tooltip was set using set_tooltip_markup(), this function will return the escaped text.

Returns

the tooltip text

fn valign(&self) -> Align

Gets the vertical alignment of @self.

Returns

the vertical alignment of @self

fn vexpands(&self) -> bool

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

See hexpands() for more detail.

Returns

whether vexpand flag is set

fn is_vexpand_set(&self) -> bool

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

See is_hexpand_set() for more detail.

Returns

whether vexpand has been explicitly set

fn get_visible(&self) -> bool

Determines whether the widget is visible.

If you want to take into account whether the widget’s parent is also marked as visible, use is_visible() instead.

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

See set_visible().

Returns

true if the widget is visible

fn width(&self) -> i32

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 WidgetImpl::snapshot().

For pointer events, see contains().

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

Returns

The width of @self

fn grab_focus(&self) -> bool

Causes @self to have the keyboard focus for the Window it’s inside.

If @self is not focusable, or its WidgetImpl::grab_focus() implementation cannot transfer the focus to a descendant of @self that is focusable, it will not take focus and false will be returned.

Calling grab_focus() on an already focused widget is allowed, should not have an effect, and return true.

Returns

true if focus is now inside @self.

fn has_css_class(&self, css_class: &str) -> bool

Returns whether @css_class is currently applied to @self.

css_class

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

Returns

true if @css_class is currently applied to @self, false otherwise.

fn has_default(&self) -> bool

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

Returns

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

fn has_focus(&self) -> bool

Determines if the widget has the global input focus.

See is_focus() for the difference between having the global input focus, and only having the focus within a toplevel.

Returns

true if the widget has the global input focus.

fn has_visible_focus(&self) -> bool

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 @self. See GtkWindowExt::gets_focus_visible() for more information about focus indication.

To find out if the widget has the global input focus, use has_focus().

Returns

true if the widget should display a “focus rectangle”

fn hide(&self)

👎Deprecated: Since 4.10

Reverses the effects of gtk_widget_show().

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

Deprecated since 4.10

Use set_visible() instead

fn in_destruction(&self) -> bool

Returns whether the widget is currently being destroyed.

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

Returns

true if @self is being destroyed

fn insert_action_group(&self, name: &str, group: Option<&impl IsA<ActionGroup>>)

Inserts @group into @self.

Children of @self that implement 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 None, a previously inserted group for @name is removed from @self.

name

the prefix for actions in @group

group

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

fn insert_after( &self, parent: &impl IsA<Widget>, previous_sibling: Option<&impl IsA<Widget>> )

Inserts @self into the child widget list of @parent.

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

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

If @parent is already set as the parent widget of @self, this function can also be used to reorder @self 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.

parent

the parent Widget to insert @self into

previous_sibling

the new previous sibling of @self

fn insert_before( &self, parent: &impl IsA<Widget>, next_sibling: Option<&impl IsA<Widget>> )

Inserts @self into the child widget list of @parent.

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

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

If @parent is already set as the parent widget of @self, this function can also be used to reorder @self 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.

parent

the parent Widget to insert @self into

next_sibling

the new next sibling of @self

fn is_ancestor(&self, ancestor: &impl IsA<Widget>) -> bool

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

ancestor

another Widget

Returns

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

fn is_drawable(&self) -> bool

Determines whether @self can be drawn to.

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

Returns

true if @self is drawable, false otherwise

fn is_focus(&self) -> bool

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

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

Returns

true if the widget is the focus widget.

fn is_sensitive(&self) -> bool

Returns the widget’s effective sensitivity.

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

Returns

true if the widget is effectively sensitive

fn is_visible(&self) -> bool

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 get_visible() and set_visible().

Returns

true if the widget and all its parents are visible

fn keynav_failed(&self, direction: DirectionType) -> bool

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 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 child_focus() on the widget’s toplevel.

The default keynav-failed handler returns false for DirectionType::TabForward and DirectionType::TabBackward. For the other values of DirectionType it returns true.

Whenever the default handler returns true, it also calls 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 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.

direction

direction of focus movement

Returns

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).

fn list_mnemonic_labels(&self) -> Vec<Widget>

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

Typically, these widgets will be labels. See, for example, 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

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

fn map(&self)

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

This function is only for use in widget implementations.

fn measure( &self, orientation: Orientation, for_size: i32 ) -> (i32, i32, i32, i32)

Measures @self in the orientation @orientation and for the given @for_size.

As an example, if @orientation is Orientation::Horizontal and @for_size is 300, this functions will compute the minimum and natural width of @self if it is allocated at a height of 300 pixels.

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

orientation

the orientation to measure

for_size

Size for the opposite of @orientation, i.e. if @orientation is Orientation::Horizontal, this is the height the widget should be measured with. The 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.

Returns

minimum

location to store the minimum size

natural

location to store the natural size

minimum_baseline

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

natural_baseline

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

fn mnemonic_activate(&self, group_cycling: bool) -> bool

Emits the ::mnemonic-activate signal.

See mnemonic-activate.

group_cycling

true if there are other widgets with the same mnemonic

Returns

true if the signal has been handled

fn observe_children(&self) -> ListModel

Returns a GListModel to track the children of @self.

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

a GListModel tracking @self’s children

fn observe_controllers(&self) -> ListModel

Returns a GListModel to track the EventControllers of @self.

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

a GListModel tracking @self’s controllers

fn pick(&self, x: f64, y: f64, flags: PickFlags) -> Option<Widget>

Finds the descendant of @self 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 @self’s content area.

Usually widgets will return None if the given coordinate is not contained in @self checked via contains(). Otherwise they will recursively try to find a child that does not return None. 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.

x

X coordinate to test, relative to @self’s origin

y

Y coordinate to test, relative to @self’s origin

flags

Flags to influence what is picked

Returns

The widget descendant at the given point

fn queue_allocate(&self)

Flags the widget for a rerun of the WidgetImpl::size_allocate() function.

Use this function instead of queue_resize() when the @self’s size request didn’t change but it wants to reposition its contents.

An example user of this function is set_halign().

This function is only for use in widget implementations.

fn queue_draw(&self)

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

This means @self’s WidgetImpl::snapshot() implementation will be called.

fn queue_resize(&self)

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 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 WidgetImpl::size_allocate() virtual method. Calls to gtk_widget_queue_resize() from inside WidgetImpl::size_allocate() will be silently ignored.

This function is only for use in widget implementations.

fn realize(&self)

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 @self 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 realize.

fn remove_controller(&self, controller: &impl IsA<EventController>)

Removes @controller from @self, 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.

controller

a EventController

fn remove_css_class(&self, css_class: &str)

Removes a style from @self.

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

css_class

The style class to remove from @self, without the leading ‘.’ used for notation of style classes

fn remove_mnemonic_label(&self, label: &impl IsA<Widget>)

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

See list_mnemonic_labels(). The widget must have previously been added to the list with add_mnemonic_label().

label

a Widget that was previously set as a mnemonic label for @self with add_mnemonic_label()

fn set_can_focus(&self, can_focus: bool)

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

Applications should set @can_focus to false to mark a widget as for pointer/touch use only.

Note that having @can_focus be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input focus.

See grab_focus() for actually setting the input focus on a widget.

can_focus

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

fn set_can_target(&self, can_target: bool)

Sets whether @self can be the target of pointer events.

can_target

whether this widget should be able to receive pointer events

fn set_child_visible(&self, child_visible: bool)

Sets whether @self should be mapped along with its parent.

The child visibility can be set for widget before it is added to a container with 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.

child_visible

if true, @self should be mapped along with its parent.

fn set_css_classes(&self, classes: &[&str])

Clear all style classes applied to @self and replace them with @classes.

classes

None-terminated list of style classes to apply to @self.

fn set_cursor(&self, cursor: Option<&Cursor>)

Sets the cursor to be shown when pointer devices point towards @self.

If the @cursor is NULL, @self will use the cursor inherited from the parent widget.

cursor

the new cursor

fn set_cursor_from_name(&self, name: Option<&str>)

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

This is a utility function that creates a cursor via gdk::Cursor::from_name() and then sets it on @self with set_cursor(). See those functions for details.

On top of that, this function allows @name to be None, which will do the same as calling set_cursor() with a None cursor.

name

The name of the cursor

fn set_direction(&self, dir: TextDirection)

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 TextDirection::None, then the value set by Widget::set_default_direction() will be used.

dir

the new direction

fn set_focus_child(&self, child: Option<&impl IsA<Widget>>)

Set @child as the current focus child of @self.

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

child

a direct child widget of @self or None to unset the focus child of @self

fn set_focus_on_click(&self, focus_on_click: bool)

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

Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application.

focus_on_click

whether the widget should grab focus when clicked with the mouse

fn set_focusable(&self, focusable: bool)

Specifies whether @self can own the input focus.

Widget implementations should set @focusable to true in their init() function if they want to receive keyboard input.

Note that having @focusable be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input focus.

See grab_focus() for actually setting the input focus on a widget.

focusable

whether or not @self can own the input focus

fn set_font_map(&self, font_map: Option<&impl IsA<FontMap>>)

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.

font_map

a pango::FontMap, or None to unset any previously set font map

fn set_font_options(&self, options: Option<&FontOptions>)

👎Deprecated: Since 4.16

Sets the cairo::FontOptions used for Pango rendering in this widget.

When not set, the default font options for the gdk::Display will be used.

Deprecated since 4.16

options

a cairo::FontOptions to unset any previously set default font options

fn set_halign(&self, align: Align)

Sets the horizontal alignment of @self.

align

the horizontal alignment

fn set_has_tooltip(&self, has_tooltip: bool)

Sets the has-tooltip property on @self to @has_tooltip.

has_tooltip

whether or not @self has a tooltip.

fn set_hexpand(&self, expand: bool)

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

When a user resizes a Window, 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.

Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room.

By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call compute_expand(). A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on Widget.).

Setting hexpand explicitly with this function will override the automatic expand behavior.

This function forces the widget to expand or not to expand, regardless of children. The override occurs because set_hexpand() sets the hexpand-set property (see set_hexpand_set()) which causes the widget’s hexpand value to be used, rather than looking at children and widget state.

expand

whether to expand

fn set_hexpand_set(&self, set: bool)

Sets whether the hexpand flag will be used.

The hexpand-set property will be set automatically when you call set_hexpand() to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag.

If hexpand 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.

set

value for hexpand-set property

fn set_layout_manager(&self, layout_manager: Option<impl IsA<LayoutManager>>)

Sets the layout manager delegate instance that provides an implementation for measuring and allocating the children of @self.

layout_manager

a LayoutManager

fn set_margin_bottom(&self, margin: i32)

Sets the bottom margin of @self.

margin

the bottom margin

fn set_margin_end(&self, margin: i32)

Sets the end margin of @self.

margin

the end margin

fn set_margin_start(&self, margin: i32)

Sets the start margin of @self.

margin

the start margin

fn set_margin_top(&self, margin: i32)

Sets the top margin of @self.

margin

the top margin

fn set_widget_name(&self, name: &str)

Sets a widgets name.

Setting a name allows you to refer to the widget from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for StyleContext.

Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *…), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice.

name

name for the widget

fn set_opacity(&self, opacity: f64)

Request the @self to be rendered partially transparent.

An opacity of 0 is fully transparent and an opacity of 1 is fully opaque.

Opacity works on both toplevel widgets and child widgets, although there are some limitations: For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this has any effect only on X displays with a compositing manager, see gdk_display_is_composited(). On Windows and Wayland it should always work, although setting a window’s opacity after the window has been shown may cause some flicker.

Note that the opacity is inherited through inclusion — if you set a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy progressively more translucent). As a consequence, Popovers and other Native widgets with their own surface will use their own opacity value, and thus by default appear non-translucent, even if they are attached to a toplevel that is translucent.

opacity

desired opacity, between 0 and 1

fn set_overflow(&self, overflow: Overflow)

Sets how @self treats content that is drawn outside the widget’s content area.

See the definition of Overflow for details.

This setting is provided for widget implementations and should not be used by application code.

The default value is Overflow::Visible.

overflow

desired overflow

fn set_parent(&self, parent: &impl IsA<Widget>)

Sets @parent as the parent widget of @self.

This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. The opposite function is unparent().

This function is useful only when implementing subclasses of Widget.

parent

parent widget

fn set_receives_default(&self, receives_default: bool)

Specifies whether @self will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default.

receives_default

whether or not @self can be a default widget.

fn set_sensitive(&self, sensitive: bool)

Sets the sensitivity of a widget.

A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t interact with them. Insensitive widgets are known as “inactive”, “disabled”, or “ghosted” in some other toolkits.

sensitive

true to make the widget sensitive

fn set_size_request(&self, width: i32, height: i32)

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, GtkWindowExt::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 margin-start, margin-end, margin-top, and margin-bottom, but it does include pretty much all other padding or border properties set by any subclass of Widget.

width

width @self should request, or -1 to unset

height

height @self should request, or -1 to unset

fn set_state_flags(&self, flags: StateFlags, clear: bool)

Turns on flag values in the current widget state.

Typical widget states are insensitive, prelighted, etc.

This function accepts the values StateFlags::DIR_LTR and StateFlags::DIR_RTL but ignores them. If you want to set the widget’s direction, use set_direction().

This function is for use in widget implementations.

flags

State flags to turn on

clear

Whether to clear state before turning on @flags

fn set_tooltip_markup(&self, markup: Option<&str>)

Sets @markup as the contents of the tooltip, which is marked up with Pango markup.

This function will take care of setting the has-tooltip as a side effect, and of the default handler for the query-tooltip signal.

See also Tooltip::set_markup().

markup

the contents of the tooltip for @self

fn set_tooltip_text(&self, text: Option<&str>)

Sets @text as the contents of the tooltip.

If @text contains any markup, it will be escaped.

This function will take care of setting has-tooltip as a side effect, and of the default handler for the query-tooltip signal.

See also Tooltip::set_text().

text

the contents of the tooltip for @self

fn set_valign(&self, align: Align)

Sets the vertical alignment of @self.

align

the vertical alignment

fn set_vexpand(&self, expand: bool)

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

See set_hexpand() for more detail.

expand

whether to expand

fn set_vexpand_set(&self, set: bool)

Sets whether the vexpand flag will be used.

See set_hexpand_set() for more detail.

set

value for vexpand-set property

fn set_visible(&self, visible: bool)

Sets the visibility state of @self.

Note that setting this to true doesn’t mean the widget is actually viewable, see get_visible().

visible

whether the widget should be shown or not

fn should_layout(&self) -> bool

Returns whether @self 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

true if child should be included in measuring and allocating

fn show(&self)

👎Deprecated: Since 4.10

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.

Deprecated since 4.10

Use set_visible() instead

fn size_allocate(&self, allocation: &Allocation, baseline: i32)

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

This is a simple form of allocate().

allocation

position and size to be allocated to @self

baseline

The baseline of the child, or -1

fn snapshot_child( &self, child: &impl IsA<Widget>, snapshot: &impl IsA<Snapshot> )

Snapshot the a child of @self.

When a widget receives a call to the snapshot function, it must send synthetic WidgetImpl::snapshot() calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its WidgetImpl::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 Native.

child

a child of @self

snapshot

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

fn translate_coordinates( &self, dest_widget: &impl IsA<Widget>, src_x: f64, src_y: f64 ) -> Option<(f64, f64)>

👎Deprecated: Since 4.12

Translate coordinates relative to @self’s allocation to coordinates relative to @dest_widget’s allocations.

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

Deprecated since 4.12

Use gtk_widget_compute_point() instead

dest_widget

a Widget

src_x

X position relative to @self

src_y

Y position relative to @self

Returns

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

dest_x

location to store X position relative to @dest_widget

dest_y

location to store Y position relative to @dest_widget

fn trigger_tooltip_query(&self)

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

fn unmap(&self)

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

This function is only for use in widget implementations.

fn unparent(&self)

Dissociate @self from its parent.

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

fn unrealize(&self)

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

This function is only useful in widget implementations.

fn unset_state_flags(&self, flags: StateFlags)

Turns off flag values for the current widget state.

See set_state_flags().

This function is for use in widget implementations.

flags

State flags to turn off

fn height_request(&self) -> i32

Override for height request of the widget.

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

fn set_height_request(&self, height_request: i32)

Override for height request of the widget.

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

fn width_request(&self) -> i32

Override for width request of the widget.

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

fn set_width_request(&self, width_request: i32)

Override for width request of the widget.

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

fn connect_destroy<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Signals that all holders of a reference to the widget should release the reference that they hold.

May result in finalization of the widget if all references are released.

This signal is not suitable for saving widget state.

fn connect_direction_changed<F: Fn(&Self, TextDirection) + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when the text direction of a widget changes.

previous_direction

the previous text direction of @widget

fn connect_hide<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when @widget is hidden.

fn connect_keynav_failed<F: Fn(&Self, DirectionType) -> Propagation + 'static>( &self, f: F ) -> SignalHandlerId

Emitted if keyboard navigation fails.

See keynav_failed() for details.

direction

the direction of movement

Returns

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

fn connect_map<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when @widget is going to be mapped.

A widget is mapped when the widget is visible (which is controlled with visible) and all its parents up to the toplevel widget are also visible.

The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of unmap.

fn connect_mnemonic_activate<F: Fn(&Self, bool) -> Propagation + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when a widget is activated via a mnemonic.

The default handler for this signal activates @widget if @group_cycling is false, or just makes @widget grab focus if @group_cycling is true.

group_cycling

true if there are other widgets with the same mnemonic

Returns

true to stop other handlers from being invoked for the event. false to propagate the event further.

fn connect_move_focus<F: Fn(&Self, DirectionType) + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when the focus is moved.

The ::move-focus signal is a keybinding signal.

The default bindings for this signal are Tab to move forward, and Shift+Tab to move backward.

direction

the direction of the focus move

fn emit_move_focus(&self, direction: DirectionType)

fn connect_query_tooltip<F: Fn(&Self, i32, i32, bool, &Tooltip) -> bool + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when the widget’s tooltip is about to be shown.

This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering “above” @widget; or emitted when @widget got focus in keyboard mode.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case true should be returned, false otherwise. Note that if @keyboard_mode is true, the values of @x and @y are undefined and should not be used.

The signal handler is free to manipulate @tooltip with the therefore destined function calls.

x

the x coordinate of the cursor position where the request has been emitted, relative to @widget’s left side

y

the y coordinate of the cursor position where the request has been emitted, relative to @widget’s top

keyboard_mode

true if the tooltip was triggered using the keyboard

tooltip

a Tooltip

Returns

true if @tooltip should be shown right now, false otherwise.

fn connect_realize<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when @widget is associated with a gdk::Surface.

This means that realize() has been called or the widget has been mapped (that is, it is going to be drawn).

fn connect_show<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when @widget is shown.

fn connect_state_flags_changed<F: Fn(&Self, StateFlags) + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when the widget state changes.

See state_flags().

flags

The previous state flags.

fn connect_unmap<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when @widget is going to be unmapped.

A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden.

As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.

fn connect_unrealize<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when the gdk::Surface associated with @widget is destroyed.

This means that unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden).

fn connect_can_focus_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_can_target_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_css_classes_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_cursor_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_focus_on_click_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_focusable_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_halign_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_has_default_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_has_focus_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_has_tooltip_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_height_request_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_hexpand_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_hexpand_set_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_layout_manager_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_margin_bottom_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_margin_end_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_margin_start_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_margin_top_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_opacity_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_overflow_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_parent_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_receives_default_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_root_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_scale_factor_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_sensitive_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_tooltip_markup_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_tooltip_text_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_valign_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_vexpand_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_vexpand_set_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_visible_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

fn connect_width_request_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Widget>> WidgetExt for O