bancaldo™

torna all’indice degli appunti

SpinButton

Il widget Gtk.SpinButton è un widget che consente all’utente di “aggiustare” un valore cliccando
sulle frecce laterali.
Oltre che essere incrementato e ridotto, il valore può essere inserito direttamente nella entry
del widget, con la comodità di essere validato, nello stesso momento dell’inserimento.

Per creare un SpinButton si utilizza il costruttore Gtk.SpinButton(**kwargs).

Le properties principali dell’oggetto spinbutton sono:

Name	Type	Flags	Short Description
adjustment	Gtk.Adjustment	r/w	l’oggetto Gtk.Adjustment che gestisce il valore dello spinbutton
climb-rate	float	r/w/en	il rapporto di accelerazione che abbiamo quando teniamo premuto un bottone o un tasto
digits	int	r/w/en	il numero di decimali da visualizzare nello spinbutton
numeric	bool	r/w/en	è un bool per visualizzare o meno i caratteri non numerici (True)
snap-to-ticks	bool	r/w/en	è un bool che se a True, trasforma automaticamente i valori errati, nei valori dello step più vicino
update-policy	Gtk.SpinButtonUpdatePolicy	r/w/en	è un oggetto Gtk.SpinButtonUpdatePolicy che regola l’aggiornamento dello spinbox. True si aggiorna anche in caso di valore errato
value	float	r/w/en	è un float legge il valore corrente, o ne setta uno nuovo
wrap	bool	r/w/en	è un bool per avere il wrap, una volta raggiunto i suoi limiti

 
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
>>> adjustment = Gtk.Adjustment(value=0, lower=0, upper=100, step_increment=2)
>>> spinbutton = Gtk.SpinButton(adjustment=adjustment, digits=1, value=20)

E’ possibile passare i parametri del widget in fase di costruzione, ma è possibile accedervi e
modificarli anche in seguito, utilizzando i metodi getter e setter get_property(property_name)
e set_property(property_name, property_value):

 
>>> spinbutton.get_property("value")
20.0
>>> spinbutton.set_property("digits", 2)

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

 
>>> spinbutton.set_value(50)
>>> spinbutton.get_value()
50.0

Segnali

Per connettere un widget ad una callback, in modo che, quando viene emesso un segnale specifico,
quest’ultima venga invocata, si utilizza il metodo connect(signal, callback).
I segnali relativi allo spinbutton sono:

Name	Short Description
change-value	il segnale “change-value” viene emesso quando il valore dello spinbutton inizia a cambiare
input	il segnale “input” può essere usato per influenzare la conversione dell’input in un valore
output	il segnale “output” può essere usato per cambiare la formattazione del valore che viene visualizzato nella entry dello spinbutton
value-changed	il segnale “value-changed” viene emesso quando il valore rappresentato dallo spin button, cambia
wrapped	il segnale “wrapped” viene emesso subito dopo che lo spin button wrappa dal suo valore massimo, al suo minimo e vice-versa

 
>>> def on_change_value(button):
...     print("INFO: changing value to %s" % button.get_value())
...     
>>> spinbutton.connect("value_changed", on_change_value)
61
>>> spinbutton.set_value(20)
INFO: changing value to 20.0

Metodi

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

new(adjustment, climb_rate, digits)

Il metodo costruttore che crea un nuovo oggetto Gtk.SpinButton.
Parametri:
adjustment: l’oggetto Gtk.Adjustment che lo spinbutton deve usare,
o None;
climb_rate: è un float che indica di quanto
accelererà il rapporto di cambiamento, quando teniamo premuti il bottone o il tasto di modifica;
digits: il numero di decimali da visualizzare;

new_with_range(min, max, step)

E’ un costruttore “scorciatoia” che costruisce un Gtk.SpinButton numerico senza dover prima creare
un oggetto Adjustment.
La property “value” viene inizialmente settata al valore minimo, il page-increment viene settato
a 10*step ed la precisione dello spinbutton viene settata a “step”.
Parametri:
min: il minimo valore (float) disponibile nello spinbutton;
max: il massimo valore (float) disponibile nello spinbutton;
step: il valore (float) che aggiungiamo e sottraiamo quando
regoliamo lo spinbutton;

configure(adjustment, climb_rate, digits)

Modifica le properties dello spinbutton.
Parametri:
adjustment: l’oggetto Gtk.Adjustment che aggiornerà l’adjustment
esistente, o None per lasciarlo invariato;
climb_rate: il nuovo float che aggiorna il climb rate esistente
digits: il numero di decimali da visualizzare nello spinbutton;

get_adjustment()

Ritorna l’oggetto Gtk.Adjustment associato allo spinbutton.

get_digits()

Ritorna la “precisione” dello spinbutton, ovvero i decimali visualizzati dallo stesso.

get_increments()

Ritorna una namedtuple con lo “step” ed il “page-increment” correnti.

>>> spinbutton.get_increments()
(step=2.0, page=0.0)
>>> spinbutton.get_increments().step
2.0

get_numeric()

Ritorna True se solo i numeri possono essere digitati nello spinbutton.

get_range()

Ritorna una namedtuple con il range impostato sullo spinbutton:

>>> spinbutton.get_range()
(min=0.0, max=100.0)
>>> spinbutton.get_range().max
100.0

get_snap_to_ticks()

Ritorna True se i valori vengono “corretti” sullo step più vicino.

get_update_policy()

Ritorna l’oggetto Gtk.SpinButtonUpdatePolicy(value), ovvero la
policy update corrente, che definisce il comportamento dello spinbutton.
Questo Enum definisce se lo spinbutton debba visualizzare i valori anche se questi sono fuori dal
range consentito:
ALWAYS (0): al refresh dello spinbutton, il valore extra-range è ancora
visualizzato;
IF_VALID (1): al refresh dello spinbutton, il valore viene visualizzato solo se
interno al range impostato;

>>> spinbutton.get_update_policy()
<enum GTK_UPDATE_ALWAYS of type Gtk.SpinButtonUpdatePolicy>

get_value()

Ritorna il valore corrente dello spinbutton.

get_value_as_int()

Ritorna il valore corrente dello spinbutton come intero (int).

get_wrap()

Ritorna True se il wrap è attivo sullo spinbutton, ovvero il valore dello
spinbutton, quando si raggiunge uno dei due limiti, ricomincia da quello opposto (se eccede dal
massimo, ricomincia dal minimo e se scende sotto il minimo, ricomincia dal massimo).

set_adjustment(adjustment)

Setta l’oggetto Gtk.Adjustment sullo spin button, rimpiazzando quello esistente.
Parametri:
adjustment: il Gtk.Adjustment che rimpiazzerà quello corrente;

set_digits(digits)

Setta la precisione dello spinbutton
Parametri:
digits: un intero che indica quanti decimali utilizzare e
visualizzare nello spinbutton;

set_increments(step, page)

Setta lo step ed il page-increment dello spinbutton.
Parametri:
step: il float che indica di quanto incrementa/decrementa il valore
ad ogni click sulla freccia su/giù dello spinbutton
page: il float che indica il page-increment ad ogni pressione di
PagUp/PageDown;

set_numeric(numeric)

Setta il flag numeric che indica se è possibile digitare caratteri non numerici nella entry dello
spinbutton.
Parametri:
numeric: il flag che attiva (True) la digitazione di caratteri
non numerici nello spinbutton;

set_range(min, max)

Setta i valori minimo e massimo nello spinbutton.
Parametri:
min: il float che fissa il limite minimo;
max: il float che fissa il limite massimo;

set_snap_to_ticks(snap_to_ticks)

Setta la policy da usare quando un valore non è corretto.
Parametri:
snap_to_ticks: il flag che indica se correggere un valore non
valido (True);

set_update_policy(policy)

Setta la update policy dello spinbutton
Parametri:
policy: l’oggetto Gtk.SpinButtonUpdatePolicy che può assumere i
due valori ALWAYS e IF_VALID, ovvero visualizzare o meno un valore che eccede dai limiti impostati
per lo spinbutton;

set_value(value)

Setta il valore dello spinbutton
Parametri:
value: il nuovo valore (float) da settare e visualizzare nello
spinbutton;

set_wrap(wrap)

Setta il flag wrap per lo spin button, ovvero se il valore deve ricominciare dal limite opposto,
quando si eccede da uno dei due impostati.
Parametri:
wrap: il flag che setta il wrap per lo spinbutton (True);

spin(direction, increment)

Incrementa o decrementa lo spinbutton di una certa quantità, in una certa direzione.
Parametri:
direction: l’oggetto Gtk.SpinType
che indica in che direzione muovere il valore. L’enum spintype può assumere i seguenti valori:
STEP_FORWARD (0): incrementa dello step corrente;
STEP_BACKWARD (1): decrementa dello step corrente;
PAGE_FORWARD (2): incrementa di un page-increment corrente;
PAGE_BACKWARD (3): decrementa di un page-increment corrente;
HOME (4): va al valore minimo;
END (5): va al valore massimo;
USER_DEFINED (6): cambia di un valore specificato dall’utente;
increment: il float che indica lo step incrementale da applicare
nella direzione “direction”;

>>> spinbutton.get_value()
0.0
>>> spinbutton.spin(direction=Gtk.SpinType.STEP_FORWARD, increment=0.0)
>>> spinbutton.get_value()
2.0
>>> spinbutton.spin(direction=Gtk.SpinType.END, increment=0.0)
>>> spinbutton.get_value()
100.0
>>> spinbutton.spin(direction=Gtk.SpinType.STEP_BACKWARD, increment=0.0)
>>> spinbutton.get_value()
98.0
>>> spinbutton.spin(direction=Gtk.SpinType.HOME, increment=0.0)
>>> spinbutton.get_value()
0.0
>>> spinbutton.spin(direction=Gtk.SpinType.USER_DEFINED, increment=7.0)
>>> spinbutton.get_value()
7.0

update()

Forza manualmente l’aggiornamento dello spinbutton.
Di seguito un codice d’esempio:

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


class GWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title="SpinButton example")
        self.set_border_width(10)

        adjustment = Gtk.Adjustment(value=0, lower=0, upper=100,
                                    step_increment=2, page_increment=10,
                                    page_size=0)
        self.spinbutton = Gtk.SpinButton()
        self.spinbutton.set_adjustment(adjustment)
        self.spinbutton.set_wrap(True)
        check_numeric = Gtk.CheckButton(label="Numeric")
        check_ifvalid = Gtk.CheckButton(label="If Valid")
        # layout
        hbox = Gtk.Box(spacing=6)
        hbox.pack_start(self.spinbutton, False, False, 0)
        hbox.pack_start(check_ifvalid, False, False, 0)
        hbox.pack_start(check_numeric, False, False, 0)
        self.add(hbox)
        # bindings
        check_numeric.connect("toggled", self.on_numeric_toggled)
        check_ifvalid.connect("toggled", self.on_ifvalid_toggled)

    def on_numeric_toggled(self, button):
        self.spinbutton.set_numeric(button.get_active())

    def on_ifvalid_toggled(self, button):
        if button.get_active():
            policy = Gtk.SpinButtonUpdatePolicy.IF_VALID
        else:
            policy = Gtk.SpinButtonUpdatePolicy.ALWAYS
        self.spinbutton.set_update_policy(policy)


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 SpinButton