Home > Gtk3, PyGObject, python > PyGObject: Gtk.IconView

PyGObject: Gtk.IconView

13 Aprile 2020

torna all’indice appunti

IconView

Un Gtk.IconView è un widget che visualizza una collezione di icone in una vista a griglia.
Supporta il drag and drop, le selezioni multiple e il riordinamento degli elementi.
Come per il Gtk.TreeView, il Gtk.IconView utilizza un Gtk.ListStore come modello.
Invece di utilizzare i cell renderers, Gtk.IconView richiede che una delle sue colonne, nel
proprio Gtk.ListStore, contenga oggetti GdkPixbuf.Pixbuf.

Le properties principali sono:

Name Type Flags Short Description
activate-on-single-click bool r/w/en Attiva una row con single click
cell-area Gtk.CellArea r/w/co La Gtk.CellArea usata per il layout delle celle
column-spacing int r/w/en Spazio tra le colonne della griglia
columns int r/w/en Numero delle colonne da visualizzare
item-orientation Gtk.Orientation r/w/en Come sono posizionati testo e icona di ogni elemento
item-padding int r/w/en Padding tra gli elementi dell’icon view
item-width int r/w/en La larghezza usata per ogni elemento
markup-column int r/w/en La colonna del Model usata per il testo se usiamo Pango markup
model Gtk.TreeModel r/w Il model per l’icon view
pixbuf-column int r/w/en La colonna del Model usata per i pixbuf
reorderable bool r/w/en la View è riordinabile
row-spacing int r/w/en Spazio tra le righe della griglia
selection-mode Gtk.SelectionMode r/w/en Il selection mode
spacing int r/w/en Spazio tra le celle di un elemento
text-column int r/w/en La colonna del Model usata per il testo
tooltip-column int r/w/en La colonna nel model che contiene i testi dei tooltip per gli elementi

Segnali

I principali segnali di Gtk.IconView sono:

Name Short Description
activate-cursor-item Un keybinding signal emesso quando lo user attiva l’elemento in focus
item-activated Il segnale “item-activated” viene emesso quando chiamiamo il metodo Gtk.IconView.item_activated(), quando lo user fa doppio click
su un elemento con la property “activate-on-single-click” settata a False, o quando lo user clicca un elemento con property “activate-on-single-click” settata a True
move-cursor il segnale “move-cursor” è un keybinding signal emesso quando lo user muove il cursore
select-all Un keybinding signal emesso quando lo user seleziona tutti gli elementi
select-cursor-item Un keybinding signal emesso quando lo user seleziona l’elemento in focus
selection-changed Il segnale “selection-changed” viene emesso quando la selezione cambia
toggle-cursor-item Un keybinding signal emesso quando lo user cambia lo stato dell’elemento (toggle)
unselect-all Un keybinding signal emesso quando lo user deseleziona tutti gli elementi

Metodi

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

new()

Crea un nuovo widget Gtk.IconView.

>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
>>> iconview = Gtk.IconView.new()

new_with_area(area)

Crea un nuovo Gtk.IconView usando l’area specificata per il layout delle celle.
Parametri:
area: il Gtk.CellArea da usare per il layout delle celle;

new_with_model(model)

Crea un nuovo Gtk.IconView con il model passato come argomento.
Parametri:
model: il Gtk.TreeModel, ovvero il model dell’iconview;

convert_widget_to_bin_window_coords(wx, wy)

Converte le coordinate del widget in coordinate per la bin_window, come ci si aspetta, ad esempio,
da Gtk.IconView.get_path_at_pos().
Parametri:
wx: le coord. X relative al widget;
wy: le coord. Y relative al widget;

create_drag_icon(path)

Crea una rappresentazione cairo.Surface dell’elemento al percorso at path.
Questa immagine è usata per una drag icon.
Parametri:
path (Gtk.TreePath): un Gtk.TreePath nell’iconview;

enable_model_drag_dest(targets, actions)

Rende l’iconview un Drop Destination (drop) durante un DragAndDrop automatico.
La chiamata a questo metodo setta la property “reorderable” si Gtk.IconView a False.
Parametri:
targets: ([Gtk.TargetEntry]) – the table of targets that the drag will support
actions: (Gdk.DragAction) – the bitmask of possible actions for a drag to this widget

enable_model_drag_source(start_button_mask, targets, actions)

Rende l’iconview un drag source (drag) per il DragAndDrop automatico.
La chiamata a questo metodo setta la property “reorderable” si Gtk.IconView a False.
Parametri:
start_button_mask: il Gdk.ModifierType) cioè il mask dei buttons
abilitati ad iniziare il drag;
targets: il Gtk.TargetEntry, cioè la table dei targets che il
drag supporterà;
actions: la Gdk.DragAction, ovvero il bitmask delle possibili
azioni per il drag da questo widget;

get_activate_on_single_click()

Ritorna il settaggio effettuato con Gtk.IconView.set_activate_on_single_click(), ovvero
ritorna True se l’elemento viene attivato con single click.

get_cell_rect(path, cell)

Ritorna False se non c’è alcun elemento altrimenti True, inoltre ritorna il Gdk.Rectangle relativo
al path e cellrenderer passati come argomenti.
Parametri:
path: un Gtk.TreePath;
cell: un Gtk.CellRenderer o None;

get_column_spacing()

Ritorna il valore della spaziatura (property “column-spacing”) tra le colonne dell’iconview.

get_columns()

Ritorna il numero delle colonne (property “columns”).

get_cursor()

Ritorna un boolean, il percorso corrente del cursore e la cella corrente con il focus.
Il boolean sarà True se il cursore è settato, altrimenti False.
Se il cursore non è settato, il path ritornato sarà None. Se nessuna cella ha il focus, allora la
cella ritornata sarà None.

get_dest_item_at_pos(drag_x, drag_y)

Determina l’elemento di destinazione in base alla posizione data. Se non ci sono elementi alla
posizione data, ritorna None, altrimenti un tupla contenente il path dell’elemento e la posizione
di drop.
Parametri:
drag_x: la posizione X per determinare l’elemento di destinazione;
drag_y: la posizione Y per determinare l’elemento di destinazione;

get_drag_dest_item()

Ritorna le informazioni sull’elemento che è stato evidenziato durante il drag.
Le info sono il path dell’elemento evidenziato (Gtk.TreePath) e la posizione di drop
(Gtk.IconViewDropPosition)

get_item_at_pos(x, y)

Ritorna una tupla contenente il path (Gtk.TreePath) dell’elemento esistente alla posizione data e
il renderer responsabile della cella alla posizione data (Gtk.CellRenderer).
Se non esiste alcun elemento alla posizione data, ritorna None.
Il path ritornato è relativo alle coordinate di bin_window.
A differenza di Gtk.IconView.get_path_at_pos(), questo metodo ottiene anche la cella alla
posizione data.
Parametri:
x: La posizione X da identificare;
y: La posizione Y da identificare;

get_item_column(path)

Ritorna la colonna nella quale è visualizzato l’elemento con il path specificato.
Parametri:
path: il Gtk.TreePath dell’elemento;

get_item_orientation()

Ritorna la posizione dei testi relativamente alla icone (property “item-orientation”).

get_item_padding()

Ritorna il padding intorno agli elementi (property “item-padding”).

get_item_row(path)

Ritorna la riga nella quale è visualizzato l’elemento con il path specificato.
Parametri:
path: il Gtk.TreePath dell’elemento;

get_item_width()

Ritorna la larghezza del singolo elemento (property “item-width”).

get_margin()

Ritorna il valore dello spazio (property “margin”) lasciato ai bordi (top, bottom, left, right)
dell’iconview.

get_markup_column()

Ritorna la colonna dedicata al markup o -1 se non è settata.

get_model()

Ritorna il model (Gtk.TreeModel) su cui si basa il Gtk.IconView.

get_path_at_pos(x, y)

Ritorna il Gtk.TreePath corrispondente all’icona esistente alla posizione data, o None.
Il path trovato è relativo alle coordinate di bin_window. Vedere Gtk.IconView.get_item_at_pos(),
se si è interessati anche alla cella presente alla posizione data.
Vedere Gtk.IconView.convert_widget_to_bin_window_coords() per la conversione di coordinate widget
in coordinate bin_window.
Parametri:
x: La posizione X da identificare;
y: La posizione Y da identificare;

get_pixbuf_column()

Ritorna la colonna dedicata ai Pixbufs o -1 se non è stata settata.

get_reorderable()

Ritorna True se la lista può essere riordinata. Vedere Gtk.IconView.set_reorderable().

get_row_spacing()

Ritorna il valore della spaziatura (property “row-spacing”) tra righe dell’iconview.

get_selected_items()

Ritorna la lista (GLib.List) con i paths (Gtk.TreePath) di tutti gli elementi selezionati.

get_selection_mode()

Ritorna il selection mode (Gtk.SelectionMode) dell’iconview.

get_spacing()

Ritorna il valore della spaziatura (property “spacing”) tra le celle di un elemento,
ad esempio lo spazio che c’è tra l’icona e il testo.

get_text_column()

Ritorna la colonna dedicata al testo o -1 se non è stata settata.

get_tooltip_column()

Ritorna la colonna dedicata al tooltip delle righe dell’iconview o -1 se non è stata settata.

get_tooltip_context(x, y, keyboard_tip)

Ritorna un boolean che indica se il tooltip dato punta ad un elemento, la coordinata X,
la coordinata Y, il model (Gtk.TreeModel), il path (Gtk.TreePath), l’iter(Gtk.TreeIter).
I valori x, y e keyboard_tip che sono ricevuti nel signal handler, devono essere passati a
questo metodo. In pratica il valore ritornato indica se esiste un elemento dell’iconview alle
coordinate date (True) o meno (False) per i mouse tooltips.
Per i keyboard tooltips l’elemento ritornato sarà l’elemento del cursore.
Parametri:
x: la coordinata X relativa alle coordinate del widget;
y: la coordinata Y relativa alle coordinate del widget;
keyboard_tip: True se è un keyboard tooltip altrimenti False;

get_visible_range()

Ritorna None se non c’è un range visible, oppure una tupla contenente: l’inizio della regione,
la fine della regione: (start_path: Gtk.TreePath, end_path: Gtk.TreePath).

item_activated(path)

Attiva l’elemento determinato dal path passato come argomento.
Parametri:
path: il Gtk.TreePath dell’elemento da attivare;

path_is_selected(path)

Ritorna True se l’icona a cui punta il path è selezionata.
Se il path non punta ad una posizione valida, viene ritornato False.
Parametri:
path: il Gtk.TreePath da controllare;

scroll_to_path(path, use_align, row_align, col_align)

Parametri:

path: (Gtk.TreePath) – The path of the item to move to.
use_align: (bool) – whether to use alignment arguments, or False.
row_align: (float) – The vertical alignment of the item specified by path.
col_align: (float) – The horizontal alignment of the item specified by path.

Muove gli alignments dell’iconview alla posizione specificata da path.
row_align determina dove la row è posizionata, e col_align determina la colonna.
Entrambe richiedono valori tar 0.0 e 1.0, dove 0.0 sta per left/top alignment, 1.0 sta per
right/bottom alignment, 0.5 sta per centrato.
Se use_align è False, gli argomenti alignment vengono ignorati, e il tree richiederà un lavoro
minimo per scorrere l’elemento. Se l’elemento è già visibile a schermo, non succederà nulla.
Questo metodo funziona solo se è settato un model e path è una riga valida del model.
Se il model cambia prima che l’iconview venga generato, il path centrato, verrà modificato
per essere coerente con la modifica del model.

select_all()

Seleziona tutte le icone.

select_path(path)

Seleziona la riga con il path passato come argomento.
Parametri:
path: il Gtk.TreePath da cui selezionare la riga;

selected_foreach(func, *data)

Chiama una funzione per ogni icona selezionata. Il model non può essere modificato all’interno
di questa funzione.
Parametri:
func: la Gtk.IconViewForeachFunc, ovvero la funzione da chiamare
per ogni icona selezionata;
data: i dati da passare alla funzione;

set_activate_on_single_click(single)

Causa l’emissionde del segnale “item-activated” con un single click invece che con doppio click.
Parametri:
single: il boolean che settato a True emette un segnale
“item-activated” su un single click;

set_column_spacing(column_spacing)

Setta la property “column-spacing” che specifica la spaziatura tra le colonne dell’iconview.
Parametri:
column_spacing: il valore della spaziatura tra colonne;

set_columns(columns)

Setta la property “columns” che determina quante colonne sono presenti nell’iconview.
Se columns è -1, il numero di colonne sarà scelto automaticamente per riempire l’area disponibile.
Parametri:
columns: il numero di colonne presenti nell’iconview;

set_cursor(path, cell, start_editing)

Setta il corrente keyboard focus a path, e lo seleziona.
Questo è comodo quando vogliamo richiamare l’attenzione dell’utente mettendo il focus su
un determinato elemento. Se cell non è None, il focus viene dato alla cella stessa.
Se start_editing è True, l’editing verrà iniziato nella cella specificata.
Parametri:
path: il Gtk.TreePath o None;
cell: il Gtk.CellRenderer o None;
start_editing: True se la cella specificata deve essere editata;

set_drag_dest_item(path, pos)

Setta l’elemento che viene evidenziato per il feedback.
Parametri:
path: il Gtk.TreePath (o None) dell’elemento da evidenziare;
pos: il Gtk.IconViewDropPosition che specifica dove eseguire il
drop, relativo all’elemento;

set_item_orientation(orientation)

Setta la property “item-orientation” che determina se le label sono disegnate a fianco delle
icone, invece che sotto.
Parametri:
orientation: il Gtk.Orientation ovvero la posizione dei testi
rispetto alle icone. Il valore dell’enum Gtk.Orientation può essere Gtk.Orientation.VERTICAL e
Gtk.Orientation.HORIZONTAL;

set_item_padding(item_padding)

Setta la property di Gtk.IconView “item-padding” che specifica il padding attorna ad ogni elemento
dell’iconview.
Parametri:
item_padding: il padding attorno ad ogni elemento;

set_item_width(item_width)

Setta la property “item-width” che specifica la larghezza da usare per ogni elemento.
Se viene settata a -1, l’iconview determinerà automaticamente la dimensione più adatta.
Parametri:
item_width: la larghezza di ogni elemento;

set_margin(margin)

Setta la property “margin” che specifica lo spazio inserito ai bordi (top, bottom, left, right)
dell’iconview.
Parametri:
margin: il valore del margine da settare;

set_markup_column(column)

Setta la colonna con le info di markup per l’iconview. La colonna di markup deve essere di tipo
GObject.TYPE_STRING.
Parametri:
column: l’indice della colonna da settare o -1 per non
visualizzare il markup text;

set_model(model)

Setta il model del Gtk.IconView. Se l’iconview ha già un model settato, questo verrà rimosso prima
di settare il model nuovo. Se model è None, allora verrà rimosso il vecchio model.
Parametri:
model: il Gtk.TreeModel (o None) dell’iconview;

set_pixbuf_column(column)

Parametri:
column: l’indice della colonna da settare per i pixbufs o -1
per disabilitarla;

Setta la colonna con i pixbufs

set_reorderable(reorderable)

Parametri:
reorderable: True se la lista di elementi può essere riordinata;

Questo metodo permette di riordinare models che supportano Gtk.TreeDragSourceIface e
Gtk.TreeDragDestIface. Sia Gtk.TreeStore che Gtk.ListStore supportano questa funzionalità.
Se reorderable è True, lo user può riordinare il model facendo drag and drop con le righe.
E’ possibile intercettare tali cambiamenti collegando i segnali del model “row_inserted” e
“row_deleted”. Il riordinamento è implementato settando l’iconview come drag source
e destination.

set_row_spacing(row_spacing)

Setta la property “row-spacing” che specifica la spaziatura tra le righe dell’iconview.
Parametri:
row_spacing: il valore della spaziatura tra le righe;

set_selection_mode(mode)

Setta il selection mode dell’iconview. I valori dell’enum Gtk.SelectionMode possono assumere i
seguenti valori:
NONE (0): nessuna selezione è possibile;
SINGLE (1): nessuno o un elemento solo può essere selezionato;
BROWSE (2): esattamente un elemento può essere selezionato;
MULTIPLE (3): può essere selezionato qualsiasi numero di elementi;
Parametri:
mode: il Gtk.SelectionMode dell’iconview.

set_spacing(spacing)

Setta la property “spacing” che specifica la spaziatura presente tra le celle di un elemento
(ad esempio tra icona e testo).
Parametri:
spacing: il valore della spaziatura tra le celle di un elemento;

set_text_column(column)

Setta la colonna con il testo, e deve essere di tipo GObject.TYPE_STRING.
Parametri:
column: l’indice della colonna del model con il testo o -1 per
non visualizzare il testo;

set_tooltip_cell(tooltip, path, cell)

Setta la tip area del tooltip. Vedere anche Gtk.Tooltip.set_tip_area() o, per una semplice
alternativa, Gtk.IconView.set_tooltip_column().
Parametri:
tooltip: il Gtk.Tooltip da settare;
path: il Gtk.TreePath;
cell: il Gtk.CellRenderer (o None) su cui settare il tooltip;

set_tooltip_column(column)

Se vogliamo avere tooltips semplici (solo testo) a pieno elemento, possiamo usare questo metodo
per far gestire i tooltip automaticamente dal Gtk.IconView.
column deve essere settata alla colonna del model che contiene i testi dei tooltipis, o -1 per
disabilitare questo aspetto. Quando abilitato, la property “has-tooltip” di Gtk.Widget sarà
settata a True e l’iconview sarà connesso all’handler del segnale “query-tooltip” di Gtk.Widget.
Nota: l’handler di segnale setta il testo con il metodo Gtk.Tooltip.set_markup(), così facendo
è necessario l’escape dei caratteri quali &, <. Parametri:
column: l’indice della colonna per i tooltips;

set_tooltip_item(tooltip, path)

Setta la tip area del tooltip per essere coperta dall’elemento con percorso path.
Vedere anche Gtk.IconView.set_tooltip_column() per una semplice alternativa, o
Gtk.Tooltip.set_tip_area().
Parametri:
tooltip: il Gtk.Tooltip;
path: il Gtk.TreePath dell’elemento che coprirà il tooltip;

unselect_all()

Deseleziona tutte le icone.

unselect_path(path)

Deseleziona la riga di percorso path.
Parametri:
path: il Gtk.TreePath della row da deselezionare;

unset_model_drag_dest()

Annulla l’effetto di Gtk.IconView.enable_model_drag_dest().
La chiamata a questo metodo setta la property “reorderable” a False.

unset_model_drag_source()

Annulla l’effetto di Gtk.IconView.enable_model_drag_source().
La chiamata a questo metodo setta la property “reorderable” a False.

Di seguito un codice di esempio:

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


class GWindow(Gtk.Window):
  def __init__(self):
    super().__init__(title="IconView example")
    self.set_default_size(150, 200)
    icons = ["edit-cut", "edit-paste", "edit-copy"]
    model = Gtk.ListStore(Pixbuf, str)
    iconview = Gtk.IconView.new()
    iconview.set_model(model)
    iconview.set_pixbuf_column(0)
    iconview.set_text_column(1)
    iconview.set_item_orientation(Gtk.Orientation.HORIZONTAL)
    iconview.set_reorderable(True)

    for icon in icons:
        pixbuf = Gtk.IconTheme.get_default().load_icon(icon, 64, 0)
        model.append([pixbuf, icon.split("-")[1]])

    self.add(iconview)


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 IconView

Categorie:Gtk3, PyGObject, python Tag: , ,
I commenti sono chiusi.