Struct gtk4::SearchEntry

#[repr(transparent)]
pub struct SearchEntry { /* private fields */ }

SearchEntry is an entry widget that has been tailored for use as a search entry.

The main API for interacting with a SearchEntry as entry is the Editable interface.

It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry.

To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, SearchEntry emits the signal::SearchEntry::search-changed signal which can be used instead of the signal::Editable::changed signal.

The signal::SearchEntry::previous-match, signal::SearchEntry::next-match and signal::SearchEntry::stop-search signals can be used to implement moving between search results and ending the search.

Often, SearchEntry will be fed events by means of being placed inside a SearchBar. If that is not the case, you can use set_key_capture_widget() to let it capture key input from another widget.

SearchEntry provides only minimal API and should be used with the Editable API.

CSS Nodes

entry.search
╰── text

SearchEntry has a single CSS node with name entry that carries a .search style class, and the text node is a child of that.

Accessibility

SearchEntry uses the AccessibleRole::SearchBox role.

Implements

WidgetExt, glib::ObjectExt, AccessibleExt, BuildableExt, ConstraintTargetExt, EditableExt, WidgetExtManual, AccessibleExtManual, EditableExtManual

Implementations

impl SearchEntry

pub fn new() -> SearchEntry

Creates a SearchEntry.

Returns

a new SearchEntry

pub fn builder() -> SearchEntryBuilder

Creates a new builder-pattern struct instance to construct SearchEntry objects.

This method returns an instance of SearchEntryBuilder which can be used to create SearchEntry objects.

pub fn key_capture_widget(&self) -> Option<Widget>

Gets the widget that @self is capturing key events from.

Returns

The key capture widget.

pub fn search_delay(&self) -> u32

Available on crate feature v4_8 only.

Get the delay to be used between the last keypress and the signal::SearchEntry::search-changed signal being emitted.

Returns

a delay in milliseconds.

pub fn set_key_capture_widget(&self, widget: Option<&impl IsA<Widget>>)

Sets @widget as the widget that @self will capture key events from.

Key events are consumed by the search entry to start or continue a search.

If the entry is part of a SearchBar, it is preferable to call SearchBar::set_key_capture_widget() instead, which will reveal the entry in addition to triggering the search entry.

Note that despite the name of this function, the events are only ‘captured’ in the bubble phase, which means that editable child widgets of @widget will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with EventControllerKey::forward().

widget

a Widget

pub fn set_search_delay(&self, delay: u32)

Available on crate feature v4_8 only.

Set the delay to be used between the last keypress and the signal::SearchEntry::search-changed signal being emitted.

delay

a delay in milliseconds

pub fn activates_default(&self) -> bool

Whether to activate the default widget when Enter is pressed.

pub fn set_activates_default(&self, activates_default: bool)

Whether to activate the default widget when Enter is pressed.

pub fn placeholder_text(&self) -> Option<GString>

The text that will be displayed in the SearchEntry when it is empty and unfocused.

pub fn set_placeholder_text(&self, placeholder_text: Option<&str>)

The text that will be displayed in the SearchEntry when it is empty and unfocused.

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

Emitted when the entry is activated.

The keybindings for this signal are all forms of the Enter key.

pub fn emit_activate(&self)

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

Emitted when the user initiates a move to the next match for the current search string.

This is a keybinding signal.

Applications should connect to it, to implement moving between matches.

The default bindings for this signal is Ctrl-g.

pub fn emit_next_match(&self)

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

Emitted when the user initiates a move to the previous match for the current search string.

This is a keybinding signal.

Applications should connect to it, to implement moving between matches.

The default bindings for this signal is Ctrl-Shift-g.

pub fn emit_previous_match(&self)

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

Emitted with a delay. The length of the delay can be changed with the property::SearchEntry::search-delay property.

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

Emitted when the user initiated a search on the entry.

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

Emitted when the user stops a search via keyboard input.

This is a keybinding signal.

Applications should connect to it, to implement hiding the search entry in this case.

The default bindings for this signal is Escape.

pub fn emit_stop_search(&self)

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

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

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

Available on crate feature v4_8 only.

Trait Implementations

impl Clone for SearchEntry

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SearchEntry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SearchEntry

fn default() -> Self

Returns the “default value” for a type.

impl Display for SearchEntry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for SearchEntry

fn hash<H>(&self, state: &mut H)where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SearchEntry

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for SearchEntry

type Parent = Widget

impl<OT: ObjectType> PartialEq<OT> for SearchEntry

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for SearchEntry

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for SearchEntry

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for SearchEntry

impl IsA<Accessible> for SearchEntry

impl IsA<Buildable> for SearchEntry

impl IsA<ConstraintTarget> for SearchEntry

impl IsA<Editable> for SearchEntry

impl IsA<Widget> for SearchEntry