bancaldo™

torna all’indice appunti

Label

Il widget Gtk.Label è un widget che permette di visualizzare testo non editabile.
Spesso viene utilizzata come “etichetta”, a fianco di una text-entry (Gtk.Entry).
La larghezza della label, sarà arrangiata in base alla lunghezza de testo che conterrà.
E’ possibile anche inserire testi multiriga, aggiugendo “/n”.
Può contenere markup e link.

Per creare una Label si utilizza il costruttore Gtk.Label(*args, **kwargs),
dove l’argomento più significativo è ovviamente “label”.

E’ 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):

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

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

 
>>> label.set_label("another text")
>>> label.get_text()
'another text'

Le properties principali sono:

Name	Type	Flags	Short Description
angle	float	r/w/en	L’angolo di rotazione della label
attributes	Pango.AttrList	r/w	Una lista di style attributes da applicare al testo della label
cursor-position	int	r	La posizione corrente del cursore (in caratteri)
ellipsize	Pango.EllipsizeMode	r/w/en	Il posto dove applicare l’ellipse (“…”), se la label è più lunga dello spazio disponibile
justify	Gtk.Justification	r/w/en	Il tipo di allineamento delle linee nel testo
label	str	r/w	Il testo della label
lines	int	r/w/en	Il numero desiderato di linee quando eseguiamo l’ellipsizing di una wrapped label
max-width-chars	int	r/w/en	La massima larghezza della label (in caratteri)
mnemonic-keyval	int	r	La mnemonic accelerator key della label
mnemonic-widget	Gtk.Widget	r/w	Il widgetda attivare quando la mnemonic key della label viene premuta
pattern	str	w	Una stringa con caratteri “_” nelle posizioni corrispondenti ai caratteri da sottolineare nel testo
selectable	bool	r/w/en	Se il testo della label può essere selezionato
selection-bound	int	r	La posizione della fine opposta della selezione, dal cursore (in caratteri)
single-line-mode	bool	r/w/en	Se la label è in single line mode
track-visited-links	bool	r/w/en	Se i link visitati rimangono tracciati (cambio di colore)
use-markup	bool	r/w/en	Se il testo della label include XML markup. Vedi Pango.parse_markup()
use-underline	bool	r/w/en	Se True, una sottolineatura nel testo indica, per il carattere successivo, la mnemonic accelerator key
width-chars	int	r/w/en	La larghezza della label (in caratteri)
wrap	bool	r/w/en	Se True esegue il wrap delle linee se il testo diventa troppo lungo
wrap-mode	Pango.WrapMode	r/w/en	Se wrap è True, controlla come viene effettuato il line-wrapping

Segnali

I segnali principali sono:

Name	Short Description
activate-current-link	un keybinding-signal emesso quando l’utente attiva il link contenuto nella label;
activate-link	un segnale emesso per attivare una URI;
copy-clipboard	il segnale “::copy-clipboard” è un keybinding-signal emesso quando si copia il contenuto della label sul clipboard;
move-cursor	il segnale “::move-cursor” è un keybinding-signal emesso quand si inizia un movimento del cursore;
populate-popup	il segnale “::populate-popup” emesso prima di mostrare il context menu di una label;

Metodi

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

new():

Il costruttore per creare una nuova Gtk.Label.

new_with_mnemonic(str)

Un altro costruttore che crea una label impostandone direttamente il testo.
Utilizzando l’underscore davanti al carattere desiderato, si ottiene il carattere “mnemonic”
(alt + …). Se dovesse essere necessario far apparire l’underscore come carattere nella label,
dovrà essere indicato con 2 underscores consecutivi.

>>> label = Gtk.Label.new_with_mnemonic("_mnemonic label")
>>> label.get_text()
'mnemonic label'
>>> label = Gtk.Label.new_with_mnemonic("label__with__underscores")
>>> label.get_text()
'label_with_underscores'

I Parametri sono:
str: il testo della label;

get_angle()

Ritorna l’angolo di rotazione della label:

>>> label.get_angle()
0.0

get_attributes()

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

get_current_uri()

Ritorna l’URI attivo nella label. Il link attivo è quello sotto il puntatore del mouse, o, in una
label selezionabile, il link sul quale si trova il cursore.
Questa funzione è utile utilizzando l’handler “activate-link” o “query-tooltip”.

get_ellipsize()

Ritorna la posizione di “ellipsize” (“…”) quando non c’è abbastanza spazio per un testo.

get_justify()

Ritorna il tipo di giustificazione della label;
Il default per una label, è un enum di tipo GTK_JUSTIFY_LEFT.

get_label()

Ritorna il testo contenuto nel widget label, compresi gli mnemonic e gli eventuali Pango markup,
a differenza di get_text() che ritorna il testo puro.

>>> mlabel = Gtk.Label.new()
>>> mlabel.set_markup("<b>markup</b> label")
>>> mlabel.get_text()
'markup label'
>>> mlabel.get_label()
'<b>markup</b> label'

get_layout()

Ritorna il Pango.Layout utilizzato per visualizzare la label. Il layout è utile ad esempio per
convertire la text-position, in pixel-position.

get_layout_offsets()

Ritorna le coordinate x e y dove la label disegnerà il Pango.Layout che rappresenta il testo nella
label stessa. Utile per convertire i mouse events in coordinate nel Pango.Layout, ad esempio per
catturare azioni quando solo una parte della label viene cliccata.

get_line_wrap()

Ritorna True, se le linee nella label sono automaticamente “wrappate”.
Vedi set_line_wrap().

get_line_wrap_mode()

Ritorna il tipo di line-wrap (enum Pango.WrapMode) utilizzato nella label.

>>> mlabel.get_line_wrap_mode()
<enum PANGO_WRAP_WORD of type Pango.WrapMode>
>>> mlabel.get_line_wrap_mode().real
0

get_lines()

Ritorna il numero di linee alle quali una label wrappata o con ellipse, dovrebbe essere limitata.

get_max_width_chars()

Ritorna il valore massimo di larghezza della label, in caratteri.

get_mnemonic_keyval()

Ritorna il numero corrispondente alla mnemonic key settata per la label.
Se non è impostato alcun mnemonic, viene ritornato Gdk.KEY_VoidSymbol.

>>> mlabel = Gtk.Label.new_with_mnemonic("_mnemonic label")
>>> mlabel.get_mnemonic_keyval()
109
>>> chr(109)
'm'

get_mnemonic_widget()

Ritorna il target del mnemonic (keyboard shortcut) della label.

get_selectable()

Ritorna True, se la label è selectable, altrimenti False

get_selection_bounds()

Ritorna True se ci sono caratteri selezionati nella label, e se sì, le posizioni di start e di end
selection. Altrimenti ritorna False:

>>> mlabel.set_selectable(True)
>>> mlabel.select_region(2, 5)
>>> mlabel.get_selection_bounds()
(True, start=2, end=5)

get_single_line_mode()

Ritorna True se la label è in single line mode.

get_text()

Ritorna il testo della label senza eventuali mnemonic e Pango markups.

get_track_visited_links()

Ritorna True se la label sta tenendo traccia del link cliccati.

get_use_markup()

Ritorna True se il testo della label viene interpretato come “marked up” dal Pango markup language

>>> label = Gtk.Label("normal label")
>>> label.get_use_markup()
False
>>> markuplabel = Gtk.Label.new()
>>> markuplabel.set_markup("<b>markup</b> label")
>>> markuplabel.get_use_markup()
True

get_use_underline()

Ritorna True se l’underscore contenuto nella label, indica uno mnemonic.

get_width_chars()

Ritorna la larghezza della label, in charatteri

get_xalign()

Ritorna il valore della property xalign; i valori di xalign vanno da 0.0 a 1.0
0.0: indica allineamento a sinistra
1.0: indica allineamento a destra
0.5: indica la centratura orizzontale

get_yalign()

Ritorna il valore della property yalign; i valori di xalign vanno da 0.0 a 1.0
0.0: indica allineamento TOP
1.0: indica allineamento BOTTOM
0.5: indica la centratura verticale

select_region(start_offset, end_offset)

Seleziona un range di caratteri nella label.
Se la label non è selectable, questa funzione non ha effetto.
I Parametri sono:
start_offset: inizio della regione (in caratteri);
end_offset: fine della regione (in caratteri);

set_angle(angle)

Setta l’angolo di rotazione della label in senso antiorario:
90.0: legge la label dall’basso verso l’alto
270.0: legge la label dall’alto verso il basso
I Parametri sono:
angle: l’angolo di rotazione della label (0.0 a 359.5 gradi);

set_attributes(attrs)

Setta un lista di attributi Pango.AttrList che verrà integrata al testo della label e agli attributi
precedentemente settati.
Non è però raccomandato mescolare markup strings con attributi settati manualmente.
I Parametri sono:
attrs: la lista di attributi Pango.AttrList da settare alla label;

set_ellipsize(mode)

Setta il tipo di “ellipsize” (“…”), quando non c’è abbastanza spazio per un testo lungo.
Il tipo di ellipsize è un enum Pango.EllipsizeMode
e può assumere i seguenti valori:
NONE (0): nessuna ellipsization;
START (1): omette i caratteri all’inizio del testo;
MIDDLE (2): omette i caratteri a centro testo;
END (3): omette i caratteri alla fine del testo;

>>> from gi.repository import Pango
>>> label.set_ellipsize(Pango.EllipsizeMode.END)

I Parametri sono:
mode: il tipo di ellipsize mode (Pango.EllipsizeMode);

set_justify(jtype)

Setta l’allineamento delle linee nel testo della label.
Il valore di default è l’enum Gtk.Justification.LEFT.
Per settare l’allineamento dell’intera label invece, usare Gtk.Widget.set_halign().
Questo metodo non ha effetto su label con singola linea.
I Parametri sono:
jtype: il tipo di justification delle linee della label;

set_label(str)

Setta il testo della label e viene interpretata comprendendo eventuali underlines (per gli mnemonic)
e/o Pango markup.
I Parametri sono:
str: il testo da settare nella label;

set_line_wrap(wrap)

Setta il line wrapping nella label. Settando wrap a True, quando il testo eccede la larghezza del
widget, il testo viene spezzato.
Per le label che devono wrappare ad una specifica posizione, settare il size della label con il
metodo set_size_request().
I Parametri sono:
wrap: il boolean che setta o meno il wrapping delle linee;

set_line_wrap_mode(wrap_mode)

Se il wrap delle linee è attivo (set_line_wrap(True)), questo metodo controlla come viene effettuato
il wrap stesso.
Il default è un enum Pango.WrapMode.WORD, il quale esegue un wrap ai bordi della parola.
Gli enum disponibili sono:
WORD (0): wrap lines ai bordi della parola;
CHAR (1): wrap lines ai bordi del carattere;
WORD_CHAR (2): wrap lines ai bordi della parola, ma se non c’è spazio, passa ai bordi del carattere.
I Parametri sono:
wrap_mode: il tipo di wrap mode (Pango.WrapMode) delle linee;

set_lines(lines)

Setta il numero di linee alle quali una label con ellipse e wrapping attivi, deve essere limitata.
Ovviamente devono essere attivi il wrap e l’ellipse (“…”).
I Parametri sono:
lines: il numero delle linee sui cui ha effetto il wrapping e
l’ellipsize;

set_markup(str)

Esegue il parsing della stringa con il Pango text markup language, settando il
testo della label con gli attributi passati in str.
Questo metodo setta la property “use-markup” a True.
Se str contiene dati esterni, può essere necessario eseguire un “escape” su di essa con i metodi
markup_escape_text(), o g_markup_printf_escaped():
I Parametri sono:
str: il testo con markup da inserire nella label;

set_markup_with_mnemonic(str)

Esegue il parsing della stringa con il Pango text markup language, settando il testo
della label con gli attributi passati in str.
Se i caratteri della stringa sono preceduti da underscore, questi saranno i caratteri mnemonic.
I Parametri sono:
str: il testo con markup da inserire nella label con mnemonic;

set_max_width_chars(n_chars)

Setta la larghezza massima in caratteri della label.
I Parametri sono:
n_chars: la larghezza della label (in caratteri);

set_mnemonic_widget(widget)

Se la label ha uno mnemonic key, ad esempio usando metodi come set_markup_with_mnemonic(),
set_text_with_mnemonic(), new_with_mnemonic() o settando a True la property
“use_underline”, la label stessa verrà automaticamente associata al widget passato come argomento.
Il target widget riceverà il segnale “mnemonic-activate”. L’handler di default per questo segnale
attiverà il widget, se non ci saranno conflitti
con altri mnemonic, in caso contrario effettuerà il toggle focus tra i widget in conflitto.
I Parametri sono:
widget: il widget per gli mnemonic;

set_pattern(pattern)

Setta il pattern “underlines” nel testo della label.
Esempio: se il testo della label è “FooBarBaz”, passando un pattern di questo tipo “___ ___”
sottolineerà “Foo” and “Baz”, ma non “Bar”.
I Parametri sono:
pattern: il pattern da settare sul testo della label;

set_selectable(setting)

Settando “setting” a True, si permette il copia/incolla del testo della label.
I Parametri sono:
setting: il boolean che setta il testo della label selezionabile;

set_single_line_mode(single_line_mode)

Setta il “single line” mode nella label.
I Parametri sono:
single_line_mode: il boolean che setta il testo su una sola linea;

set_text(str)

Setta il testo della label, sovrascrivendo i precedenti contenuti, cancellando eventuali mnemonic
accelerators e settando a False, la property “use-underline”.
Come effetto collaterale, setterà a False anche la property “use-markup”.
I Parametri sono:
str: il testo da settare nella label;

set_text_with_mnemonic(str)

Setta il testo della label a str e i caratteri preceduti da underscore, verranno interpretati
come keybord accelerators.
I Parametri sono:
str: il testo della label con gli mnemonic;

set_track_visited_links(track_links)

settando a True “track_links”, la label terrà traccia dei link cliccati (cambio di colore):
I Parametri sono:
track_links: il boolean che attiva settato a True, tiene traccia
visivamete, dei link visitati;

set_use_markup(setting)

Mettendo a True “setting”, vuol dire che la label conterrà markup in Pango’s markup language.
I Parametri sono:
setting: il boolean che permette di usare o meno il markup language;

set_use_underline(setting)

Settando a True “setting”, indichiamo che i caratteri preceduti da underscore, saranno mnemonic
accelerator key.
I Parametri sono:
setting: il boolean che setta o meno, l’uso degli underline, che
definiscono i caratteri da utilizzare per gli mnemonic accelerator key;

set_width_chars(n_chars)

Setta la larghezza in caratteri desiderata (non la massima ammessa).
I Parametri sono:
n_chars: la larghezza desiderata della label, in caratteri;

set_xalign(xalign)

Setta la property “xalign” al valore passato come argomento. I valori di xalign vanno da 0.0 (LEFT)
a 1.0 (RIGHT); 0.5 indica centrato orizzontalmente.
I Parametri sono:
xalign: l’allineamento della label (0.0 – 1.0);

set_yalign(yalign)

Setta la property “yalign” al valore passato come argomento. I valori di yalign vanno da 0.0 (TOP)
a 1.0 (BOTTOM); 0.5 indica centrato verticalmente.
I Parametri sono:
yalign: l’allineamento della label (0.0 – 1.0);

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, Pango


class GWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title="Label Example")
        self.set_default_size(width=200, height=50)
        label = Gtk.Label.new_with_mnemonic("label__with__underscores")
        mlabel = Gtk.Label.new_with_mnemonic("_mnemonic label")
        e_label = Gtk.Label(label="a very long, long, long, long, long text")
        e_label.set_ellipsize(Pango.EllipsizeMode.END)
        markuplabel = Gtk.Label.new()
        markuplabel.set_markup('<span foreground="blue" weight="bold">'
                               'markup</span>'
                               ' <span background="white" '
                               'foreground="red" style="italic">'
                               'label</span>')
        dlabel = Gtk.Label.new("diagonal")
        dlabel.set_angle(45.0)

        hbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10)

        hbox.pack_start(label, True, True, 0)
        hbox.pack_start(mlabel, True, True, 0)
        hbox.pack_start(e_label, True, True, 0)
        hbox.pack_start(markuplabel, True, True, 0)
        hbox.pack_start(dlabel, True, True, 0)
        self.add(hbox)


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

link di riferimento:

torna all’indice degli appunti
Gtk3 Label