bancaldo™

torna all’indice appunti

FlowBox

Il widget Gtk.FlowBox è un widget contenitore che posiziona i child widgets in
sequenza, a seconda dell’orientamento definito.
Ad esempio, se viene settato un orientamento orizzontale, i child widgets verranno posizionati da
sinistra verso destra e, se necessario, verrà iniziata una nuova riga sotto quella precedente
(ad esempio riducendo la larghezza della finestra).
Alla stessa maniera, settando un orientamento verticale, i child widgets verranno arrangiati
dall’alto verso il basso, aggiungendo nuove colonne, qualora fosse necessario (ad esempio
riducendo l’altezza della finestra).
I child widgets di un Gtk.FlowBox possono essere dinamicamente ordinati e filtrati.
Nonostante sia consigliato che un Gtk.FlowBox abbia solo child di tipo Gtk.FlowBoxChild,
è possibile aggiungere ogni tipo di widget, utilizzando il metodo ereditato dalla classe
Gtk.Container, dalla quale Gtk.FlowBox deriva, cioè Gtk.Container.add().
Nota:
La gestione delle dimensioni del widget Gtk.FlowBox non è come ci si aspetta, volendo quindi
ridurle sia orizzontalmente, che verticalmente, richiede l’utilizzo di un widget Gtk.ScrolledWindow
che ne abiliti queste funzionalità.

Le properties principali sono:

Name	Type	Flags	Short Description
activate-on-single-click	bool	r/w/en	Se la riga è attivabile con un singolo click
column-spacing	int	r/w/en	La quantità di spazio orizzontale tra 2 children
homogeneous	bool	r/w/en	Se i children saranno di dimensioni omogenee
max-children-per-line	int	r/w/en	Il numero massimo di children allocabili consecutivamente rispetto all’orientamento settato
min-children-per-line	int	r/w/en	Il minimo numero di children allocabili consecutivamente rispetto all’orientamento settato
row-spacing	int	r/w/en	La quantità di spazio verticale tra 2 children
selection-mode	Gtk.SelectionMode	r/w/en	Il tipo di selection mode

Segnali

Sono i segnali ereditati principalmente da Gtk.Container:

Name	Short Description
activate-cursor-child	Il segnale “activate-cursor-child” viene emesso quando il box viene attivato
child-activated	il segnale “child-activated” viene emesso quando viene attivato un child
select-all	Il segnale “select-all” viene emesso quando tutti i children del box vengono selezionati, se selection-mode lo permette
selected-children-changed	Il segnale “selected-children-changed” viene emesso quando il set di children selezionati cambia
unselect-all	Il segnale “unselect-all” viene emesso quando tutti i children del box vengono deselezionati

Metodi

Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.FlowBox, i principali
metodi sono:

new()

Metodo costruttore che crea un nuovo widget Gtk.FlowBox.

bind_model(model, create_widget_func, *user_data)

Lega un model al flowbox. Se il flowbox è già legato ad un model, il precedente legame viene
distrutto, il contenuto del flowbox azzerato e viene ripopolato con i widget che rappresentano
gli elementi del nuovo model.
Ogni volta che il model cambiam il flowbox viene aggiornato. Se model è None,
il flowbox risulta vuoto.
Se un flowbox è lagato ad un model, aggiungere widget direttamente con i metodi Gtk.FlowBox.insert()
e Gtk.Container.add()) darà risultati indefiniti.
Nota:
Se si lega il flowbox ad un model, le funzionalità di filtering e di sorting di Gtk.FlowBox non
funzioneranno, poichè dovranno essere implementate direttamente sul model.
Parametri:
model: un oggetto Gio.ListModel a cui legare il flowbox;
create_widget_func: una funzione che crea gli elementi (widgets);
user_data: i dati utente da passare alla funzione create_widget_func;

get_activate_on_single_click()

Ritorna True se i children si attivano con un click singolo.

get_child_at_index(idx)

Ritorna il child (Gtk.FlowBoxChild) alla posizione data.
Parametri:
idx la posizione del child desiderato;

get_child_at_pos(x, y)

Ritorna il child (Gtk.FlowBoxChild) alle coordinate date, o None in caso a quelle
coordinate, non ci siano widgets.
Parametri:
x: la coordinata x del widget child;
y: la coordinata y del widget child;

get_column_spacing()

Ritorna lo spazio orizzontale utilizzato per distanziare i child widget.

get_homogeneous()

Ritorna True se il box è omogeneo, ovvero i widgets hanno tutti le stesse dimensioni.

get_max_children_per_line()

Ritorna il massimo numero di children ammessi per riga/colonna.

get_min_children_per_line()

Ritorna il minimo numero di children ammessi per riga/colonna.

get_row_spacing()

Ritorna lo spazio verticale dedicato al distanziamento delle righe.

get_selected_children()

Crea una lista di tutti i children (Gtk.FlowBoxChild) selezionati.

get_selection_mode()

Ritorna il tipo di selection-mode (Gtk.SelectionMode) impostato sul flowbox.

insert(widget, position)

Inserisce un widget (Gtk.Widget) nel flowbox, alla posizione desiderata.
Se un funzione di ordinamento è stata settata, il widget sarà inserito comunque alla posizione
desiderata. Se position=-1, o maggiore del numero totale di children presenti nel flowbox,
il widget sarà inserito alla fine.
Parametri:
widget: il child (Gtk.Widget) da aggiungere;
position: la posizione dove vogliamo aggiungere il child;

invalidate_filter()

Aggiorna il filtering per tutti i children.
Chiamare questa funzione quando il risultato della funzione di filter è cambiata a causa di
fattori esterni, ad esempio quando la funzione di filter ha appena cercato dei risultati e il
testo della entry, con il quale filtriamo i risultati, cambia.

invalidate_sort()

Aggiorna il sorting per tutti i children.
Chiamare questa funzione quando il risultato della funzione di sort (ordinamento) è cambiata
a causa di fattori esterni

select_all()

Seleziona tutti i children del flowbox, se il selection mode lo permette.

select_child(child)

Seleziona un singolo child del flowbox, se il selection mode lo permette.
Parametri:
child: il child (Gtk.FlowBoxChild) che vogliamo selezionare;

selected_foreach(func, *data)

Chiama una funzione per ogni child selezionato. All’interno di questa funzione, la selezione non
può essere modificata.
Parametri:
func: la funzione (Gtk.FlowBoxForeachFunc) da chiamare per ogni
child selezionato;
data: i dati da passare alla funzione;

set_activate_on_single_click(single)

Se single è True i children verranno attivati con in click singolo.
Parametri:
single: un boolean che settato a True, permette
di selezionare un child con click singolo;

set_column_spacing(spacing)

Setta lo spazio orizzontale da aggiungere tra i children.
Vedere la property “column-spacing” di Gtk.FlowBox.
Parametri:
spacing: il valore dello spacing orizzontale da usare tra i children;

set_filter_func(filter_func, *user_data)

Settando una funzione di filter nel flowbox possiamo decidere dinamicamente quali children
mostrare, ad esempio con una funzione di ricerca, mostrare solo quei children che contengono i
termini di ricerca. La funzione di filter filter_func sarà chiamata per ogni child, e verrà
chiamata ogni volta che un child cambia, grazie al metodo Gtk.FlowBoxChild.changed(),
o quando viene chiamato il metodo Gtk.FlowBox.invalidate_filter().
Nota: utilizzare una funzione di filter è incompatibile con l’utilizzo di un
model (vedi Gtk.FlowBox.bind_model()).
Parametri:
filter_func: la callback (Gtk.FlowBoxFilterFunc) che filtra i
children da visualizzare;
user_data: i dati da passare alla funzione di filter filter_func;

set_hadjustment(adjustment)

Collega un adjustment per la gestione del focus nel flowbox.
L’adjustment è anche usato per l’autoscrolling durante una selezione “rubberband”.
Vedere Gtk.ScrolledWindow.get_hadjustment() per un esempio tipico di come
ottenere un adjustment, e Gtk.FlowBox.set_vadjustment() per il settaggio
dell’adjustment verticale. L’adjustments deve essere in pixel e nello stesso sistema di coordinate
usato per l’allocazione dei children.
Parametri:
adjustment: l’adjustment (Gtk.Adjustment) da utilizzare quando il
focus si sposta tra i discendenti del contenitore;

set_homogeneous(homogeneous)

Setta la property “homogeneous” del Gtk.FlowBox per garantire, o meno, che a tutti i children
del flowbox venga garantito lo stesso spazio.
Parametri:
homogeneous: il boolean che settato a True crea
lo stesso alloggiamento per ogni child;

set_max_children_per_line(n_children)

Setta il massimo numero di children da allocare in linea, in accordo con l’orientamento del flowbox.
Parametri:
n_children: il massimo numero di children per linea;

set_min_children_per_line(n_children)

Setta il minimo numero di children da allocare in linea, in accordo con l’orientamento del flowbox.
Parametri:
n_children: il minimo numero di children per linea;

set_row_spacing(spacing)

Setta lo spazio verticale da aggiungere tra i children, modificando la property “row-spacing”
del flowbox.
Parametri:
spacing: lo spazio da aggiungere verticalmente tra i children;

set_selection_mode(mode)

Setta il tipo di selection mode nel flowbox.
Parametri:
mode: il selection-mode (Gtk.SelectionMode) da utilizzare;

set_sort_func(sort_func, *user_data)

Settando una funzione di sort (ordinamento) nel flowbox possiamo decidere dinamicamente di
riordinare i children. La funzione di sort sort_func sarà chiamata per ogni child, e verrà
chiamata ogni volta che un child cambia, grazie al metodo Gtk.FlowBoxChild.changed(),
o quando viene chiamato il metodo Gtk.FlowBox.invalidate_sortr().
Nota: utilizzare una funzione di sort è incompatibile con l’utilizzo di un
model (vedi Gtk.FlowBox.bind_model()).
Parametri:
sort_func: la callback (Gtk.FlowBoxFilterFunc) che ordina i children;
user_data: i dati da passare alla funzione di sort sort_func;

set_vadjustment(adjustment)

Collega un adjustment per la gestione del focus nel flowbox.
L’adjustment è anche usato per l’autoscrolling durante una selezione “rubberband”.
Vedere Gtk.ScrolledWindow.get_vadjustment() per un esempio tipico di come
ottenere un adjustment, e Gtk.FlowBox.set_hadjustment() per il settaggio
dell’adjustment orizzontale. L’adjustments deve essere in pixel e nello stesso sistema di
coordinate usato per l’allocazione dei children.
Parametri:
adjustment: l’adjustment (Gtk.Adjustment) da utilizzare quando il
focus si sposta tra i discendenti del contenitore;

unselect_all()

Deseleziona tutti i children del flowbox.

unselect_child(child)

Deseleziona il child passato come argomento.
Parametri:
child: il child (Gtk.FlowBoxChild) del flowbox che vogliamo
selezionare;

FlowBoxChild

Come abbiamo visto, i child di un widget Gtk.FlowBox, sono delle istanze della classe Gtk.FlowBoxChild.
Sono anche essi dei contenitori di widget.

le Properties sono ereditate dal widget Gtk.Container.
Il segnale a cui connettersi è

Name	Short Description
activate	Il segnale “activate” viene emesso quando il child nel Gtk.FlowBox viene attivato (click, doppio click, Spazio, o tasto Enter)

I metodi principali sono:

new()

Crea un nuovo widget Gtk.FlowBoxChild, da usare come child di un widget Gtk.FlowBox.

>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk, Gdk
>>> flowboxchild = Gtk.FlowBoxChild.new()

add(child)

Metodo ereditato dalla classe Gtk.Container,
dalla quale Gtk.FlowBoxChild deriva. Aggiunge un widget al contenitore FlowBoxChild.
Parametri:
child: il widget da aggiungere al flowboxchild;

>>> label = Gtk.Label(label="label 0")
>>> flowboxchild.add(label)

changed()

Setta il child (Gtk.FlowBoxChild) come “changed”. Questo cambio di stato ha effetto sulle
eventuali funzioni di sort e filter.

get_child

Metodo ereditato dalle classi genitore, che ritorna il widget con il quale abbiamo creato
il widget Gtk.FlowBoxChild.

>>> flowboxchild.get_child().get_label()
'label 0'

get_index()

Ritorna l’indice del flowboxchild o -1 se il flowbox non risiede in un flowbox.

>>> flowboxchild.get_index()
-1
>>> flowbox = Gtk.FlowBox.new()
>>> flowbox.add(flowboxchild)
>>> flowboxchild.get_index()
0

is_selected()

Ritorna True se il flowboxchild risulta selezionato nel flowbox.

Di seguito un codice di esempio:

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


class GWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title="FlowBox Demo")
        self.set_border_width(10)
        self.set_default_size(300, 250)
        # Header
        header = Gtk.HeaderBar(title="FlowBox example")
        header.set_subtitle("Labels")
        header.props.show_close_button = True
        self.set_titlebar(header)

        scrolled = Gtk.ScrolledWindow()
        # define the scrollbar visibility
        scrolled.set_policy(hscrollbar_policy=Gtk.PolicyType.NEVER,
                            vscrollbar_policy=Gtk.PolicyType.AUTOMATIC)
        flowbox = Gtk.FlowBox.new()
        flowbox.set_selection_mode(Gtk.SelectionMode.SINGLE)
        flowbox.set_valign(Gtk.Align.START)
        flowbox.set_max_children_per_line(3)

        for char in 'abcdefghjklm':
            button = Gtk.Button(label=char)
            flowbox.add(button)

        scrolled.add(flowbox)
        self.add(scrolled)

        flowbox.connect("selected-children-changed", self.on_child_select)

    def on_child_select(self, flowbox):
        selected = [child for child in flowbox.get_selected_children()
                    if child.is_selected()]
        if selected:
            for s_child in selected:
                label = s_child.get_child().get_label()
                print("INFO: child <{}> at position <{}> selected!".format(
                      label, s_child.get_index()))


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 FlowBox