Gtk.SearchBar

Gtk.SearchBar — A toolbar to integrate a search entry with

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.SearchBar

Functions:

• new () -> Gtk.Widget
• connect_entry (self, entry:Gtk.Entry)
• get_search_mode (self) -> bool
• set_search_mode (self, search_mode:bool)
• get_show_close_button (self) -> bool
• set_show_close_button (self, visible:bool)
• handle_event (self, event:Gdk.Event) -> bool

Description:

Gtk.SearchBar is a container made to have a search entry (possibly with additional connex widgets, such as drop-down menus, or buttons) built-in. The search bar would appear when a search is started through typing on the keyboard, or the application’s search mode is toggled on.

For keyboard presses to start a search, events will need to be forwarded from the top-level window that contains the search bar.

See Gtk.SearchBar::handle_event() for example code. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items.

You will also need to tell the search bar about which entry you are using as your search entry using Gtk.SearchBar::connect_entry().

The following example shows you how to create a more complex search entry.

Creating a search bar

    self.searchbar = Gtk.SearchBar()
    grid.attach(self.searchbar, 0, 1, 1, 1)

    searchentry = Gtk.SearchEntry()
    self.searchbar.connect_entry(searchentry)
    self.searchbar.add(searchentry)

Function Details:

new()

new () -> Gtk.Widget

Creates a Gtk.SearchBar. You will need to tell it aboutwhich widget is going to be your text entry usingGtk.SearchBar:connect_entry().

• Returns: a new Gtk.SearchBar

• Since: 3.10

connect_entry()

connect_entry (self, entry:Gtk.Entry)

Connects the Gtk.Entry widget passed as the one to be used inthis search bar. The entry should be a descendant of the search bar.This is only required if the entry isn’t the direct child of thesearch bar (as in our main example).

• Since: 3.10

get_search_mode()

get_search_mode (self) -> bool

Returns whether the search mode is on or off.

• Returns: whether search mode is toggled on

• Since: 3.10

set_search_mode()

set_search_mode (self, search_mode:bool)

Switches the search mode on or off.

• Since: 3.10

get_show_close_button()

get_show_close_button (self) -> bool

Returns whether the close button is shown.

• Returns: whether the close button is shown

• Since: 3.10

set_show_close_button()

set_show_close_button (self, visible:bool)

Shows or hides the close button. Applications thatalready have a “search” toggle button should not show a closebutton in their search bar, as it duplicates the role of thetoggle button.

• Since: 3.10

handle_event()

handle_event (self, event:Gdk.Event) -> bool

This function should be called when the top-levelwindow which contains the search bar received a key event. If the key event is handled by the search bar, the bar willbe shown, the entry populated with the entered text and GDK_EVENT_STOPwill be returned. The caller should ensure that events arenot propagated further. If no entry has been connected to the search bar, usingGtk.SearchBar:connect_entry(), this function will returnimmediately with a warning.

• Returns: GDK_EVENT_STOP if the key press event resultedin text being entered in the search entry (and revealingthe search bar if necessary), GDK_EVENT_PROPAGATE otherwise.

• Since: 3.10

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
from gi.repository import Gdk

class SearchBar(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_default_size(250, -1)
        self.set_title("SearchBar")
        self.connect("key-press-event", self.on_key_event)
        self.connect("destroy", Gtk.main_quit)

        grid = Gtk.Grid()
        self.add(grid)

        label = Gtk.Label("Press Control+F to initiate find")
        grid.attach(label, 0, 0, 1, 1)

        self.searchbar = Gtk.SearchBar()
        grid.attach(self.searchbar, 0, 1, 1, 1)

        searchentry = Gtk.SearchEntry()
        self.searchbar.connect_entry(searchentry)
        self.searchbar.add(searchentry)

    def on_key_event(self, widget, event):
        shortcut = Gtk.accelerator_get_label(event.keyval, event.state)

        if shortcut in ("Ctrl+F", "Ctrl+Mod2+F"):
            if self.searchbar.get_search_mode():
                self.searchbar.set_search_mode(False)
            else:
                self.searchbar.set_search_mode(True)

window = SearchBar()
window.show_all()

Gtk.main()