Class SearchEntry

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.SearchEntry
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Editable, Proxy
@Generated("org.javagi.JavaGI") public class SearchEntry extends Widget implements Accessible, Buildable, ConstraintTarget, Editable

A single-line text entry widget for use as a search entry.

The main API for interacting with a GtkSearchEntry as entry is the GtkEditable interface.

An example GtkSearchEntry

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, GtkSearchEntry emits the Gtk.SearchEntry::search-changed signal which can be used instead of the Gtk.Editable::changed signal.

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

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

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

Shortcuts and Gestures

The following signals have default keybindings:

  • Gtk.SearchEntry::activate
  • Gtk.SearchEntry::next-match
  • Gtk.SearchEntry::previous-match
  • Gtk.SearchEntry::stop-search

CSS Nodes

entry.search
╰── text

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

Accessibility

GtkSearchEntry uses the Gtk.AccessibleRole.search_box role.

  • Constructor Details

    • SearchEntry

      public SearchEntry(MemorySegment address)
      Create a SearchEntry instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • SearchEntry

      public SearchEntry()
      Create a new SearchEntry.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the SearchEntry class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected SearchEntry asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • getInputHints

      public Set<InputHints> getInputHints()
      Gets the input purpose for entry.
      Returns:
      The input hints
      Since:
      4.14

    • getInputPurpose

      public InputPurpose getInputPurpose()
      Gets the input purpose of entry.
      Returns:
      The input hints
      Since:
      4.14

    • getKeyCaptureWidget

      public @Nullable Widget getKeyCaptureWidget()
      Gets the widget that this SearchEntry is capturing key events from.
      Returns:
      The key capture widget.

    • getPlaceholderText

      public @Nullable String getPlaceholderText()
      Gets the placeholder text associated with entry.
      Returns:
      The placeholder text.
      Since:
      4.10

    • getSearchDelay

      public int getSearchDelay()
      Get the delay to be used between the last keypress and the Gtk.SearchEntry::search-changed signal being emitted.
      Returns:
      a delay in milliseconds.
      Since:
      4.8

    • setInputHints

      public void setInputHints(Set<InputHints> hints)
      Sets the input hints for entry.
      Parameters:
      hints - the new input hints
      Since:
      4.14

    • setInputHints

      public void setInputHints(InputHints... hints)
      Sets the input hints for entry.
      Parameters:
      hints - the new input hints
      Since:
      4.14

    • setInputPurpose

      public void setInputPurpose(InputPurpose purpose)
      Sets the input purpose of entry.
      Parameters:
      purpose - the new input purpose
      Since:
      4.14

    • setKeyCaptureWidget

      public void setKeyCaptureWidget(@Nullable Widget widget)

      Sets widget as the widget that this SearchEntry 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 GtkSearchBar, it is preferable to call SearchBar.setKeyCaptureWidget(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).

      Parameters:
      widget - a GtkWidget

    • setPlaceholderText

      public void setPlaceholderText(@Nullable String text)
      Sets the placeholder text associated with entry.
      Parameters:
      text - the text to set as a placeholder
      Since:
      4.10

    • setSearchDelay

      public void setSearchDelay(int delay)
      Set the delay to be used between the last keypress and the Gtk.SearchEntry::search-changed signal being emitted.
      Parameters:
      delay - a delay in milliseconds
      Since:
      4.8

    • onActivate

      public SignalConnection<SearchEntry.ActivateCallback> onActivate(SearchEntry.ActivateCallback handler)

      Emitted when the entry is activated.

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

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivate

      public void emitActivate()
      Emits the "activate" signal. See onActivate(SearchEntry.ActivateCallback).

    • onNextMatch

      public SignalConnection<SearchEntry.NextMatchCallback> onNextMatch(SearchEntry.NextMatchCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitNextMatch

      public void emitNextMatch()
      Emits the "next-match" signal. See onNextMatch(SearchEntry.NextMatchCallback).

    • onPreviousMatch

      public SignalConnection<SearchEntry.PreviousMatchCallback> onPreviousMatch(SearchEntry.PreviousMatchCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPreviousMatch

      public void emitPreviousMatch()
      Emits the "previous-match" signal. See onPreviousMatch(SearchEntry.PreviousMatchCallback).

    • onSearchChanged

      public SignalConnection<SearchEntry.SearchChangedCallback> onSearchChanged(SearchEntry.SearchChangedCallback handler)
      Emitted with a delay. The length of the delay can be changed with the Gtk.SearchEntry:search-delay property.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSearchChanged

      public void emitSearchChanged()
      Emits the "search-changed" signal. See onSearchChanged(SearchEntry.SearchChangedCallback).

    • onSearchStarted

      public SignalConnection<SearchEntry.SearchStartedCallback> onSearchStarted(SearchEntry.SearchStartedCallback handler)
      Emitted when the user initiated a search on the entry.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSearchStarted

      public void emitSearchStarted()
      Emits the "search-started" signal. See onSearchStarted(SearchEntry.SearchStartedCallback).

    • onStopSearch

      public SignalConnection<SearchEntry.StopSearchCallback> onStopSearch(SearchEntry.StopSearchCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitStopSearch

      public void emitStopSearch()
      Emits the "stop-search" signal. See onStopSearch(SearchEntry.StopSearchCallback).

    • builder

      public static SearchEntry.Builder<? extends SearchEntry.Builder> builder()
      A SearchEntry.Builder object constructs a SearchEntry with the specified properties. Use the various set...() methods to set properties, and finish construction with SearchEntry.Builder.build().
      Returns:
      the builder object