Entries

Entries allows the user to enter text. GTK provides a few entry widgets for different use cases. Those are the generic Gtk.Entry, Gtk.PasswordEntry and Gtk.SearchEntry. Although none of these widgets derive from each other, they implement the Gtk.Editable interface, so they share some properties and methods. You can change and get the contents with the Gtk.Editable.props.text property. You can also limit the number of characters the entry can take with Gtk.Editable.props.max_width_chars.

Occasionally you might want to make an Entry widget read-only. This can be done by setting Gtk.Editable.props.editable to False.

Generic Entry

Gtk.Entry is the standard entry.

Gtk.Entry can be set to show a invisible character using Gtk.Entry.props.visibility and Gtk.Entry.props.invisible_char, this is useful to hide the text of the entry when it is used for example to retrieve passwords. Though Password Entry exist for this specific use case.

Gtk.Entry has the ability to display progress or activity information behind the text. This is similar to Gtk.ProgressBar widget and is commonly found in web browsers to indicate how much of a page download has been completed. To make an entry display such information, use Gtk.Entry.props.progress_fraction, Gtk.Entry.props.progress_pulse_step, or Gtk.Entry.progress_pulse().

Additionally, a Gtk.Entry can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use Gtk.Entry.set_icon_from_icon_name() or one of the various other properties and methods that set an icon from an icon name, Gio.Icon, or a Gdk.Paintable. To set a tooltip on an icon, use Gtk.Entry.set_icon_tooltip_text() or the corresponding function for markup.

Entries can have a placeholder text, just use Gtk.Entry.props.placeholder_text.

Password Entry

Gtk.PasswordEntry brings some features for password handing. It can show a button to toggle the visibility of the text if you set Gtk.PasswordEntry.props.show_peek_icon to True.

Search Entry

Gtk.SearchEntry is an entry specially designed for use as a search entry. Gtk.SearchEntry allows you to implement the popular “type to search” feature. You can use Gtk.SearchEntry.set_key_capture_widget() to set the parent widget that will redirect its key events to the entry.

Gtk.SearchEntry has the search-changed signal, it differs from Gtk.Editable’s changed in the sense that it gets emitted after a short delay that you can configure with Gtk.SearchEntry.props.search_delay. This way you can get reactive searching without over loading your backend.

Example

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk, GLib


class EntryWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Entry Demo')

        self.set_size_request(200, 100)

        self.timeout_id = None

        header = Gtk.HeaderBar()
        self.set_titlebar(header)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
        vbox.props.margin_start = 24
        vbox.props.margin_end = 24
        vbox.props.margin_top = 24
        vbox.props.margin_bottom = 24
        self.set_child(vbox)

        # Gtk.SearchEntry
        search = Gtk.SearchEntry()
        search.props.placeholder_text = 'Search Entry'
        search.set_key_capture_widget(self)
        header.set_title_widget(search)
        self.set_focus(search)

        # Gtk.Entry
        self.entry = Gtk.Entry()
        self.entry.set_text('Hello World')
        vbox.append(self.entry)

        hbox = Gtk.Box(spacing=6)
        vbox.append(hbox)

        self.check_editable = Gtk.CheckButton(label='Editable')
        self.check_editable.connect('toggled', self.on_editable_toggled)
        self.check_editable.props.active = True
        hbox.append(self.check_editable)

        self.check_visible = Gtk.CheckButton(label='Visible')
        self.check_visible.connect('toggled', self.on_visible_toggled)
        self.check_visible.props.active = True
        hbox.append(self.check_visible)

        self.pulse = Gtk.CheckButton(label='Pulse')
        self.pulse.connect('toggled', self.on_pulse_toggled)
        hbox.append(self.pulse)

        self.icon = Gtk.CheckButton(label='Icon')
        self.icon.connect('toggled', self.on_icon_toggled)
        hbox.append(self.icon)

        # Gtk.PasswordEntry
        pass_entry = Gtk.PasswordEntry()
        pass_entry.props.placeholder_text = 'Password Entry'
        pass_entry.props.show_peek_icon = True
        pass_entry.props.margin_top = 24
        vbox.append(pass_entry)

    def on_editable_toggled(self, button):
        value = button.get_active()
        self.entry.set_editable(value)

    def on_visible_toggled(self, button):
        self.entry.props.visibility = button.props.active

    def on_pulse_toggled(self, button):
        if button.get_active():
            self.entry.props.progress_pulse_step = 0.2
            # Call self.do_pulse every 100 ms
            self.timeout_id = GLib.timeout_add(100, self.do_pulse)
        else:
            # Don't call self.do_pulse anymore
            GLib.source_remove(self.timeout_id)
            self.timeout_id = None
            self.entry.props.progress_pulse_step = 0

    def do_pulse(self):
        self.entry.progress_pulse()
        return True

    def on_icon_toggled(self, button):
        if button.props.active:
            icon_name = 'system-search-symbolic'
        else:
            icon_name = None
        self.entry.set_icon_from_icon_name(
            Gtk.EntryIconPosition.PRIMARY, icon_name
        )


def on_activate(app):
    win = EntryWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)