PyGObject: Gtk.IconView
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:
Commenti recenti