bancaldo™

torna all’indice appunti

Entry

Il widget Gtk.Entry è un widget che permette di inserire testo in single-line.
Per creare una Entry si utilizza il costruttore Gtk.Entry(**kwargs).
Come per tutti gli altri widgets visti fino ad ora, è possibile settare i parametri del widget
anche successivamente alla sua costruzione, con i soliti metodi getter e setter
get_property(property_name) e set_property(property_name, property_value):

Le properties principali del widget Gtk.Entry sono:

Name	Type	Flags	Short Description
activates-default	bool	r/w/en	se attivare il widget di default (es. il default button di un dialog) quando si preme Enter
attributes	Pango.AttrList	r/w/en	Una lista di style attributes da applicare al testo della label
buffer	Gtk.EntryBuffer	r/w/c/en	l’oggetto Text buffer che ha in carico il testo della entry
caps-lock-warning	bool	r/w/en	se in caso di password viene mostrato un avviso con Caps Lock attivo
completion	Gtk.EntryCompletion	r/w/en	L’oggetto ausiliario per il completion (completamento)
cursor-position	int	r	La posizione corrente del cursore, in caratteri
editable	bool	r/w/en	Se il contenuto della entry può essere editato
enable-emoji-completion	bool	r/w/en	Se è attivo il suggerimento Emoji
has-frame	bool	r/w/en	Se False, rimuove il bordo esterno della entry
im-module	str	r/w/en	Quale modulo IM (Input Method) deve essere usato
input-hints	Gtk.InputHints	r/w/en	Hints per il comportamento del text field
input-purpose	Gtk.InputPurpose	r/w/en	Scopo del text field
invisible-char	int	r/w/en	Il carattere da usare quando mascheriamo il contenuto della entry(es. “password mode”)
invisible-char-set	bool	r/w	Se l'”invisible character” è stato settato
max-length	int	r/w/en	Massimo numero di caratteri per la entry. 0 se nessun massimo è settato
max-width-chars	int	r/w/en	La massima larghezza desiderata per la entry, in caratteri
overwrite-mode	bool	r/w/en	Se il nuovo testo sovrascrive quello esistente
placeholder-text	str	r/w/en	Mostra un testo suggeritore quando la entry è vuota e senza focus
populate-all	bool	r/w/en	Se emette il segnale “populate-popup” grazie ai popups
primary-icon-activatable	bool	r/w/en	Se la primary icon è attivabile
primary-icon-gicon	Gio.Icon	r/w/en	la Gio.Icon utilizzata per la primary icon
primary-icon-name	str	r/w/en	Il nome della icona per la primary icon
primary-icon-pixbuf	GdkPixbuf.Pixbuf	r/w/en	Il Primary pixbuf per la entry
primary-icon-sensitive	bool	r/w/en	Se la primary icon è sensitive
primary-icon-storage-type	Gtk.ImageType	r	Lo storage-type usato per la primary icon
primary-icon-tooltip-markup	str	r/w/en	il testo markup del tooltip sulla primary icon
primary-icon-tooltip-text	str	r/w/en	il testo del tooltip sulla primary icon
progress-fraction	float	r/w/en	Il progresso corrente del totale completato (es. inserimento dato)
progress-pulse-step	float	r/w/en	La frazione del lavoro totale da muovere come “bouncing block” ad ogni chiamata di Gtk.Entry.progress_pulse()
scroll-offset	int	r/en	Numero di pixels della entry che può scorrere sulla sinistra (out of the screen)
secondary-icon-activatable	bool	r/w/en	Se la secondary icon è attivabile
secondary-icon-gicon	Gio.Icon	r/w/en	La Gio.Icon per la secondary icon
secondary-icon-name	str	r/w/en	Il nome dell’icona per la secondary icon
secondary-icon-pixbuf	GdkPixbuf.Pixbuf	r/w/en	Il Secondary pixbuf per la entry
secondary-icon-sensitive	bool	r/w/en	Se la secondary icon è sensitive
secondary-icon-storage-type	Gtk.ImageType	r	Lo storage-type per la secondary icon
secondary-icon-tooltip-markup	str	r/w/en	il testo markup del tooltip sulla secondary icon
secondary-icon-tooltip-text	str	r/w/en	il testo del tooltip sulla secondary icon
selection-bound	int	r	La posizione del margine opposto della selezione, dal cursore in caratteri
show-emoji-icon	bool	r/w/en	Se mostrare una icona per le Emoji
tabs	Pango.TabArray	r/w/en	Un lista di posizioni di tabstop da applicare al testo della entry
text	str	r/w/en	Il contenuto della entry
text-length	int	r	La lunghezza del testo corrente della entry
truncate-multiline	bool	r/w/en	Se troncare le multiline quando incolliamo su una linea
visibility	bool	r/w/en	se False visualizza l’invisible str invece del testo (password mode)
width-chars	int	r/w/en	Larghezza della entry in caratteri
xalign	float	r/w/en	L’allineamento orizzontale da 0 (sinistra) a 1 (destra)

 
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
... 
>>> entry = Gtk.Entry()
>>> entry.set_property("text", "some text")
>>> entry.get_property("text")
'some text'

oppure con i metodi getter e setter specifici get_*property_name*()
e set_*property_name*(value):

 
>>> entry.set_text("another text")
>>> entry.get_text()
'another text'

Segnali

I segnali principali sono:

Name	Short Description
activate	il segnale “activate” viene emesso quando l’utente preme il tasto “Invio”
backspace	il segnale “backspace” è un keybinding-signal che viene emesso quando l’utente preme il tasto “BackSpace”;
copy-clipboard	il segnale “copy-clipboard” è anche esso un keybinding-signal, emesso quando si copia una selezione sul clipboard;
cut-clipboard	il segnale “cut-clipboard” è simile al precedente, ma viene emesso nell’operazione di “taglia”;
delete-from-cursor	il segnale “delete-from-cursor” è emesso quando l’utente inizia a cancellare il testo;
icon-press	il segnale “icon-press” viene emesso quando si clicca sulla icona della entry;
icon-release	il segnale “icon-release” viene emesso al rilascio del button quando si clicca sull’icona della entry;
insert-at-cursor	il segnale “insert-at-cursor” viene emesso quando l’utente inizia l’inserimento al cursore, di una stringa;
insert-emoji	il segnale “insert-emoji” viene emesso quando si utilizza, nella entry, il chooser delle Emoji;
move-cursor	il segnale “move-cursor” viene emesso quando viene mosso il cursore nella entry;
paste-clipboard	il segnale “paste-clipboard” viene emesso quando si incolla il contenuto copiato/tagliato, sul clipboard;
populate-popup	il segnale “populate-popup” viene emesso prima che venga visualizzato il context-menu della entry;
preedit-changed	se viene usato un input method, il testo digitato non verrà immediatamento spedito al buffer;
toggle-overwrite	il segnale “toggle-overwrite” viene emesso quando si ha il toggle sull’overwrite mode della entry.

Metodi

Di seguito i metodi utilizzabili con il widget Gtk.Entry:

new()

Metodo costruttore che crea una nuova Gtk.Entry.

new_with_buffer(buffer)

Metodo costruttore che crea una nuova Gtk.Entry con il text buffer specificato.
Buffer è un oggetto Gtk.EntryBuffer, che
contiene il testo visualizzato nella entry e può essere condiviso con altri oggetti Gtk.Entry.

>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk, GLib
>>> entry = Gtk.Entry(text="some text")
>>> buffer = entry.get_buffer()
>>> buffer.get_text()
'some text'
>>> entry2 = Gtk.Entry.new_with_buffer(buffer)
>>> entry2.get_text()
'some text'

get_activates_default()

Ritorna il valore settato con il metodo set_activates_default().

get_alignment()

Ritorna il valore dell’allineamento settato con il metodo set_alignment().
Il valore di default è 0.0, ovvero allineamento a sinistra.
Allineamento a destra ha valore 1.0.

get_attributes()

Ritorna la lista degli attributi settati con il metodo set_attributes()

get_buffer()

Ritorna l’oggetto Gtk.EntryBuffer che detiene il testo contenuto nella entry.

get_completion()

Ritorna l’oggetto Gtk.EntryCompletion in uso.
Tale oggetto, come suggerisce il nome, fornisce la funzione di completamento, durante la
digitazione nella entry.

get_icon_name(icon_pos)

Ritorna il nome dell’icona utilizzata, o None se assente.
Ritorna None anche in caso l’icona sia stata settata con altri metodi
(es. pixbuf, stock o gicon).
icon_pos è un enum Gtk.EntryIconPosition che può assumere i seguenti valori:
PRIMARY (0): all’inizio della entry (dipende dalla direzione del testo);
SECONDARY (1): alla fine della entry dipende dalla direzione del testo);
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_icon_pixbuf(icon_pos)

Ritorna l’oggetto GdkPixbuf.Pixbuf presente in posizione icon_pos (Gtk.EntryIconPosition).
Diversamente dagli altri metodi getter e setter relativi all’icona, questo metodo
funzionerà indipendentemente dal fatto che l’icona sia stata settata usando un GdkPixbuf.Pixbuf,
un Gio.Icon, uno stock item, o un icon name.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_icon_sensitive(icon_pos)

Ritorna True se l’icona appare “sensitive” o “insensitive”
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_icon_storage_type(icon_pos)

Ritorna il tipo di rappresentazione usata per salvare l’immagine (Gtk.ImageType).
Se l’icona non ha dati-immagine, il valore ritornato sarà di tipo Gtk.ImageType.EMPTY.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_icon_tooltip_markup(icon_pos)

Ritorna il testo (markup) contenuto nel tooltip relativo all’icona, in posizione “icon_pos”,
o None.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_icon_tooltip_text(icon_pos)

Ritorna il testo contenuto nel tooltip relativo all’icona, in posizione “icon_pos”, o None.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;

get_input_hints()

Ritorna il valore della property “input-hints”.

get_input_purpose()

Ritorna il valore della property “input-purpose”.

get_invisible_char()

Ritorna il carattere utilizzato per nascondere il testo (ad esempio nell’inserimento password).
Di Default viene utilizzato il pallino nero, ma può essere settato utilizzando il
metodo set_invisible_char().

>>> entry = Gtk.Entry()
>>> entry.get_invisible_char()
'●'
>>> entry.set_invisible_char("*")
>>> entry.get_invisible_char()
'*'

get_layout()

Ritorna l’oggetto Pango.Layout usato per visualizzare la entry.

get_layout_offsets()

Ritorna la posizione del Pango.Layout usato per il render del testo all’interno della entry.

get_max_length()

Ritorna il massimo numero di caratteri ammessi, o 0 se non c’è un valore massimo.

get_max_width_chars()

Ritorna il valore massimo della larghezza, in caratteri, della entry.

get_overwrite_mode()

Ritorna il valore settato con set_overwrite_mode(), cioè se il testo viene sovrascritto quando
digitiamo nella entry (True).

get_placeholder_text()

Ritorna la stringa che rappresenta il placeholder (suggerimento) della entry.

get_progress_fraction()

Ritorna il rapporto di completamento rispetto all’ valore settato con set_progress_fraction().

get_progress_pulse_step()

Ritorna il pulse step settati con set_progress_pulse_step().

get_tabs()

Ritorna i tabstops settati precedentemente
con il metodo set_tabs(), o None.

get_text()

Ritorna il testo contenuto nella entry.
E’ l’equivalente della chiamata al metodo Gtk.EntryBuffer.get_text().

get_text_area()

Ritorna un oggetto Gdk.Rectangle rappresentante l’area dove il testo della entry, viene disegnato.

get_text_length()

Ritorna il numero di caratteri nella entry, o 0 se assenti.
E’ equivalente alla chiamata al metodo Gtk.EntryBuffer.get_length().

>>> entry.set_text("some text")
>>> entry.get_text_length()
9
>>> entry.get_buffer().get_length()
9

get_visibility()

Ritorna True, se il testo nella entry è visibile, altrimenti None

get_width_chars()

Ritorna il valore settato con set_width_chars(), ovvero il numero di caratteri che conterrà la entry.
Questo ovviamente modifica la larghezza della entry, larghezza che verrà modificata anche dal tipo
di impacchettamento che verrà riservato al widget.

grab_focus_without_selecting()

Sposta il keyboard focus sulla entry.
Si comporta come il metodo Gtk.Widget.grab_focus(), senza selezionare il contenuto della entry.

im_context_filter_keypress(event)

Permette all’input method della entry, di gestire internamente gli eventi key press e key release.
Se ritorna True, l’evento “event” non verrà processato ulteriormente.
Event è un oggetto di tipo Gdk.EventKey.
Questo metodo dovrebbe essere chiamato dal nostro handler quando sovrascriviamo un determinato
key event handling. E’ necessario nel caso si voglia inserire il proprio key handling,
tra l’input method e il key event di default.

layout_index_to_text_index(layout_index)

Passando un layout_index (int), ritorna il byte index corripondente del contenuto della entry.
Parametri:
layout_index: il byte index nel text layout della entry;

progress_pulse()

Indica che è avvenuto un progresso parziale, ma non quale percentuale.
In pratica un progress-indicator segnala un’attività muovendosi avanti e indietro.
Per modificare la larghezza dell’indicatore durante il pulse, usare il metodo
Gtk.Entry.set_progress_pulse_step().

reset_im_context()

Resetta il context dell’input method. Può essere necessario quando la modifica del buffer,
incasini il comportamento dell’input method.

set_activates_default(setting)

Se settings = True, quando premiamo Enter nella entry, verrà attivato il
widget di default della window. Di solito significa che se è un dialog box che contiene la entry
sulla quale stiamo scrivendo, questo verrà chiuso, inquanto il default widget della window, molto
probabilmente, è un bottone che ha aperto il dialog box stesso.
setting: il boolean che settato a True attiva il default widget
quando premiamo Enter;

set_alignment(xalign)

Setta l’alignment orizzontale della entry.
Parametri:
xalign: è un float che va da 0.0 (allineamento a sinistra) a 1.0
(allineamento a destra);

set_attributes(attrs)

Setta un oggetto Pango.AttrList.
Gli attributi di questa lista saranno applicati al text della entry.
Parametri:
attrs: la lista di attributi Pango.AttrList;

set_buffer(buffer)

Setta l’oggetto Gtk.EntryBuffer che gestisce il testo della entry.

>>> entry = Gtk.Entry(text="some text")
>>> buffer = entry.get_buffer()
>>> buffer.get_text()
'some text'
>>> entry2 = Gtk.Entry.new_with_buffer(buffer)
>>> entry2.get_text()
'some text'

Parametri:
buffer: il Gtk.EntryBuffer che gestisce il testo della entry;

set_completion(completion)

Setta l’oggetto Gtk.EntryCompletion
da utilizzare per la funzione di completamento, durante la digitazione nella entry.
Parametri:
completion: The Gtk.EntryCompletion utilizzato per il completamento,
o None;

set_has_frame(setting)

Se setting = True (impostazione di default), la entry avrà un frame arrotondato,
altrimenti rettangolare.
Parametri:
setting: il boolean che abilita/disabilita il bordo della entry;

set_icon_activatable(icon_pos, activatable)

Se activatable = True, l’icona in posizione “icon_pos” sarà attivabile.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
activatable: il boolean che rende la icon specificata (primary o
secondary) attivabile o meno;

set_icon_drag_source(icon_pos, target_list, actions)

Setta l’icona alla posizione data cosicchà quando l’utente cliccherà e trascinerà l’icona, Gtk+ inizierà l’operazione di Drag.
Per gestire l’operazione di Drag dobbiamo conneterci al solito segnale “drag-data-get” (o possibilmente al segnale “::drag-data-delete”),
e usare il metodo get_current_icon_drag_source() nel nostro signal handler, per scoprire se il drag è cominciato da un’icona.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
target_list: è un oggetto Gtk.TargetList contenente i target ovvero
i formati nei quali possono essere forniti i dati.
actions: è un oggetto Gdk.DragAction ovvero un bitmask delle drag
actions concesse.

set_icon_from_gicon(icon_pos, icon)

Setta l’icona visualizzata nella entry, alla posizione specificata.
Se l’icona è sconosciuta, verrà utilizzata un’icona “broken image”.
Se icon = None, nessuna icona verrà visualizzata nella entry.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
icon: l’oggetto Gio.Icon dell’icona da settare, o None;

set_icon_from_icon_name(icon_pos, icon_name)

Setta l’icona visualizzata nella entry, alla posizione specificata.
Se l’icona è sconosciuta, verrà utilizzata un’icona “broken image”.
Se icon = None, nessuna icona verrà visualizzata nella entry.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
icon_name: un stringa rappresentante l’icona desiderata, o None;

Una corposa lista di icone può essere reperita qui

set_icon_from_pixbuf(icon_pos, pixbuf)

Setta l’icona visualizzata alla posizione desiderata, utilizzando un pixbuf.
Se pixbuf = None, nessuna icona verrà visualizzata
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
pixbuf: l’oggetto GdkPixbuf.Pixbuf, o None

set_icon_sensitive(icon_pos, sensitive)

Setta la sensitività per l’icona specificata, ovvero sensibile al click del mouse;
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
sensitive: True (default) se vogliamo che l’icona
appaia sensitiva al puntatore, False per inibirla;

set_icon_tooltip_markup(icon_pos, tooltip)

Setta il tooltip (markup) per l’icona nella posizione specificata.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
tooltip: la testo markup del tooltip da assegnare all’icona;

>>> entry.set_icon_from_icon_name(Gtk.EntryIconPosition.PRIMARY, "system-search-symbolic")
>>> entry.set_icon_tooltip_markup(Gtk.EntryIconPosition.PRIMARY, "<b>S</b>earch")
>>> entry.get_icon_tooltip_markup(Gtk.EntryIconPosition.PRIMARY)
'<b>S</b>earch'

set_icon_tooltip_text(icon_pos, tooltip)

Setta il tooltip (solo testo) per l’icona nella posizione specificata.
Parametri:
icon_pos: la Gtk.EntryIconPosition cioè la posizione dell’icona;
tooltip: la testo del tooltip da assegnare all’icona;

set_input_hints(hints)

Setta la property “input-hints” che permette agli input-methods di essere più specifici.
Parametri:
hints: l’oggetto Gtk.InputHints;

set_input_purpose(purpose)

Setta la property “input-purpose”, usata dalle tastiere on-screen e altri input methods.
Parametri:
purpose: l’oggetto Gtk.InputPurpose;

set_invisible_char(ch)

Setta il carattere da utilizzare al posto dei caratteri digitati, quando viene utilizzato
set_visibility(False), ovvero si rende il testo della entry, invisibile (“password mode”).
Di deafult GTK+ prende il carattere che nasconda di più quello sottostante.
Parametri:
ch: il carattere Unicode usato per il mask;

>>> newentry = Gtk.Entry()
>>> newentry.set_visibility(False)
>>> newentry.get_invisible_char()
'●'

set_max_length(max)

Setta la massima lunghezza del contenuto della entry. Se il contenuto eccede questo valore,
verrà troncato.
Parametri:
max: la massima lunghezza della entry;

>>> entry.set_max_length(3)
>>> entry.set_text("Some text")
>>> entry.get_text()
'Som'

set_max_width_chars(n_chars)

Setta il valore massimo della larghezza della entry, in caratteri.
Parametri:
n_chars: la massima lunghezza desiderata della entry;

set_overwrite_mode(overwrite)

Se overwrite = True, quando digitiamo nella entry, il viene sovrascritto (INS).
Parametri:
overwrite: il boolean che abilita/disabilita l’overwrite mode
della entry;

set_placeholder_text(text)

Setta il placeholder (suggerimento di cosa ci si aspetta venga inserito), che appare nella entry
quando è vuota o non ha il focus.
Parametri:
text: il testo del placeholder da settare nella entry;

set_progress_fraction(fraction)

Causa il riempimento del progress-indicator.
Parametri:
fraction: il float che indica di quanto riempire il progress
indicator e va da 0.0 a 1.0.

set_progress_pulse_step(fraction)

Setta a “fraction” la frazione della entry che rimbalzerà ad ogni chiamata di progress_pulse().
Parametri:
fraction: la frazione del totale che rappresenta il blocco che si
muoverà durante il bouncing;

set_tabs(tabs)

Setta un Pango.TabArray che contiene i tabstops che verranno applicati al testo della entry.
Parametri:
tabs: l’oggetto Pango.TabArray, ovvero la lista dei tabstops;

set_text(text)

Setta il testo nella entry
Parametri:
text: il testo da settare nella entry;

set_visibility(visible)

Setta se il contenuto della entry deve essere visibile (True).
Di default GTK+ prende il miglior “invisible character” disponibile nel font in uso
Nel caso di utilizzo con visible=False, sarebbe meglio settare le property “input-purpose” a
Gtk.InputPurpose.PASSWORD, o Gtk.InputPurpose.PIN per rafforzare il reale intento di questa entry.
Parametri:
visible: il boolean che visualizza o meno il testo come plain-text;

set_width_chars(n_chars)

Modifica il size richiesto della entry. Questo settaggio modifica il size, ma viene a sua volta
modificato da come decidiamo di “impacchettare” il widget nei contenitori che lo ospiteranno.
Parametri:
n_chars: la larghezza della entry in caratteri;

text_index_to_layout_index(text_index)

Converte da una posizione nel contenuto della entry, ad una posizione nel Pango.Layout della entry.
Parametri:
text_index: il byte index nel contenuto della entry;

unset_invisible_char()

Resetta l’invisible char settato con set_invisible_char() in modo che torni ad essere utilizzato
il char di default scelto in base al font in uso.

Pango’s Markup Language

Per tutto quello che concerne il Pango’s Markup Language, descrizione, sintassi e abbreviazioni,
fare riferimento alla pagina di Gnome Developers

Di seguito un codice d’esempio:

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


class GWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title="Entry example")
        self.set_size_request(200, 50)
        entry = Gtk.Entry()
        entry.set_placeholder_text("search")
        entry.set_icon_from_icon_name(Gtk.EntryIconPosition.PRIMARY,
                                      "system-search-symbolic")
        entry.set_icon_tooltip_markup(Gtk.EntryIconPosition.PRIMARY,
                                      "type <span foreground='Red'>word</span>")
        # bindings
        entry.connect("notify::text", self.on_entry)
        # layout
        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
        self.add(vbox)
        vbox.pack_start(entry, True, True, 0)

    def on_entry(self, entry, *args):
        print("INFO: searching for %s..." % entry.get_text())


if __name__ == "__main__":
    win = GWindow()
    win.connect("destroy", Gtk.main_quit)
    win.show_all()
    Gtk.main()

Nota:

Per catturare il testo digitato ad ogni pressione di un tasto, è utile connettersi al segnale
“notify::property_name”, che come ricordiamo viene emesso ogni qualvolta una property di un
widget, viene modificata.

link di riferimento:

torna all’indice degli appunti
Gtk3 Entry