Archivio
PyGObject: Gtk.MessageDialog
torna all’indice degli appunti
MessageDialog
Il widget Gtk.message dialog è un widget che visualizza una finestra di dialog con un testo e all’occorrenza dei bottoni di scelta.
La differenza tra Gtk.message dialog e Gtk.Dialog è che nel primo, viene settata a True la property “:skip-taskbar-hint”, che permette di
nascondere il dialog all task-bar.
Il metodo migliore per utilizzare un dialog, è chiamarne il metodo run() che rende il dialog modal.
In sostanza modal significa che il dialog diventa automaticamente figlio della top-level window principale dalla quale lo abbiamo
generato e attende fino a che l’utente non interagisce con esso (es. cliccando un Button), per poi tornare alla window parent che l’ha generato.
Per creare un message dialog si utilizza il costruttore Gtk.message dialog(*args, **kwargs).
Le properties principali dell’oggetto MessageDialog sono:
“buttons”: I bottoni (Gtk.ButtonsType) visualizzati nel dialog;
“message-area”: il widget Gtk.Box che gestisce le labels primaria e secondaria;
“message-type”: l’oggetto Gtk.MessageType che definisce il tipo di oggetto;
“secondary-text”: il messaggio secondario del dialog;
“secondary-use-markup”: il boolean che, settato a True, permette di includere il Pango markup;
“text”: il testo principale del dialog;
“use-markup”: il boolean che, settato a True, permette di includere il Pango markup;
>>> import gi
>>> gi.require_version('Gtk', '3.0')
>>> from gi.repository import Gtk, GLib, Gdk
>>> dialog = Gtk.message dialog(parent=None, use_markup=False, message_type=Gtk.MessageType.INFO,
... buttons=Gtk.ButtonsType.OK, text="This is an INFO message dialog")
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):
A differenza di altri widget, però, le properties leggibili, sono limitate, poichè i flags settati per queste, non permettono la lettura/scrittura:
>>> for p in dialog.props:
... if p.flags == 227:
... print(p)
...
<GParamString 'name'>
<GParamObject 'parent'>
<GParamBoolean 'is-focus'>
<GParamString 'tooltip-markup'>
<GParamString 'tooltip-text'>
<GParamInt 'margin'>
<GParamBoolean 'expand'>
<GParamString 'title'>
<GParamString 'role'>
<GParamString 'text'>
<GParamString 'secondary-text'>
>>> dialog.get_property("text")
'This is an INFO message dialog'
oppure con i metodi getter e setter specifici get_() e set_(value):
>>> dialog.set_tooltip_text("Tooltip text")
>>> dialog.get_tooltip_text()
'Tooltip text'
Quindi è bene settare le properties non accessibili, in fase di costruzione!
Metodi
Di seguito i metodi utilizzabili con il widget Gtk.message dialog:
format_secondary_markup(message_format)
Setta il testo secondario del message dialog che verrà formattato con il Pango text markup language.
Questa funzione non esegue l’escape di caratteri XML speciali.
“str”: la stringa in formato markup;
format_secondary_text(message_format)
Setta il testo secondario del message dialog.
get_message_area()
Ritorna un oggetto Gtk.Box corrispondente all’area dedicata dal message dialog, al testo
set_markup(str)
Setta il testo principale del message dialog che verrà formattato con il Pango text markup language.
“str”: la stringa in formato markup;
Tipi di MessageDialog
I tipi di MessageDialog sono definiti dall’Enum message_type che passiamo in fase di costruzione.
Questo Enum è di tipo Gtk.MessageType e può
assumere i seguenti valori:
INFO (0): Messaggio informativo semplice, di solito corredato da un Button OK.
WARNING (1): Messaggio di avviso;
QUESTION (2): Messaggio di scelta, con bottoni YES/NO;
ERROR (3): Messaggio di errore;
OTHER (4): Nessuna delle precedenti. E’ un messaggio personalizzabile;
Image
Settare un’immagine nel message dialog è molto semplice e ci sono più modi.
Creiamo un oggetto Gtk.Image con il classmethod Gtk.Image.new_from_file, lo rendiamo visibile con
il metodo show() e lo settiamo in fase di costruzione dell’oggetto Gtk.MessageDialog con la property “image”.
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="MessageDialog Example")
button1 = Gtk.Button(label="Information")
button2 = Gtk.Button(label="Error")
button3 = Gtk.Button(label="Warning")
button4 = Gtk.Button(label="Question")
# Bindings
button1.connect("clicked", self.on_info_clicked)
button2.connect("clicked", self.on_error_clicked)
button4.connect("clicked", self.on_question_clicked)
button3.connect("clicked", self.on_warning_clicked)
# Layout
box = Gtk.Box(spacing=6)
box.add(button1)
box.add(button2)
box.add(button3)
box.add(button4)
self.add(box)
def on_info_clicked(self, widget):
image = Gtk.Image.new_from_file("info.png")
image.show()
dialog = Gtk.MessageDialog(parent=self, use_markup=False, title="Info",
message_type=Gtk.MessageType.INFO,
buttons=Gtk.ButtonsType.OK, image=image,
text="Primary Message Text")
dialog.format_secondary_text("secondary text that explains things")
dialog.run() # Return when user click dialog buttons
dialog.destroy()
def on_error_clicked(self, widget):
image = Gtk.Image.new_from_file("error.png")
image.show()
dialog = Gtk.MessageDialog(parent=self, use_markup=True, title="Error",
message_type=Gtk.MessageType.ERROR,
buttons=Gtk.ButtonsType.CANCEL, image=image,
text='<span foreground="red" weight="bold">'
'Primary Error Message Text</span>')
dialog.format_secondary_text("secondary text that explains things")
dialog.run()
dialog.destroy()
def on_warning_clicked(self, widget):
image = Gtk.Image.new_from_file("warning.png")
image.show()
dialog = Gtk.MessageDialog(parent=self, use_markup=True,
title="Warning", image=image,
message_type=Gtk.MessageType.WARNING,
buttons=Gtk.ButtonsType.OK_CANCEL,
text='<span foreground="blue" weight="bold">'
'Primary Warning Message Text</span>')
dialog.format_secondary_text("secondary text that explains things")
response = dialog.run()
if response == Gtk.ResponseType.OK:
print("WARNING: dialog closed by clicking OK button")
elif response == Gtk.ResponseType.CANCEL:
print("WARNING: dialog closed by clicking CANCEL button")
dialog.destroy()
def on_question_clicked(self, widget):
image = Gtk.Image.new_from_file("question.png")
image.show()
dialog = Gtk.MessageDialog(parent=self, use_markup=False,
title="Question",
message_type=Gtk.MessageType.QUESTION,
buttons=Gtk.ButtonsType.YES_NO,
text="This is an QUESTION MessageDialog")
dialog.format_secondary_text("secondary text that explains things")
response = dialog.run()
if response == Gtk.ResponseType.YES:
print("INFO: dialog closed by clicking YES button")
elif response == Gtk.ResponseType.NO:
print("INFO: dialog closed by clicking NO button")
dialog.destroy()
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
Custom Dialog
Se nessuno dei dialogs disponibili soddisfa le nostre esigenze, possiamo sempre crearne uno personalizzato utilizzando la classe
Gtk.Dialog.
Ad esempio vogliamo inserire all’interno una entry per digitare un valore e recuperarlo, vogliamo mettere una o più labels e l’icona preferita…
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
class CustomDialog(Gtk.Dialog):
def __init__(self, parent):
super().__init__(title="Custom Dialog", parent=parent)
self.result = None
self.add_buttons(Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL,
Gtk.STOCK_OK, Gtk.ResponseType.OK)
self.set_default_size(250, 100)
image = Gtk.Image.new_from_file("warning.png")
image.show()
label = Gtk.Label(label="Enter new value")
self.entry = Gtk.Entry()
box = self.get_content_area()
box.set_spacing(15)
box.add(image)
box.add(label)
box.add(self.entry)
self.show_all()
# bindings
self.connect("response", self.on_response) # get the entry value
def on_response(self, widget, response_id):
self.result = self.entry.get_text()
def get_result(self):
return self.result
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Custom Dialog Example")
self.set_border_width(6)
button = Gtk.Button(label="Open dialog")
button.connect("clicked", self.on_button_clicked)
self.add(button)
def on_button_clicked(self, widget):
dialog = CustomDialog(parent=self)
response = dialog.run()
if response == Gtk.ResponseType.OK:
print("INFO: The OK button was clicked with result %s" %
dialog.get_result())
elif response == Gtk.ResponseType.CANCEL:
print("INFO: The Cancel button was clicked")
dialog.destroy()
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
Nota:
connettere il dialog al segnale response, ci permettere di assegnare il valore della entry nella nostra variabile, che
poi possiamo recuperare all’occorrenza con il getter.
link di riferimento:
PyGObject: Gtk.Builder
torna all’indice degli appunti
Builder
Un Gtk.Builder è un oggetto che legge una descrizione testuale di una UI e ne istanzia gli
oggetti, in essa descritti.
Per creare un Gtk.Builder da una descrizione testuale, si utilizza il metodo
Gtk.Builder.new_from_file(), se la stringa che descrive la UserInterface è
contenuta in un file, oppure Gtk.Builder.new_from_resource(), oppure
Gtk.Builder.new_from_string() se abbiamo un’unica stringa descrittiva.
Il Gtk.Builder tiene un riferimento di tutti gli oggetti che crea fino a che non finalizza la UI.
Le funzioni Gtk.Builder.get_object() e Gtk.Builder.get_objects()
vengono usate per accedere ai widgets della UI, grazie ai nomi assegnati ad essi all’interno della
descrizione testuale della UI.
Le Toplevel windows ritornate da queste funzioni rimarranno “vive” fino a chè l’utente non le
distruggerà esplicitamente con il metodo Gtk.Widget.destroy().
Se la UI definition viene inserita in un file, è convenzione dara a tale file, estensione “.ui”
Faremo riferimento a questa descrizione come “Gtk.Builder UI definitions” e non sarà da confondere
con “GtkUIManager UI Definitions”, che è molto più limitata.
Gtk.Builder UI definitions Syntax
Gtk.Builder esegue l’analisi (parsing) della descrizione testuale della UI in formato XML secondo
lo schema seguente:
L’elemento toplevel è
<interface>
.
Opzionalmente accetta un attributo “domain” che farà cercare al builder le stringhe tradotte in
base al dominio specificato. Questo si ottiene anche chiamando il metodo
Gtk.Builder.set_translation_domain().
Gli oggetti sono descritti nei tag , che possono contenere elementi , che descrivono le proprietà
degli oggetti (elementi), che connettono i segnali agli handlers, ed elementi , che descrivono i
child objects (molto spesso i widgets dentro ai contenitori, ma anche le actions dentro agli
action group, o le colonne nel tree-model).
Banalmente un elemento contiene un altro elemento elemento che descrive il child object.
La versione del toolkit viene descritta dall’elemento
<requires>
.
L’attributo “lib” specifica la libreria dei widget (attualmente l’unica supportata è “gtk+”).
L’attributo “version” specifica la versione in formato
<major>.<minor>
.
Se i requisiti di versione non vengono raggiunti, il builder darà errore.
Il tipo di oggetto rappresentato da un elemento viene specificato dall’attributo “class”.
Se il tipo di oggetto non è ancora stato caricato, GTK+ tenta di trovare il metodo
get_type() dal nome della classe; questo funziona quasi sempre, in caso contrario
è possibile specificare il nome della funzione get_type() esplicitamente, usando l’attributo
“type-func”.
Come caso speciale, Gtk.Builder permette di usare un oggetto che è stato costruito da un
Gtk.UIManager in un’altra parte della definizione UI, specificando l’id del
Gtk.UIManager nell’attributo “constructor” ed il nome dell’oggetto,
nell’attributo “id”.
Agli oggetti è possibile dare un nome con l’attributo “id”, che a sua volta permette all’app di
recuperare l’oggetto, tramite il medodo del builder Gtk.Builder.get_object(id).
Il settaggio delle properties degli oggetti è molto semplice grazie all’elemento
<property>
.
L’attributo “name” è il nome della property e il contenuto dell’elemento, il suo valore.
Se l’attributo “translatable” è settato a True, GTK+ userà gettext()
(o dgettext() se il builder ha settato un translation domain) per la traduzione del valore.
Gtk.Builder può fare l’analisi di testi che rappresentino i tipi più comuni di properties:
caratteri, stringhe, interi, numeri floating-point, booleans (stringhe come “True”, “t”, “yes”,
“y”, “1” sono interpretate come True, mentre stringhe come “False”, “f”, “no”, “n”, “0”,
interpretate come False), enums (possono essere specificati con il loro “name”, “nick” o
valore intero), flags (possono essere specificate dal loro “name”, “nick”, valore intero,
opzionalmente combinate con “|”, ad esempio “GTK_VISIBLE|GTK_REALIZED”) e colori (in un formato
leggibile con Gdk.RGBA.parse()).
GVariants vengono specificati nel formato leggibile da GLib.Variant.parse(), e
pixbufs specificati come filename di un file immagine da caricare.
I Signal handlers sono settati con l’elemento
<signal>
.
L’attributo “name” specifica il nome del segnale, e l’attributo “handler”, specifica la funzione
da connettere al segnale.
A volte è necessario fare riferimento a widget che sono stati costruiti in maniera implicita da
GTK+ come parte di un widget composto, per settare le properties su di essi aggiungere ulteriori
children (ad esempio il vbox di un Gtk.Dialog).
Questo può essere ottenuto settando la property “internal-child” dell’elemento a True.
I widgets hanno posti diversi dove aggiungere un child (ad esempio i contenuti di tabs e page nei
notebooks). Questo può essere definito nella “UI definition” specificando l’attributo “type”
nell’elemento
<child>
.
Un esempio di UI Definition per Gtk.Builder
<interface>
<object class="GtkDialog" id="dialog1">
<child internal-child="vbox">
<object class="GtkBox" id="vbox1">
<property name="border-width">10</property>
<child internal-child="action_area">
<object class="GtkButtonBox" id="hbuttonbox1">
<property name="border-width">20</property>
<child>
<object class="GtkButton" id="ok_button">
<property name="label">gtk-ok</property>
<property name="use-stock">TRUE</property>
<signal name="clicked" handler="ok_button_clicked"/>
</object>
</child>
</object>
</child>
</object>
</child>
</object>
</interface>
Le properties principali sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| translation-domain | str | r/w | Il translation domain usato da gettext() |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.Builder,
i principali metodi sono:
new()
Crea un nuovo oggetto Gtk.Builder vuoto.
Questo metodo è utile nel caso si vogliano caricare porzioni di descrizione derivanti da fonti
diverse, con metodi come Gtk.Builder.add_from_file(),
Gtk.Builder.add_from_resource(), o Gtk.Builder.add_from_string().
Qualora la sorgente dovesse essere unica, sarebbero più comodi i class_methods
Gtk.Builder.new_from_file(), Gtk.Builder.new_from_resource(),
o Gtk.Builder.new_from_string().
new_from_file(filename)
Costruisce la UI definition presente nel filename passato come argomento.
Parametri:
filename: il nome del file contenente la UI description
new_from_resource(resource_path)
Costruisce la UI definition presente alla resource_path.
Parametri:
resource_path: l’oggetto Gio.Resource con il resource path;
new_from_string(string, length)
Costruisce la UI definition descritta dalla stringa.
Parametri:
string: la stringa contenente la UI definition (XML);
length: la lunghezza della stringa, o -1 se la stringa è None-terminated;
>>> TOOLBAR_INFO = """ ... <?xml version="1.0" encoding="UTF-8"?> ... <interface> ... <!-- interface-requires gtk+ 3.0 --> ... <object class="GtkToolbar" id="toolbar"> ... <property name="visible">True</property> ... <property name="can_focus">False</property> ... <property name="hexpand">True</property> ... <property name="show_arrow">False</property> ... <child> ... <object class="GtkToolButton" id="new_button"> ... <property name="use_action_appearance">False</property> ... <property name="visible">True</property> ... <property name="can_focus">False</property> ... <property name="use_action_appearance">False</property> ... <property name="is_important">True</property> ... <property name="action_name">win.new</property> ... <property name="label" translatable="yes">New</property> ... <property name="use_underline">True</property> ... <property name="stock_id">gtk-new</property> ... </object> ... <packing> ... <property name="expand">False</property> ... <property name="homogeneous">True</property> ... </packing> ... </child> ... </object> ... </interface> ... """ >>> builder = Gtk.Builder.new_from_string(TOOLBAR_INFO, -1)
add_callback_symbol(callback_name, callback_symbol)
Aggiunge il callback_symbol allo scope del builder sotto il nome della callback.
Questo metodo sovrascrive cioò che è stato settato con il metodo Gtk.Builder.connect_signals(),
per ogni callback symbols che viene aggiunto.
L’utilizzo di questo metodo permette un miglior incapsulamento inquanto non occorre dichiarare i
callback symbols nel global namespace.
Parametri:
callback_name: il nome della callback, come previsto nell’XML;
callback_symbol: il GObject.Callback, ovver il callback pointer;
add_from_file(filename)
Esegue l’analisi di un file contenente una UI definition e la unisce con il contenuto corrente del
builder. Se la UI definition risiede in un unico file è consigliabile l’utilizzo di
Gtk.Builder.new_from_file().
Parametri:
filename: il nome file di cui analizziamo il contenuto (parsing);
add_from_resource(resource_path)
Analizza un resource file con una UI definition e la unisce al contenuto corrente del builder.
Se la UI definition risiede in un unico resource file è consigliabile l’utilizzo di
Gtk.Builder.new_from_resource().
Parametri:
resource_path: il percorso del resource file da analizzare;
add_from_string(buffer, length=-1)
Analizza una stringa contenente una UI definition e la unisce al contenuto corrente del builder.
Se la UI definition risiede in un unica stringa è consigliabile l’utilizzo di
Gtk.Builder.new_from_string().
Parametri:
buffer: la stringa da analizzare;
length: la lunghezza del buffer;
add_objects_from_file(filename, object_ids)
Analizza un file contenente una UI definition costruendo solo gli oggetti richiesti e li unisce
al contenuto corrente del builder. Se stiamo aggiungendo un oggetto che dipende da un oggetto che
non è suo child (ad esempio un Gtk.TreeView che dipende dal proprio Gtk.TreeModel), dobbiamo
metterlo esplicitamente nella lista object_ids.
Parametri:
filename: il nome del file da analizzare;
object_ids: una lista di stringhe con gli oggetti da costruire;
add_objects_from_resource(resource_path, object_ids)
Analizza un resource file contenente una UI definition costruendo solo gli oggetti richiesti e li
unisce al contenuto corrente del builder. Se stiamo aggiungendo un oggetto che dipende da un
oggetto che non è suo child (ad esempio un Gtk.TreeView che dipende dal proprio Gtk.TreeModel),
dobbiamo metterlo esplicitamente nella lista object_ids.
Parametri:
resource_path: il percorso del resource file da analizzare;
object_ids: la lista “nul-terminated” di stringhe corrispondenti
agli oggetti da costruire;
add_objects_from_string(buffer, object_ids)
Analizza una stringa contenente una UI definition costruendo solo gli oggetti richiesti e li
unisce al contenuto corrente del builder. Se stiamo aggiungendo un oggetto che dipende da un
oggetto che non è suo child (ad esempio un Gtk.TreeView che dipende dal proprio Gtk.TreeModel),
dobbiamo metterlo esplicitamente nella lista object_ids.
Parametri:
buffer: la stringa da analizzare;
object_ids: una lista di stringhe con gli oggetti da costruire;
connect_signals(self, obj_or_map)
Connette i segnali specificati ai rispettivi handler, come indicato nel dizionario passato come
argomento. L’handler (value) del segnale (key), può anche essere una tupla in forma
(handler [,arg1 [,argN]]), se all’handler è necessario passare degli argomenti.
esempio di applicazione:
builder.connect_signals({'on_clicked': (on_clicked, arg1, arg2)})
Parametri:
obj_or_map: il dizionario dove chiave/valore sono rispettivamente
il segnale e l’handler corrispondente;
connect_signals_full(func, *user_data)
Utilizza una funzione per connettere i segnali.
Parametri:
func: l’oggetto Gtk.BuilderConnectFunc, cioè la funzione usata
per connettere i segnali;
user_data: i dati che possono essere passati alla funzione;
expose_object(name, object)
Aggiunge un oggetto all’ oggetto condiviso del builder cosicchè possa essere
referenziato dagli altri oggetti costruiti dal builder.
Parametri:
name: il nome dell’oggetto “esposto” al builder;
object: l’oggetto da esporre;
get_application()
Ritorna l’oggetto Gtk.Application associato al builder, oggetto utilizzato per creare i proxies
delle actions come richiesto dall’XML che il builder sta caricando. Di default, il builder usa
l’application di default (Gio.Application.get_default()).
Se vuoi usare un’altra application per la costruzione dei proxies, usare il metodo
Gtk.Builder.set_application().
get_object(name)
Ritorna l’oggetto con il nome passato come argomento.
Parametri:
name: il nome dell’oggetto che vogliamo recuperare dal builder;
>>> builder.get_object("new_button")
<Gtk.ToolButton object at 0x00000000035b5f40 (GtkToolButton at 0x000000000318d1c0)>
>>> builder.get_object("new_button").get_label()
'New'
get_objects()
Ritorna tutti gli oggetti che sono stati costruiti dal builder.
>>> for obj in builder.get_objects(): ... print(type(obj)) ... <class 'gi.overrides.Gtk.ToolButton'> <class 'gi.repository.Gtk.Toolbar'>
get_translation_domain()
Ritorna il translation domain del builder.
get_type_from_name(type_name)
Ritorna il tipo di oggetto (GObject.GType) dal nome passato come argomento, o GObject.TYPE_INVALID
se nessun tipo viene trovato.
Parametri:
type_name: il nome da cui ricavare il tipo di oggetto;
>>> builder.get_type_from_name("GtkToolbar")
<GType GtkToolbar (80271280)>
>>> builder.get_type_from_name("GtkToolButton")
<GType GtkToolButton (54634240)>
set_application(application)
Associa l’applicazione al builder.
Questo metodo si usa solo se ci sono più di un oggetto Gio.Application nel nostro processo.
Parametri:
application: l’oggetto Gtk.Application da associare al builder,
non può essere None;
set_translation_domain(domain)
Setta il translation domain del builder.
Parametri:
domain: la stringa con il translation domain o None;
value_from_string(pspec, string)
Questa funzione converte la rappresentazione XML di un valore, nell’oggetto di default
(demarshal). In pratica il metodo chiama GObject.Value.init()
sul valore, così non deve essere inizializzato anticipatamente.
Questa funzione può gestire i tipi di valore str, uchar, boolean, int, uint, long, ulong, enum,
flags, float, double, string, Gdk.Color, Gdk.RGBA e Gtk.Adjustment
Parametri:
pspec: l’oggetto GObject.ParamSpec per la property;
string: la stringa che rappresenta il valore;
value_from_string_type(type, string)
Come il metodo Gtk.Builder.value_from_string(), questo esegue il demarshal di un
valore da una stringa, ma prende un oggetto GObject.GType invece di un oggetto
GObject.ParamSpec.
In pratica il metodo chiama GObject.Value.init() sul valore, così non deve
essere inizializzato anticipatamente.
Parametri:
type: il GObject.GType del valore;
string: la stringa che rappresenta il valore;
Ecco un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gio
TOOLBAR_INFO = """
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<!-- interface-requires gtk+ 3.0 -->
<object class="GtkToolbar" id="toolbar">
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="hexpand">True</property>
<property name="show_arrow">False</property>
<child>
<object class="GtkToolButton" id="new_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.new</property>
<property name="label" translatable="yes">New</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-new</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
<child>
<object class="GtkToolButton" id="open_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.open</property>
<property name="label" translatable="yes">Open</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-open</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
</object>
</interface>
"""
class AppWindow(Gtk.ApplicationWindow):
def __init__(self):
super().__init__(title="Toolbar Example")
self.set_default_size(250, 100)
builder = Gtk.Builder.new_from_string(TOOLBAR_INFO, -1)
act_new = Gio.SimpleAction.new(name='new', parameter_type=None)
act_open = Gio.SimpleAction.new(name='open', parameter_type=None)
self.add_action(act_new)
self.add_action(act_open)
tool_bar = builder.get_object('toolbar')
tool_bar.set_style(Gtk.ToolbarStyle.BOTH)
box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
box.pack_start(tool_bar, False, False, 0)
self.add(box)
# bindings
act_new.connect('activate', self.on_menu)
act_open.connect('activate', self.on_menu)
self.connect('destroy', Gtk.main_quit)
def on_menu(self, action, value):
print("INFO: menu <%s>" % action.props.name)
if __name__ == "__main__":
win = AppWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.Image
torna all’indice degli appunti
Image
Il widget Gtk.Image visualizza un’immagine.
Generalmente verrà caricato un GdkPixbuf.Pixbuf (“pixel buffer”) da un file.
La classe Gtk.Image fornisce un metodo per fare questa operazione,
Gtk.Image.new_from_file():
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk, Gio
>>> image = Gtk.Image.new_from_file("image.png")
Se l’immagine non verrà caricata correttamente, l’oggetto image conterrà una icona “broken image”.
Come detto in precedenza, caricare un’immagine passando da un oggetto GdkPixbuf.Pixbuf
permetterà di gestire gli eventuali errori in caricamento:
>>> from gi.repository import GdkPixbuf
>>> pixbuf = GdkPixbuf.Pixbuf.new_from_file("image.png")
Traceback (most recent call last):
File "<input>", line 1, in <module>
gi.repository.GLib.GError: g-file-error-quark: Apertura del file «image.png» non riuscita: No such file or directory (4)
>>> # correggiamo il percorso o aggiungiamo il file mancante
>>> pixbuf = GdkPixbuf.Pixbuf.new_from_file("image.png")
>>> image = Gtk.Image.new_from_pixbuf(pixbuf)
Il file image può anche contenere un’animazione, in tal caso Gtk.Image visualizzerà l’animazione
via GdkPixbuf.PixbufAnimation, invece che un’immagine statica.
L’oggetto Gtk.Image è una sottoclasse di Gtk.Misc, che implica che possiamo
allinearla (center, left, right) e aggiungere il padding ad essa, grazie ai metodi di Gtk.Misc.
Gtk.Image è un widget “no window”, che significa che non riceve eventi.
Se vogliamo ricevere eventi sull’oggetto image, ad esempio quando clicchiamo sopra all’immagine,
dobbiamo inserirlo dentro ad un widget Gtk.EventBox,
quindi connettere i segnali all’eventbox stesso.
Le properties principali sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| file | str | r/w | il nome del file da caricare e visualizzare |
| gicon | Gio.Icon | r/w | La Gio.Icon che sarà visualizzata |
| icon-name | str | r/w | Il nome dell’icona dell’icon theme |
| icon-size | int | r/w/en | Il Symbolic size da usare per stock icon, icon set o named icon |
| pixbuf | GdkPixbuf.Pixbuf | r/w | Il GdkPixbuf.Pixbuf da visualizzare |
| pixbuf-animation | GdkPixbuf.PixbufAnimation | r/w | il GdkPixbuf.PixbufAnimation da visualizzare |
| pixel-size | int | r/w/en | Pixel size to use for named icon |
| resource | str | r/w | Il resource path da visualizzare |
| storage-type | Gtk.ImageType | r | la rappresentazione da usare per i dati immagine |
| surface | cairo.Surface | r/w | Il cairo.Surface da visualizzare |
| use-fallback | bool | r/w/en | Se usare gli icon names fallback |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.Image,
i principali metodi sono:
new()
Crea un nuovo widget Gtk.Image vuoto.
new_from_animation(animation)
Crea una Gtk.Image che visualizza l’animazione data.
I frames dell’animazione vengono visualizzati usando un timeout con GLib.PRIORITY_DEFAULT.
Quando usiamo le animations per indicare che l’applicazione sta lavorando, ricordarsi che tali
animazioni verranno visualizzate solo se il main loop non è occupato da un processo con priorità maggiore.
Parametri:
animation: l’oggetto GdkPixbuf.PixbufAnimation con l’animazione;
new_from_file(filename)
Crea un nuovo Gtk.Image che visualizza il file passato come argomento.
Se il file non viene trovato o non può essere caricato, il Gtk.Image risultante visualizzeà una
icona “broken image” icon.
Questo metodo non ritorna mai None, ma sempre un widget Gtk.Image valido.
Se il file contiene un’animazione, allora il widget image conterrà un’animazione.
Se vogliamo gestire gli errori di caricamento file (ad esempio l’assenza del file nel percorso
di ricerca), è necessario usare GdkPixbuf.Pixbuf.new_from_file() per caricare il
file, quindi creare il widget Gtk.Image dal pixbuf precedente.
Per le animazioni, per la stessa ragione, usare GdkPixbuf.PixbufAnimation.new_from_file().
Parametri:
filename: la stringa con il nome file che contiene l’immagine;
new_from_gicon(icon, size)
Crea un widget Gtk.Image che visualizza una icona dal tema icone corrente.
Se il nome icona non è riconosciuto, verrà visualizzata un’icona di tipo “broken image”.
Se viene modificato il tema icone, l’icona sarà aggiornata.
Parametri:
icon: un oggetto Gio.Icon che rappresenta un’icona;
size: un oggetto Gtk.IconSize con la dimensionde dell’icona;
new_from_icon_name(icon_name, size)
Crea un widget Gtk.Image che visualizza un’icona da tema icone corrente.
Se il nome icona non è riconosciuto, verrà visualizzata un’icona di tipo “broken image”.
Se viene modificato il tema icone, l’icona sarà aggiornata.
Parametri:
icon_name: una stringa con il nome icona, o None;
size: un oggetto Gtk.IconSize con la dimensionde dell’icona;
new_from_pixbuf(pixbuf)
Crea un widget Gtk.Image che visualizza un pixbuf.
Questo metodo crea solo un widget Gtk.Image dal pixbuf, ma non reagirà ai cambiamenti di stato.
E’ consigliabile in tal caso utilizzare Gtk.Image.new_from_icon_name().
Parametri:
pixbuf: il ‘oggetto GdkPixbuf.Pixbuf da cui creare il widget
Gtk.Image, o None;
new_from_resource(resource_path)
Crea un widget Gtk.Image che visualizza il resource file.
Se il file non viene trovato o non può essere caricato, il widget image risultante, mostrerà
un’immagine di tipo “broken image”.
Questo metodo ritorna sempre un widget Gtk.Image valido e mai None.
Se il file contiene un’animazione, allora il widget image conterrà un’animazione.
Se vogliamo gestire gli errori di caricamento file (ad esempio l’assenza del file nel percorso
di ricerca), è necessario usare GdkPixbuf.Pixbuf.new_from_file() per caricare il
file, quindi creare il widget Gtk.Image dal pixbuf precedente.
Per le animazioni, per la stessa ragione, usare GdkPixbuf.PixbufAnimation.new_from_file().
Parametri:
resource_path: la stringa che rappresenta un resource path;
new_from_surface(surface)
Crea un widget Gtk.Image che visualizza un surface.
Parametri:
surface: un oggetto cairo.Surface o None.
clear()
Svuota il widget Gtk.Image dai suoi contenuti.
get_animation()
Ritorna l’oggetto GdkPixbuf.PixbufAnimation visualizzato dal widget Gtk.Image.
Lo storage type dell’immagine deve essere uno tra Gtk.ImageType.EMPTY,
o Gtk.ImageType.ANIMATION (vedere Gtk.Image.get_storage_type()).
get_gicon()
Ritorna una tupla con gli oggetti Gio.Icon e Gtk.IconSize, del widget Gtk.Image.
Lo storage type dell’immagine deve essere Gtk.ImageType.EMPTY, o Gtk.ImageType.GICON
(vedere Gtk.Image.get_storage_type()).
get_icon_name()
Ritorna una tupla con il nome dell’icona e l’oggetto Gtk.IconSize delle dimensioni della stessa.
Lo storage type dell’immagine deve essere Gtk.ImageType.EMPTY, o Gtk.ImageType.ICON_NAME
(vedere Gtk.Image.get_storage_type()).
get_pixbuf()
Ritorna il GdkPixbuf.Pixbuf visualizzato dal widgetg Gtk.Image.
Lo storage type dell’immagine deve essere Gtk.ImageType.EMPTY, o Gtk.ImageType.PIXBUF
(vedere Gtk.Image.get_storage_type()).
get_pixel_size()
Ritorna la dimensione in pixel, utilizzata per le named icons.
get_storage_type()
Ritorna il tipo di rappresentazione usato dal Gtk.Image per salvare i dati dell’immagine.
Se Gtk.Image non ha dati immagine il valore ritornato sarà Gtk.ImageType.EMPTY.
>>> image.get_storage_type() <enum GTK_IMAGE_PIXBUF of type Gtk.ImageType>
set_from_animation(animation)
Fa sì che il widget Gtk.Image visualizzi l’animazione data.
Parametri:
animation: l’oggetto GdkPixbuf.PixbufAnimation che rappresenta
l’animazione da visualizzare o None;
set_from_file(filename)
Vedere il class method Gtk.Image.new_from_file().
Parametri:
filename: la stringa con il nome del file o None;
set_from_gicon(icon, size)
Vedere Gtk.Image.new_from_gicon().
Parametri:
icon: un oggetto Gio.Icon che rappresenti un’icona;
size: un oggetto Gtk.IconSize con la dimensione dell’icona;
set_from_icon_name(icon_name, size)
vedere Gtk.Image.new_from_icon_name().
Parametri:
icon_name: la stringa con il nome dell’icona o None;
size: un oggetto Gtk.IconSize con la dimensione dell’icona;
set_from_pixbuf(pixbuf)
Vedere Gtk.Image.new_from_pixbuf().
Parametri:
pixbuf: un oggetto GdkPixbuf.Pixbuf o None;
set_from_resource(resource_path)
Vedere Gtk.Image.new_from_resource().
Parametri:
resource_path: la stringa con il resource path o None;
set_from_surface(surface)
Vedere Gtk.Image.new_from_surface().
Parametri:
surface: un oggetto cairo.Surface o None;
set_pixel_size(pixel_size)
Setta la dimensione in pixel da usare per le named icons. Se il pixel_size viene settato ad un
valore positivo, tale valore verrà usato al posto dell’icon size settato dal metodo
Gtk.Image.set_from_icon_name().
Parametri:
pixel_size: la dimensione in pixel da settare per le named icons;
Nota:
siccome Gtk.IconSize è deprecato, per creare un’icona è conveniente passare
attraverso Gtk.IconTheme.
Il procedimento è semplice:
si ottiene il default icon-theme con il metodo Gtk.IconTheme.get_default() e
con l’oggetto Gtk.IconTheme ritornato si chiama il metodo
Gtk.IconTheme.load_icon(icon_name, size, flags), che restituisce l’oggetto pixbuf
relativo all’icona desiderata.
Infine si creerà il widget Gtk.Image con il metodo Gtk.Image.new_from_pixbuf(pixbuf).
Di seguito un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Image example")
box = Gtk.Box(spacing=6)
box.set_homogeneous(True)
default_theme = Gtk.IconTheme.get_default()
for icon_name in ("edit-copy", "edit-paste",
"mail-send-receive-symbolic"):
pixbuf = default_theme.load_icon(icon_name, 64, 0)
icon_image = Gtk.Image.new_from_pixbuf(pixbuf)
box.pack_start(icon_image, True, True, 0)
image = Gtk.Image.new_from_file("image.png")
box.pack_start(image, True, True, 0)
self.add(box)
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 Image
Adwaita icon theme
PyGObject: GdkPixbuf.Pixbuf
torna all’indice degli appunti
Pixbuf
Il widget GdkPixbuf.Pixbuf è la struttura principale della libreria GdkPixbuf.
Viene usato per rappresentare un’immagine e contiene tutte le informazioni della stessa come:
i dati dei pixel dell’immagine, il suo color space, i bits per sample,
larghezza e altezza e il rowstride (il numero dibytes tra l’inizio di una riga e
l’inizio della successiva).
Ne consegue che le properties relative alla classe GdkPixbuf.Pixbuf sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| bits-per-sample | int | r/w/co/en | il numero di bit per sample |
| colorspace | GdkPixbuf.Colorspace | r/w/co/en | Il colorspace nel quale i samples sono interpretati |
| has-alpha | bool | r/w/co/en | Se il pixbuf ha un canale alpha |
| height | int | r/w/co/en | il numero di righe del pixbuf |
| n-channels | int | r/w/co/en | Il numero di samples per pixel |
| pixel-bytes | GLib.Bytes | r/w/co/en | I dati del pixel ReadOnly |
| pixels | int | r/w/co/en | I pixel data del pixbuf |
| rowstride | int | r/w/co/en | I bytes tra l’inizio di una riga e l’inizio della successiva |
| width | int | r/w/co/en | Il numero di colonne del pixbuf |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto GdkPixbuf.Pixbuf,
i principali metodi sono:
calculate_rowstride(colorspace, has_alpha, bits_per_sample, width, height)
Calcola il rowstride che un’immagine creata con i parametri passati come argomenti dovrebbe avere.
Parametri:
colorspace: il GdkPixbuf.Colorspace per l’immagine;
has_alpha: un boolean per avere informazioni sulla trasparenza;
bits_per_sample: il numero di bit per color sample;
width: larghezza dell’immagine in pixels, deve essere > 0;
height: altezza dell’immagine in pixels, deve essere > 0;
get_file_info(filename)
Esegue il parsing di un file immagine e ritorna una tupla con il formato dell’immagine come
oggetto GdkPixbuf.PixbufFormat e le dimensioni dell’immagine stessa.
Se il formato dell’immagine non viene riconosciuto viene ritornato None e lo
stesso discorso vale per le dimensioni:
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
... from gi.repository import GdkPixbuf
>>> GdkPixbuf.Pixbuf.get_file_info("image.png")
(<GdkPixbuf.PixbufFormat object at 0x00000000040c6be0 (GdkPixbufFormat at 0x0000000004fa90c0)>, width=48, height=48)
>>> GdkPixbuf.Pixbuf.get_file_info("unknown.png")
(None, width=0, height=0)
Parametri:
filename: il nome del file da identificare;
get_file_info_async(filename, cancellable, callback, *user_data)
In modo asincrono esegue il parsing di un file immagine e ritorna una tupla contenente il formato
e le dimensioni dell’immagine. Per maggiorni dettagli vedi GdkPixbuf.Pixbuf.get_file_info(),
che è la versione sincrona di questo metodo.
Quando l’operazione è terminata la callback in argomento, verrà chiamata nel thread principale.
A quel punto si chiamerà il metodo GdkPixbuf.Pixbuf.get_file_info_finish() per avere il risultato.
Parametri:
filename: la stringa con il nome del file da identificare;
cancellable: un oggetto Gio.Cancellable opzionale o None;
callback: una callback Gio.AsyncReadyCallback da invocare quando
le informazioni dell’immagine sono disponibili, o None;
user_data: i dati opzionali da passare alla callback;
get_file_info_finish(async_result)
Termina un’operazione di parsing asincrona, iniziata con GdkPixbuf.Pixbuf.get_file_info_async() e
ritorna un oggetto GdkPixbuf.PixbufFormat che descrive il formato dell’immagine del file, o
None se il file non è stato riconosciuto.
Parametri:
async_result: un oggetto Gio.AsyncResult;
get_formats()
Ritorna la lista degli oggetti GdkPixbuf.PixbufFormat,
che rappresentano i formati supportati dal pixbuf.
>>> for format in GdkPixbuf.Pixbuf.get_formats(): ... print(format.get_description()) ... WMF EMF Windows animated cursor BMP GIF MacOS X icon ...
init_modules(path)
Inizializza i moduli del loader di gdkpixbuf referenziati dal file loaders.cache presente nella
directory.
Parametri:
path: la stringa col percorso della directory dove il file
loaders.cache è installato.
new(colorspace, has_alpha, bits_per_sample, width, height)
Crea un nuovo GdkPixbuf.Pixbuf e alloca un buffer per esso. Il buffer ha un rowstride ottimale:
>>> pixbuf = GdkPixbuf.Pixbuf.new(colorspace=colorspace, has_alpha=True, ... bits_per_sample=8, width=48, height=48) >>> pixbuf.get_rowstride() 192
Parametri:
colorspace: il GdkPixbuf.Colorspace per l’immagine;
has_alpha: un boolean per avere informazioni sulla trasparenza;
bits_per_sample: il numero di bit per color sample;
width: larghezza dell’immagine in pixels, deve essere > 0;
height: altezza dell’immagine in pixels, deve essere > 0;
new_from_bytes(data, colorspace, has_alpha, bits_per_sample, width, height, rowstride)
Crea un nuovo GdkPixbuf.Pixbuf out of in-memory readonly image data.
Al momento sono supportate solo immagini RGB con 8 bits per sample.
Questa è la variante GLib.Bytes del metodo GdkPixbuf.Pixbuf.new_from_data().
Parametri:
data: i dati immagine in formato 8-bit/sample;
colorspace: il GdkPixbuf.Colorspace per l’immagine;
has_alpha: un boolean per avere informazioni sulla trasparenza;
bits_per_sample: il numero di bit per color sample;
width: larghezza dell’immagine in pixels, deve essere > 0;
height: altezza dell’immagine in pixels, deve essere > 0;
rowstride: distanza in bytes tra gli inizi riga;
new_from_data(data, colorspace, has_alpha, bits_per_sample, width, height, rowstride, destroy_fn, *destroy_fn_data)
Crea un nuovo GdkPixbuf.Pixbuf out of in-memory image data.
Al momento sono supportate solo immagini RGB con 8 bits per sample.
Dal momento che forniamo un pixel buffer pre allocato, dobbiamo anche specificare un modo per
liberare quei dati. Questo è ottenuto con una funzione GdkPixbuf.PixbufDestroyNotify.
Quando un pixbuf è finalizzato la nostra “destroy notification function” viene chiamata e sarà
incaricata di liberare i dati relativi ai pixel. Vedere anche GdkPixbuf.Pixbuf.new_from_bytes().
Parametri:
data: i dati immagine in formato 8-bit/sample;
colorspace: il GdkPixbuf.Colorspace per l’immagine;
has_alpha: un boolean per avere informazioni sulla trasparenza;
bits_per_sample: il numero di bit per color sample;
width: larghezza dell’immagine in pixels, deve essere > 0;
height: altezza dell’immagine in pixels, deve essere > 0;
rowstride: distanza in bytes tra gli inizi riga;
destroy_fn: la funzione GdkPixbuf.PixbufDestroyNotify utilizzata
a pixbuf finalizzato, o None se non importa distruggere i dati;
destroy_fn_data: i dati da passare alla destroy notification
function;
new_from_file(filename)
Crea un nuovo pixbuf caricando l’immagine da un file. Il formato del file viene riconosciuto
automaticamente. Se si dovessere verificare errori nell’operazione, verrà ritornato None.
Parametri:
filename: la stringa con il nome del file da caricare;
new_from_file_at_scale(filename, width, height, preserve_aspect_ratio)
Crea un nuovo pixbuf caricando l’immagine da un file. Il formato del file viene riconosciuto
automaticamente. Se si dovessere verificare errori nell’operazione, verrà ritornato None.
L’immagine sarà scalata sulle dimensioni richieste, opzionalmente preservando l’aspect ratio.
Quando preserviamo l’aspect ratio, con width=-1 scaliamo l’immagine sull’altezza data,
con height=-1 scaliamo l’immagine sulla larghezza data.
Se non preserviamo l’aspect ratio, width=-1 o height=-1 significa non scalare l’immagine su
quella dimensione.
>>> pixbuf = GdkPixbuf.Pixbuf.new_from_file("image.png")
>>> pixbuf.get_width()
48
>>> pixbuf.get_height()
48
>>> sc_pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_scale("image.png", width=64, height=82,
... preserve_aspect_ratio=True)
>>> sc_pixbuf.get_width()
64
>>> sc_pixbuf.get_height() # forced by aspect ratio
64
Parametri:
filename: la stringa con il nome del file da caricare;
width: la larghezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
height: : l’altezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
preserve_aspect_ratio il boolean che decide se preservare o meno
l’aspect ratio dell’immagine;
new_from_file_at_size(filename, width, height)
Crea un nuovo pixbuf caricando l’immagine da un file. Il formato del file viene riconosciuto
automaticamente. Se si dovessere verificare errori nell’operazione, verrà ritornato None.
L’immagine sarà scalata sulle dimensioni richieste, preservando però l’aspect ratio,
potrebbe quindi capitare che il pixbuf risultante sia più piccolo rispetto a larghezza e altezza
richieste, proprio a causa dell’aspect ratio.
Per rispettare in toto le dimensioni richieste senza tenere conto dell’aspect ratio,
utilizzare il metodo GdkPixbuf.Pixbuf.new_from_file_at_scale().
Parametri:
filename: la stringa con il nome del file da caricare;
width: la larghezza che l’immagine dovrebbe avere;
height: l’altezza che l’immagine dovrebbe avere;
new_from_resource(resource_path)
Crea un nuovo pixbuf caricando un’immagine da una “resource”.
Il formato del file viene riconosciuto
automaticamente. Se si dovessere verificare errori nell’operazione, verrà ritornato None.
Parametri:
resource_path: la stringa con il path della risorsa;
new_from_resource_at_scale(resource_path, width, height, preserve_aspect_ratio)
Crea un nuovo pixbuf caricando un’immagine da una “resource”.
Il formato del file viene riconosciuto automaticamente.
Se si dovessere verificare errori nell’operazione, verrà ritornato None.
L’immagine sarà scalata sulle dimensioni richieste, opzionalmente preservando l’aspect ratio.
Quando preserviamo l’aspect ratio, con width=-1 scaliamo l’immagine sull’altezza data,
con height=-1 scaliamo l’immagine sulla larghezza data.
Se non preserviamo l’aspect ratio, width=-1 o height=-1 significa non scalare l’immagine su
quella dimensione.
Nota: Lo stream non viene chiuso da questo metodo.
Parametri:
resource_path: la stringa con il path della risorsa;
width: la larghezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
height: : l’altezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
preserve_aspect_ratio il boolean che decide se preservare o meno
l’aspect ratio dell’immagine;
new_from_stream(stream, cancellable)
Crea un nuovo pixbuf caricando un’immagine da uno stream in input.
Il formato del file viene riconosciuto automaticamente.
Se si dovessere verificare errori nell’operazione, verrà ritornato None.
Il cancellable può essere usato per abortire l’operazione da un altro thread.
Se l’operazione viene cancellata viene ritornato l’errore Gio.IOErrorEnum.CANCELLED.
Nota: Lo stream non viene chiuso da questo metodo.
Parametri:
stream: un Gio.InputStream dal quale caricare il pixbuf;
cancellable: un Gio.Cancellable opzionale o None;
new_from_stream_async(stream, cancellable, callback, *user_data)
Crea un nuovo pixbuf in maniera asincrona, caricando un’immagine da uno stream in input.
Per maggiori dettagli vedere GdkPixbuf.Pixbuf.new_from_stream(), che è la versione sincrona del
metodo in oggetto. Quando l’operazione è terminata, una callback viene invocata nel main thread.
E’ possibile quindi chiamare il metodo GdkPixbuf.Pixbuf.new_from_stream_finish() per ottenere il
risultato di questa operazione.
Parametri:
stream: un Gio.InputStream dal quale caricare il pixbuf;
cancellable: un oggetto Gio.Cancellable opzionale o None;
callback: una callback Gio.AsyncReadyCallback da invocare quando
le informazioni dell’immagine sono disponibili, o None;
user_data: i dati opzionali da passare alla callback;
new_from_stream_at_scale(stream, width, height, preserve_aspect_ratio, cancellable)
Crea un nuovo pixbuf caricando un’immagine da uno stream in input.
Il formato del file viene riconosciuto automaticamente.
Se si dovessere verificare errori nell’operazione, verrà ritornato None.
Il cancellable può essere usato per abortire l’operazione da un altro thread.
Se l’operazione viene cancellata viene ritornato l’errore Gio.IOErrorEnum.CANCELLED.
L’immagine sarà scalata sulle dimensioni richieste, opzionalmente preservando l’aspect ratio.
Quando preserviamo l’aspect ratio, con width=-1 scaliamo l’immagine sull’altezza data,
con height=-1 scaliamo l’immagine sulla larghezza data.
Se non preserviamo l’aspect ratio, width=-1 o height=-1 significa non scalare l’immagine su
quella dimensione.
Nota: Lo stream non viene chiuso da questo metodo.
Parametri:
stream: un Gio.InputStream dal quale caricare il pixbuf;
width: la larghezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
height: : l’altezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
preserve_aspect_ratio il boolean che decide se preservare o meno
l’aspect ratio dell’immagine;
cancellable: un oggetto Gio.Cancellable opzionale o None;
new_from_stream_at_scale_async(stream, width, height, preserve_aspect_ratio, cancellable, callback, *user_data)
Crea un nuovo pixbuf in maniera asincrona, caricando un’immagine da uno stream in input.
Per maggiori dettagli vedere GdkPixbuf.Pixbuf.new_from_stream_at_scale(), che è la versione
sincrona del metodo in oggetto. Quando l’operazione è terminata, una callback viene invocata nel
main thread. E’ possibile quindi chiamare il metodo GdkPixbuf.Pixbuf.new_from_stream_finish() per
ottenere il risultato di questa operazione.
Parametri:
stream: un Gio.InputStream dal quale caricare il pixbuf;
width: la larghezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
height: : l’altezza che l’immagine dovrà avere o -1 per non
forzare la dimensione;
preserve_aspect_ratio il boolean che decide se preservare o meno
l’aspect ratio dell’immagine;
cancellable: un oggetto Gio.Cancellable opzionale o None;
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the pixbuf is loaded
user_data (object or None) – the data to pass to the callback function
callback: una callback Gio.AsyncReadyCallback da invocare quando
le informazioni dell’immagine sono disponibili, o None;
user_data: i dati opzionali da passare alla callback;
new_from_stream_finish(async_result)
Termina un’operazione asincrona di creazione di un pixbuf iniziata con il metodo
GdkPixbuf.Pixbuf.new_from_stream_async().
Parametri:
async_result: un oggetto Gio.AsyncResult;
new_from_xpm_data(data)
Crea un nuovo pixbuf analizzando i dati XPM in memoria.
Questi dati sono comunemente il risultato dell’inclusione di un file XPM in una sorgente C.
Parametri:
data: i dati XPM inline;
save_to_stream_finish(async_result)
Termina un’operazione asincrona di salvataggio pixbuf.
Parametri:
async_result: un oggetto Gio.AsyncResult;
add_alpha(substitute_color, r, g, b)
Prende un pixbuf esistente e aggiunge un canale alpha (trasparenza) ad esso.
Se il pixbuf ha già un canale alpha, i valori del canale sono copiati dall’originale,
altrimenti il canale alpha viene inizializzato a 255 (opacità piena).
Se substitute_color è True, allora ai colori specificati da “r”, “g”, “b”, sarà
assegnata opacità zero. Esempio, se passiamo (255, 255, 255) per il substitute color,
tutti i pixel bianchi diventeranno completamente trasparenti.
Parametri:
substitute_color: boolean per settare un colore a opacità zero;
Se falso, gli argomenti r, g, b vengono ignorati.
r: il valore Red da sostituire;
g: il valore Green da sostituire;
b: il valore Blue da sostituire;
apply_embedded_orientation()
Prende un pixbuf esistente e controlla che sia presente un’opzione/tag “orientation”associato,
il quale può essere fornito dal loader jpeg (che legge il teg “exif orientation”), o dal loader
tiff (che legge il tag tiff orientation e lo compensa per le trasformazioni eseguite da libtiff).
Se è presente un’opzione/tag “orientation”, verrà eseguita l’appropriata trasformazione, così
da orientare il pixbuf correttamente. Verrà quindi ritornato il nuovo Pixbuf o None.
composite(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha)
Crea una trasformazione del pixbuf scalandolo secondo “scale_x” e “scale_y” e traslandolo secondo
gli offset “offset_x” e “offset_y”. Questo da un’immagine nelle coordinate del pixbuf di
destinazione. Il rettangolo (dest_x, dest_y, dest_width, dest_height) è quindi “alpha blended” sul
rettangolo corrispondente dell’immagine di destinazione originale.
Quando il rettangolo di destinazione contiene parti non presenti nell’immagine sorgente,
i dati ai bordi dell’immagine sorgente vengono replicati all’infinito.
Vedere Alpha compositing/blending
Parametri:
dest: il GdkPixbuf.Pixbuf nel quale fare il render del risultato;
dest_x: la coord. X (sx) della regione su cui fare il render;
dest_y: la coord. Y (top) della regione su cui fare il render;
dest_width: la larghezza della regione su cui fare il render;
dest_height: l’altezza della regione su cui fare il render;
offset_x: l’offset (float) in direzione X;
offset_y: l’offset (float) in direzione Y;
scale_x: il fattore di scala (float) in direzione X;
scale_y: il fattore di scala (float) in direzione Y;
interp_type: l’interpolazione GdkPixbuf.InterpType per la trasf.;
overall_alpha: l’alpha totale per l’immagine sorgente (0-255);
composite_color(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha, check_x, check_y, check_size, color1, color2)
Crea una trasformazione del pixbuf scalandola secondo “scale_x” e “scale_y” e traslandolo secondo
gli offset “offset_x” e “offset_y”, quindi esegue l’alpha blending del risultato, sul rettangolo
di destinazione (“dest_x”, “dest_y”, “dest_width”, “dest_height”) con un checkboard dei colori
“color1” e “color2” ed esegue il render sull’immagine di destinazione.
Se l’immagine di sorgente non ha un alpha channel, e overall_alpha=255, viene usata una
scorciatoia omettendo l’alpha blending ed eseguendo solo la scalatura dell’immagine.
Parametri:
dest: il GdkPixbuf.Pixbuf nel quale fare il render del risultato;
dest_x: la coord. X (sx) della regione su cui fare il render;
dest_y: la coord. Y (top) della regione su cui fare il render;
dest_width: la larghezza della regione su cui fare il render;
dest_height: l’altezza della regione su cui fare il render;
offset_x: l’offset (float) in direzione X;
offset_y: l’offset (float) in direzione Y;
scale_x: il fattore di scala (float) in direzione X;
scale_y: il fattore di scala (float) in direzione Y;
interp_type: l’interpolazione GdkPixbuf.InterpType per la trasf.;
overall_alpha: l’alpha totale per l’immagine sorgente (0-255);
check_x: l’offset X del checkboard;
check_y: l’offset Y del checkboard;
check_size: il size dei controlli nel checkboard (potenza di 2)
color1: il colore del check al superiore sinistro (checkboard);
color2: il colore dell’altro check;
Vedere GdkPixbuf.Pixbuf.composite_color_simple() per una variante più semplice di questo metodo.
composite_color_simple(dest_width, dest_height, interp_type, overall_alpha, check_size, color1, color2)
Crea un nuovo GdkPixbuf.Pixbuf scalandolo con “dest_width x dest_height” ed eseguendo l’alpha
blending del risultato con un checkboard di colori “color1” e “color2”.
Parametri:
dest_width: la larghezza dell’immagine di destinazione;
dest_height: l’altezza dell’immagine di destinazione;
interp_type: l’interpolazione GdkPixbuf.InterpType per la trasf.;
overall_alpha: l’alpha totale per l’immagine sorgente (0-255);
check_size: il size dei controlli nel checkboard (potenza di 2)
color1: il colore del check al superiore sinistro (checkboard);
color2: il colore dell’altro check;
copy()
Crea un nuovo GdkPixbuf.Pixbuf con una copia delle informazioni presenti nel pixbuf.
Questo non copia le opzioni settate nel pixbuf originali, per eseguire una copia completa usare
il metodo GdkPixbuf.Pixbuf.copy_options().
copy_area(src_x, src_y, width, height, dest_pixbuf, dest_x, dest_y)
Copia un’area rettangolare dal pixbuf, al “dest_pixbuf”. La conversione del formato, avviene in
maniera automatica. Se il rettangolo sorgente si sovrappone al rettangolo di destinazione sullo
stesso pixbuf, sarà sovrascritto durante la copia, perciò non possiamo usare questo metodo per
fare lo scroll di un pixbuf.
Parametri:
src_x: La coord. X del rettangolo sorgente;
src_y: La coord. Y del rettangolo sorgente;
width: La larghezza dell’area da copiare;
height: L’altezza dell’area da copiare;
dest_pixbuf: il GdkPixbuf.Pixbuf di destinazione;
dest_x: La coord. X del pixbuf di destinazione;
dest_y: La coord. Y del pixbuf di destinazione;
copy_options(dest_pixbuf)
Copia le coppie key/value relative alle opzioni di un GdkPixbuf.Pixbuf, in un altro.
Questo è comodo per mantenere i metadata originali dopo aver modificato un file.
Comunque fare attenzione a rimuovere i metadata che abbiamo già applicato, come ad esempio
l’opzione “orientation” dopo la rotazione dell’immagine.
Parametri:
dest_pixbuf: il GdkPixbuf.Pixbuf su cui copiare le opzioni;
fill(pixel)
Cancella un pixbuf al valore RGBA dato, convertendo il valore RGBA nel formato pixel del pixbuf.
Il valore alpha sarà ignorato se il pixbuf non ha un alpha channel.
Parametri:
pixel: il pixel RGBA da cancellare (0xffffffff è bianco opaco,
mentre 0x00000000 è nero trasparente)
flip(horizontal)
Capovolge un pixbuf orizzontalmente o verticalmente e ritorna il pixbuf risultante.
Parametri:
horizontal: il boolean che settato a True
capovolge il pixbuf orizzontalmente, mentre a False, verticalmente;
get_bits_per_sample()
Ritorna il numero di bits per color sample nel pixbuf.
get_byte_length()
Ritorna la lunghezza in bytes dei pixel data.
get_colorspace()
Ritorna il GdkPixbuf.Colorspace del pixbuf.
get_has_alpha()
Ritorna True se il pixbuf ha un alpha channel, altrimenti False.
L’alpha channel è l’informazione relativa all’opacità del pixbuf.
get_height()
Ritorna l’altezza del pixbuf espressa in pixels.
get_n_channels()
Ritorna il numero di canali di un pixbuf.
get_option(key)
Cerca la chiave nel dizionario i opzioni che sono state associate al pixbuf quando questo è stato
caricato o che potrebbe essere stata settata in seguito con GdkPixbuf.Pixbuf.set_option().
Alcuni esempi:
Il loader ANI fornisce le opzioni “Title” e “Artist”.
I loaders ICO, XBM, e XPM forniscono le opzioni hot-spot “x_hot” e “y_hot” per la definizione del
cursore. Il loader PNG fornisce, come opzioni, le coppie chiave/valore tEXt-ancillary-chunk.
I loaders TIFF e JPEG ritornano un’opzione “orientation” corrispondente al tag “orientation”
TIFF/Exif (se presente).
Il loader TIFF setta l’opzione “multipage” a “yes” quando un TIFF multi-page viene caricato.
I loaders JPEG e PNG settano le opzioni “x-dpi” e “y-dpi” se il file contiene informazioni
sulla densitò di immagine in punti per pollice.
Il loader JPEG setta l’opzione “comment” con il tag EXIF.
Parametri:
key: la stringa con la quale della quale chiediamo il valore;
get_options()
Ritorna un dizionario GLib.HashTable di chiavi/valori contenente le opzioni che possono essere
state settate, quando il pixbuf è stato caricato o che potrebbero essere state aggiunte in seguito
con GdkPixbuf.Pixbuf.set_option().
Vedere GdkPixbuf.Pixbuf.get_option() per maggiori dettagli.
get_pixels()
Ritorna i pixel data di un pixbuf.
>>> pixbuf.get_pixels() b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x0...
get_rowstride()
Ritorna il rowrowstride del pixbuf, ovvero la distanza, in bytes, tra l’inizio di una riga e
l’inizio della riga successiva.
>>> pixbuf.get_rowstride() 192 >>> len(pixbuf.get_pixels())/pixbuf.get_rowstride() 48.0 >>> pixbuf.get_height() 48
get_width()
Ritorna la larghezza in pixels di un pixbuf.
new_subpixbuf(src_x, src_y, width, height)
Crea un nuovo pixbuf che rappresenta una “sottoregione” del pixbuf in oggetto.
Il nuovo pixbuf condivide i propri pixels con il pixbuf originale, così facendo la scrittura
di un bixbuf ha effetto su entrambi.
Il nuovo pixbuf mantiene un riferimento sul pixbuf di partenza, così il pixbuf in oggetto non
verrà finalizzato fino a che il nuovo pixbuf non lo sarà.
Se il pixbuf di partenza è in sola lettura, questo metodo lo forzerà in scrittura.
Parametri:
src_x: la coordinata X del pixbuf sorgente;
src_y: la coordinata Y del pixbuf sorgente;
width: la larghezza della regione nel pixbuf;
height: l’altezza della regione nel pixbuf;
read_pixel_bytes()
Ritorna un oggetto GLib.Bytes contenente i dati raw del pixel.
Questi dati non devono essere modificati.
Questo metodo permette di saltare la copia implicita che deve essere fatta se il metodo
GdkPixbuf.Pixbuf.get_pixels() viene chiamato su un pixbuf read-only.
>>> pixbuf.read_pixel_bytes() <GLib.Bytes object at 0x000000000396f5e0 (GBytes at 0x0000000004a45960)>
read_pixels()
Ritorna il raw pixel data.
Questi dati non devono essere modificati.
Questo metodo permette di saltare la copia implicita che deve essere fatta se il metodo
GdkPixbuf.Pixbuf.get_pixels() viene chiamato su un pixbuf read-only.
>>> pixbuf.read_pixels() 32
remove_option(key)
Rimuove l’opzione (key) dal dizionario delle opzioni/valori creata quando il pixbuf è stato
caricato. Ritorna True se l’eliminazione va a buon fine.
Parametri:
key: la stringa con il nome dell’opzione (key) da rimuovere;
rotate_simple(angle)
Ruota il pixbuf di un multiplo di 90 gradi e ritorna il risultato in un nuovo pixbuf.
Se l’angolo è 0, viene ritornata una copia del pixbuf senza rotazione.
Parametri:
angle: il GdkPixbuf.PixbufRotation, cioè quanto ruotare il pixbuf;
saturate_and_pixelate(dest, saturation, pixelate)
Modifica la saturazione e opzionalmente esegue la pixelatura del pixbuf, mettendo il risultato
dell’operazione nel pixbuf di destinazione.
Se la saturation=1.0 la saturazione non viene modificata.
Con valori minori di 1.0, la saturazione viene ridotta (l’immagine si trasforma in scala di
grigio); se saturation è maggiore di 1.0, la saturazione viene incrementata (l’immagine assume
colori più vividi). Se pixelate=True, allora i pixels vengono sbiaditi in un pattern
“checkerboard” per creare un’immagine pixelata.
Il pixbuf sorgente e di destinazione devono avere lo stesso formato, dimensione e rowstride.
Parametri:
dest: il GdkPixbuf.Pixbuf su cui piazzare il pixbuf modificato;
saturation: il fattore di saturazione (float);
pixelate: il boolean per pixelare o meno il pixbuf risultante;
save_to_bufferv(type, option_keys, option_values)
Salva il pixbuf in un nuovo buffer nel tipo di formato “jpeg”, “tiff”, “png”, “ico” o “bmp”.
Parametri:
type: stringa con il nome del formato file;
option_keys: una di chiavi corrispondenti alla opzioni da settare;
option_values: una lista di valori corrispondenti alle opzioni;
save_to_callbackv(save_func, user_data, type, option_keys, option_values)
Salva il pixbuf in una callback nel tipo di formato “jpeg”, “png”, “tiff”, “ico” o “bmp”.
Se si verifica un errore, viene ritornato False.
Parametri:
save_func: un oggetto GdkPixbuf.PixbufSaveFunc, ovvero una
funzione chiamata per salvare ogni blocco di dati generata dalla routine di salvataggio;
user_data: i dati da passare alla funzione;
type: stringa con il nome del formato file;
option_keys: una di chiavi corrispondenti alla opzioni da settare;
option_values: una lista di valori corrispondenti alle opzioni;
save_to_streamv(stream, type, option_keys, option_values, cancellable)
Salva il pixbuf in uno stream di output. I formati di file supportati sono “jpeg”, “tiff”, “png”,
“ico” or “bmp”. Se il pixbuf viene salvato correttamente, il metodo ritorna True,
altrimenti False.
Parametri:
stream: un Gio.OutputStream su cui salvare il pixbuf;
type: stringa con il nome del formato file;
option_keys: una di chiavi corrispondenti alla opzioni da settare;
option_values: una lista di valori corrispondenti alle opzioni;
cancellable: un Gio.Cancellable opzionale o None;
save_to_streamv_async(stream, type, option_keys, option_values, cancellable, callback, *user_data)
Salva il pixbuf in uno stream di output in modo asincrono.
Per maggiori dettagli, vedere GdkPixbuf.Pixbuf.save_to_streamv(), che è la versione sincrona del
metodo in oggetto. Quando l’operazione è terminata la callback sarà chiamata nel thread
principale e quindi possiamo chiamare GdkPixbuf.Pixbuf.save_to_stream_finish() per ottenere il
risultato dell’operazione.
Parametri:
stream: un Gio.OutputStream su cui salvare il pixbuf;
type: stringa con il nome del formato file;
option_keys: una di chiavi corrispondenti alla opzioni da settare;
option_values: una lista di valori corrispondenti alle opzioni;
cancellable: un Gio.Cancellable opzionale o None;
callback: un Gio.AsyncReadyCallback da invocare quandi il pixbuf
viene salvato;
user_data: i dati da passare alla callback;
savev(filename, type, option_keys, option_values)
Salva il pixbuf in un file di tipo “jpeg”, “png”, “tiff”, “ico” or “bmp”.
Se il pixbuf viene salvato correttamente, il metodo ritorna True, altrimenti
False.
Parametri:
filename:la stringa con il nome del file da salvare;
type: stringa con il nome del formato file;
option_keys: una di chiavi corrispondenti alla opzioni da settare;
option_values: una lista di valori corrispondenti alle opzioni;
scale(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type)
Trasforma l’immagine sorgente scalandola su “scale_x” e “scale_y” e imposta l’offset definito da
“offset_x” e “offset_y”, quindi rappresenta il rettangolo (dest_x, dest_y, dest_width,
dest_height) dell’immagine risultante, sull’immagine di destinazione, rimpiazzando i contenuti
precedenti. Se non ci sono esigenze particolari si consiglia l’utilizzo del metodo
GdkPixbuf.Pixbuf.scale_simple().
Se il rettangolo del sorgente si sovrappone al rettangolo di destinazione sullo stesso pixbuf,
sarà sovrascritto durante la scalatura generando dei “rendering artifacts”.
Parametri:
dest: il GdkPixbuf.Pixbuf nel quale fare il render del risultato;
dest_x: la coord. X (sx) della regione su cui fare il render;
dest_y: la coord. Y (top) della regione su cui fare il render;
dest_width: la larghezza della regione su cui fare il render;
dest_height: l’altezza della regione su cui fare il render;
offset_x: l’offset (float) in direzione X;
offset_y: l’offset (float) in direzione Y;
scale_x: il fattore di scala (float) in direzione X;
scale_y: il fattore di scala (float) in direzione Y;
interp_type: l’interpolazione GdkPixbuf.InterpType per la trasf.;
scale_simple(dest_width, dest_height, interp_type)
Crea un nuovo GdkPixbuf.Pixbuf contenente una copia del pixbuf scalato a dest_width x dest_height.
Non influenza il pixbuf di origine. Per avere la massima velocità nell’operazione, il valore del
tipo di interpolazione deve essere settato a GdkPixbuf.InterpType.NEAREST.
(ma nelle operazioni if you want maximum speed
(but nelle operazioni di ridimensionamento è molto poco efficiente).
Il tipo di interpolazione di default dovrebbe essere GdkPixbuf.InterpType.BILINEAR, che offre
un rapporto qualità/velocità ragionevole.
Possiamo scalare una porzione di pixbuf, creando un sub-pixbuf (GdkPixbuf.Pixbuf.new_subpixbuf()).
Se “dest_width” e “dest_height” sono uguali alla larghezza e altezza del pixbuf di origine,
viene ritornata una copia del pixbuf di origine stesso, evitando la scalatura.
Per scalature e alpha-blending più complicati, consultare rispettivamente i metodi
GdkPixbuf.Pixbuf.scale() e GdkPixbuf.Pixbuf.composite().
Parametri:
dest_width: la larghezza dell’immagine di destinazione;
dest_height: l’altezza dell’immagine di destinazione;
interp_type: il tipo di interpolazione (GdkPixbuf.InterpType);
set_option(key, value)
Associa un’opzione in forma chiave/valore al GdkPixbuf.Pixbuf.
Se la chiave esiste già nel dizionario delle opzioni, il nuovo valore viene ignorato ed il metodo
ritorna False.
Parametri:
key: l’opzione (chiave del dizionario) da associare al pixbuf;
value: il valore dell’opzione;
Di seguito un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
from gi.repository import GdkPixbuf
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Pixbuf example")
self.set_default_size(300, 150)
box = Gtk.Box(spacing=6)
box.set_homogeneous(True)
pixbuf = GdkPixbuf.Pixbuf.new_from_file("image.png")
image = Gtk.Image.new_from_pixbuf(pixbuf)
pixbuf2 = pixbuf.rotate_simple(90)
pixbuf2.saturate_and_pixelate(pixbuf2, 3.0, True)
image2 = Gtk.Image.new_from_pixbuf(pixbuf2)
s_height = pixbuf.get_height() * 2
s_width = pixbuf.get_width() * 2
pixbuf3 = pixbuf.scale_simple(dest_width=s_width, dest_height=s_height,
interp_type=GdkPixbuf.InterpType.BILINEAR)
image3 = Gtk.Image.new_from_pixbuf(pixbuf3)
box.pack_start(image, True, True, 0)
box.pack_start(image2, True, True, 0)
box.pack_start(image3, True, True, 0)
self.add(box)
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gio.SimpleAction
torna all’indice degli appunti
SimpleAction
Una Gio.SimpleAction, come indica il nome, è una semplice implementazione dell’interfaccia di
Gio.Action, quindi rappresenta il modo più semplice per creare una Action.
La principale interfaccia di una Action è che può essere attivata con Gio.Action.activate().
Tale metodo causa l’emissione del segnale “activate”.
Una Action può opzionalmente avere uno stato, che può essere settato utilizzando il metodo
Gio.Action.change_state().
La classe Gio.Action è responsabile della memorizzazione del nome dell’azione, del tipo di
parametro, dello stato opzionale e dell’emissione del segnale appropriato quando lo stato cambia.
L’utilizzo delle Actions è un modo per associare un particolare attività ad un nome, tale attività
verrà eseguita dall’applicazione o da un widget, semplicemente facendo riferimento a tale nome.
In questo modo si possono tenere separate la logica dell’azione, dalla UI.
Un tipico esempio di utilizzo di Actions è dato dai Menu.
Le properties principali sono quelle ereditate da Gio.Action:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| enabled | bool | r | Se la Action può essere attivata |
| name | str | r | Il nome usato per invocare la Action |
| parameter-type | GLib.VariantType | r | Il tipo di GLib.Variant passato al metodo activate() |
| state | GLib.Variant | r | Lo stato in cui si trova la Action |
| state-type | GLib.VariantType | r | Il tipo di stato tenuto dalla Action |
Segnali
I segnale relativi al Gio.SimpleAction sono:
| Name | Short Description |
|---|---|
| activate | Indica che la Action è stata appena attivata |
| change-state | Indica che la Action ha appena ricevuto una richiesta di cambiare il proprio stato |
Il segnale activate si aspetta due parametri, simple_action” e “parameter”.
Basterà connettere la action al segnale “activate” con un handler che tenga presente di questi
parametri:
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
... from gi.repository import Gio
>>> action = Gio.SimpleAction.new(name='Bancaldo', parameter_type=None)
action.connect("activate", lambda a, p: print("INFO: action '%s' activated!" % a.get_name()))
8
>>> action.activate()
INFO: action 'Bancaldo' activated!
Il segnale change-state si aspetta due parametri, simple_action” e “value”.
Basterà connettere la action al segnale “activate” con un handler che tenga presente di questi
parametri:
>>> variant = GLib.Variant.new_boolean(True)
>>> stateful_action = Gio.SimpleAction.new_stateful(name="BancaldoStateful",
... parameter_type=None,
... state=variant)
>>> stateful_action.connect("change-state", lambda a, v: print("INFO: '%s' state changed to %s!" %
(a.get_name(), v)))
10
>>> stateful_action.change_state(GLib.Variant.new_boolean(True))
INFO: 'BancaldoStateful' state changed to true!
>>> stateful_action.change_state(GLib.Variant.new_boolean(False))
INFO: 'BancaldoStateful' state changed to false!
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.SimpleAction,
i principali metodi sono:
new(name, parameter_type)
Crea una nuova Action stateless.
Per creare una Action che abbia uno stato, utilizzare il metodo Gio.SimpleAction.new_stateful().
>>> action = Gio.SimpleAction.new(name='Bancaldo', parameter_type=None) >>> action.get_state() >>>
Parametri:
name: il nome della Action;
parameter_type: il tipo di parametro (GLib.VariantType o None) che
sarà passato agli handlers del segnale “activate” dell’oggetto Gio.SimpleAction, o None
per none passare nessun parametro;
new_stateful(name, parameter_type, state)
Crea una nuova stateful Action.
Ovviamente tutti i futuri valori di “state”, devono essere dello stesso GLib.Variant definito
in fase di costruzione.
>>> from gi.repository import GLib
>>> variant = GLib.Variant.new_boolean(True)
>>> stateful_action = Gio.SimpleAction.new_stateful(name="BancaldoStateful",
... parameter_type=None,
... state=variant)
>>> stateful_action.get_state()
GLib.Variant('b', true)
Parametri:
name: il nome della Action;
parameter_type: il tipo di parametro (GLib.VariantType o None) che
sarà passato agli handlers del segnale “activate” dell’oggetto Gio.SimpleAction, o None
per none passare nessun parametro;
state: lo stato iniziale (GLib.Variant) della Action;
set_enabled(enabled)
Abilita o disabilita una Action. Ovviamente una Action deve essere abilitata per poter essere
attivata o cambiare il proprio stato dall’esterno.
Parametri:
enabled: il boolean che abilita/disabilita la Action;
set_state(value)
Setta lo stato della Action. Questo metodo aggiorna direttamente la property “state”.
Non dovrebbe essere chiamato dall’utente per modificare lo stato della Action; è
preferibile utilizzare il metodo Gio.Action.change_state().
>>> new_state = GLib.Variant.new_boolean(False)
>>> stateful_action.set_state(new_state)
>>> stateful_action.get_state()
GLib.Variant('b', false)
Parametri:
value: il nuovo GLib.Variant con cui modificheremo lo stato;
set_state_hint(state_hint)
Setta l’hint (suggerimento) dello stato, per la Action.
Parametri:
state_hint: il GLib.Variant (o None) che rappresenta lo state hint
della Action.
>>> state_hint = GLib.Variant.new_string("Bancaldo's Boolean")
>>> stateful_action.set_state_hint(state_hint)
>>> stateful_action.get_state_hint()
GLib.Variant('s', "Bancaldo's Boolean")
Ecco un codice di esempio:
#!/usr/bin/env python3
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
from gi.repository import Gio
class AppWindow(Gtk.ApplicationWindow):
def __init__(self):
super().__init__()
self.set_default_size(200, 100)
# actions
act_file = Gio.SimpleAction.new(name='FileNew', parameter_type=None)
act_quit = Gio.SimpleAction.new(name='FileQuit', parameter_type=None)
act_info = Gio.SimpleAction.new(name='AboutInfo', parameter_type=None)
self.add_action(act_file)
self.add_action(act_quit)
self.add_action(act_info)
# model menu
menu_model = Gio.Menu.new()
# 1st menu
menu_file = Gio.Menu.new()
file_new = Gio.MenuItem.new('New', 'win.FileNew')
file_quit = Gio.MenuItem.new('Quit', 'win.FileQuit')
menu_file.append_item(file_new)
menu_file.append_item(file_quit)
# 2nd menu
menu_about = Gio.Menu.new()
about_info = Gio.MenuItem.new('Info', 'win.AboutInfo')
menu_about.append_item(about_info)
menu_model.append_submenu('File', menu_file)
menu_model.append_submenu('About', menu_about)
menu_bar = Gtk.MenuBar.new_from_model(menu_model)
# layout
layout = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
layout.pack_start(menu_bar, False, False, 0)
self.add(layout)
# bindings
act_file.connect('activate', self.on_menu)
act_quit.connect('activate', self.on_quit)
act_info.connect('activate', self.on_menu)
self.connect('destroy', Gtk.main_quit)
def on_menu(self, action, value):
print('INFO: menu <%s>' % action.props.name)
@staticmethod
def on_quit(action, param):
Gtk.main_quit()
if __name__ == '__main__':
win = AppWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
torna all’indice degli appunti
Gtk3 Gio.Action
GLib.Variant
GLib.VariantType
PyGObject: Gio.ActionMap
torna all’indice degli appunti
ActionMap
L’interfaccia Gio.ActionMap è implementata da Gio.ActionGroup.
Ha la funzione di contenere istanze di Gio.Action.
Un’applicazione comune di questa interfaccia è quella di mappare le actions provenienti da vari
gruppi (come Gtk.Application e Gtk.ApplicationWindow) utilizzando nomi con prefissi
identificativi, come ad esempio “app.” e “win.
Attenzione! Gio.ActionMap e Gio.ActionGroup sono Interfacce e non classi con un
metodo costruttore. Non è pertanto possibile costruirne delle istanze direttamente.
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
... from gi.repository import Gio
...
>>> action_map = Gio.ActionMap()
Traceback (most recent call last):
File "<input>", line 1, in <module>
NotImplementedError: ActionMap can not be constructed
E’ quindi necessario utilizzare delle classi che, oltre ad implementare la stessa interfaccia,
mettano a disposizione i metodi costruttori necessari allo scopo:
>>> myapp = Gtk.ApplicationWindow() >>> action = Gio.SimpleAction.new(name='Bancaldo', parameter_type=None) >>> myapp.add_action(action)
Non ci sono properties per Gio.ActionMap.
Segnali
Non ci sono segnali per Gio.ActionMap.
Metodi
I principali metodi sono:
add_action(action)
Aggiunge una action all’ActionMap. Se l’ActionMap contiene già una action con lo stesso nome,
la vecchia action viene rimossa dell’ActionMap stesso.
Parametri:
action: l’oggetto Gio.Action da aggiungere al Gio.ActionMap;
add_action_entries(entries, user_data)
Questo è un metodo che permette di aggiungere ad un Gio.ActionMap, una lista di
Gio.ActionEntry.
Parametri:
entries: la lista di Gio.ActionEntry da agiungere all’ActionMap;
user_data: i dati per le connessioni ai segnali;
lookup_action(action_name)
Ritorna la action con il nome passato come argomento, o None se non ci sono corrispondenze.
>>> myapp.lookup_action("Bancaldo")
>>> action = Gio.SimpleAction.new(name='Bancaldo', parameter_type=None)
>>> myapp.add_action(action)
>>> myapp.lookup_action("Bancaldo")
<Gio.SimpleAction object at 0x000000000365bfc0 (GSimpleAction at 0x0000000004b049c0)>
Parametri:
action_name: il nome della action;
remove_action(action_name)
Rimuove la action con il nome passato come argomento, dall’ActionMap.
Parametri:
action_name: il nome della action che vogliamo rimuovere;
– I metodi ereditati da Gio.ActionGroup sono:
action_added(action_name)
Emette il segnale “action-added” di Gio.ActionGroup.
Parametri:
action_name: il nome della action nel gruppo;
action_enabled_changed(action_name, enabled)
Emette il segnale “action-enabled-changed” di Gio.ActionGroup.
Parametri:
action_name: il nome della action nel gruppo;
enabled: il boolean che abilita/disabilita la action;
action_removed(action_name)
Emette il segnale “action-removed” di Gio.ActionGroup.
Parametri:
action_name: il nome della action nel gruppo;
action_state_changed(action_name, state)
Emette il segnale “action-state-changed” di Gio.ActionGroup.
Parametri:
action_name: il nome della action nel gruppo;
state: il nuovo stato GLib.Variant della action;
activate_action(action_name, parameter)
Attiva la action all’interno del gruppo. Se la action si aspetta un parametro, viene passato
il tipo corretto di parametro richiesto, altrimenti None.
Vedere Gio.ActionGroup.get_action_parameter_type().
Parametri:
action_name: il nome della action nel gruppo;
parameter: i parametri GLib.Variant all’attivazione (o None);
change_action_state(action_name, value)
Cambia lo stato della action con il valore passato come argomento.
La action deve essere stateful e il valore deve essere del tipo corretto.
Vedere Gio.ActionGroup.get_action_state_type().
Parametri:
action_name: il nome della action nel gruppo;
value: il nuovo stato GLib.Variant
get_action_enabled(action_name)
Controlla se la action all’interno del gruppo, è abilitata.
Una action per essere attivata o per poter cambiare il proprio stato, deve essere abilitata.
Parametri:
action_name: il nome della action nel gruppo;
get_action_parameter_type(action_name)
Ritorna il tipo di parametro che deve essere fornito quando si attiva la action.
Quando si attiva una action usando il metodo Gio.ActionGroup.activate_action(), il GLib.Variant
passato a questo metodo deve essere lo stesso tipo ritornato dal metodo in oggetto, se invece
questo metodo ritorna None, allora None dovrà essere passato a Gio.ActionGroup.activate_action().
Parametri:
action_name: il nome della action nel gruppo;
get_action_state(action_name)
Ritorna lo stato corrente della action con il nome passato come argomento.
Se la action non è stateful allora verrà ritornato None.
Se la action è stateful allora verrà ritornato il tipo di valore che corrisponderà al tipo
ritornato dal metodo Gio.ActionGroup.get_action_state_type().
Parametri:
action_name: il nome della action nel gruppo;
get_action_state_hint(action_name)
Ritorna un hint (suggerimento) sul range valido di valori per lo stato della action.
Se la action non è stateful o non è stato settato alcun hint, allora verrà ritornato None.
Se viene ritornata una lista di GLib.Variant, allora ogni elemento della lista sarà un possibile
valore dello stato della action.
Se viene ritornata una coppia di GLib.Variant (tupla) allora la tupla specificherà i valori
minimo e massimo dello stato.
Parametri:
action_name: il nome della action nel gruppo;
get_action_state_type(action_name)
Ritorna il tipo di stato della action.
Se la action è stateful, il metodo ritorna il GLib.VariantType dello stato della action e tutte le
chiamate al metodo Gio.ActionGroup.change_action_state() devono avere un GLib.Variant di
questo tipo e Gio.ActionGroup.get_action_state() ritornerà ovviamento lo stesso tipo di
GLib.Variant. Se la action non è stateful verrà ritornato None.
Parametri:
action_name: il nome della action nel gruppo;
has_action(action_name)
Controlla se la action esiste all’interno dell’ActionGroup.
Parametri:
action_name: il nome della action nel gruppo;
list_actions()
Lista le actions presenti nell’ActionGroup.
query_action(action_name)
Ritorna una ResultTuple con tutti i parametri della action con nome passato come argomento.
Questo metodo acquisisce tutte le informazioni disponibili da Gio.ActionGroup.has_action(),
Gio.ActionGroup.get_action_enabled(), Gio.ActionGroup.get_action_parameter_type(),
Gio.ActionGroup.get_action_state_type(), Gio.ActionGroup.get_action_state_hint() e
Gio.ActionGroup.get_action_state() con una singola chiamata.
Se la action esiste, viene ritornato True e tutti i valori diversi da None.
Se la action non esiste, viene ritornato False.
>>> myapp.query_action("Bancaldo")
(True, enabled=True, parameter_type=None, state_type=None, state_hint=None, state=None)
Parametri:
action_name: il nome della action nel gruppo;
link di riferimento:
torna all’indice degi appunti
Gtk3 Gio.ActionMap
Gtk3 Gio.ActionGroup
PyGObject: Gtk.EventBox
torna all’indice degli appunti
EventBox
Un widget Gtk.EventBox è una sottoclasse di Gtk.Bin che possiede una propria Window.
Viene spesso utilizzato quando vogliamo catturare gli eventi per quei widget che non possiedono
una propria finestra, come ad esempio le Immagini.
Le properties principali sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| above-child | bool | r/w/en | Se la finestra della eventbox, si trova sopra la finestra del widget figlio, invece che sotto di essa |
| visible-window | bool | r/w/en | Se la event box è visibile, anzichè invisibile ed usata solo per intercettare gli eventi |
Segnali
I segnali sono quelli ereditati da Gtk.Container, Gtk.Widget e GObject.Object.
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.EventBox,
i principali metodi sono:
new()
Crea un nuovo widget Gtk.EventBox.
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
...
>>> image = Gtk.Image.new_from_file("image.png")
>>> eventbox = Gtk.EventBox.new()
>>> eventbox.add(image)
get_above_child()
Ritorna True se la finestra della eventbox è sopra alla window del proprio child,
altrimenti ritorna False, se si trova sotto.
Vedere Gtk.EventBox.set_above_child() per i dettagli.
get_visible_window()
Ritorna True se la finestra della eventbox è visibile, altrimenti False
Vedere Gtk.EventBox.set_visible_window() per i dettagli.
set_above_child(above_child)
Setta se la finestra dell’event box debba essere posizionato sopra la finestra del suo widget
child, anzichè sotto. Se la finestra e sopra, tutti gli eventi dentro la event box andranno alla
eventbox. Se la finestra e sotto, gli eventi nella finestra del child, prima andranno al child
stesso, poi al suo genitore. Il default è tenere la finestra sotto alla finestra del child widget.
Parametri:
above_child: il boolean che a True pone la finestra dell’event box
sopra alla finestra del child widget;
set_visible_window(visible_window)
Setta se l’event box debba usare una finestra visibile o invisibile.
Il default è usare una finestra visibile.
In una finestra di event box invisibile, la window creata per l’event box è di tipo
Gdk.WindowWindowClass.INPUT_ONLY, che significa appunto che è invisibile e serve solo per
ricevere eventi. Una finestra di event box visibile, è di tipo Gdk.WindowWindowClass.INPUT_OUTPUT,
cioè che agisce da parent window per tutti i widgets contenuti nell’event box.
Per intercettare solo gli eventi, la finestra di event box dovrebbe essere invisibile.
Creare una finestra visibile, potrebbe generare anche degli artifacts visibili all’utente,
specialmente se l’utente sta usando un tema con gradienti o pixmaps.
La ragione di creare un event box non input-only è se vogliamo settare un background o disegnare
su di essa.
C’è un problema per gli event box invisibili che hanno la loro finestra sotto al child (vedere
Gtk.EventBox.set_above_child(). Dal momento che la finestra input-only non è una finestra
genitore di ogni finestra creata dai widgets discendenti dell’event box, gli eventi su queste
finestre non sono propagati dal windowing system, ma solo da GTK+.
In pratica se un evento non è nell’event mask della finestra discendente (vedere
Gtk.Widget.add_events()), non sarà ricevuta dall’event box.
Questo non succede per gli event box visibili, perchè in tal caso, la finestra della event box
è genitore delle finestre discendenti.
Parametri:
visible_window: il boolean che rende la finestra dell’event box
visibile;
Ecco un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="EventBox example")
self.set_default_size(250, 100)
image = Gtk.Image.new_from_file("image.png")
eventbox = Gtk.EventBox.new()
eventbox.add(image)
self.add(eventbox)
eventbox.connect("button_press_event", self.on_click)
def on_click(self, widget, param):
print("INFO: clicked on %s" % widget.get_child().get_property("file"))
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Signals
torna all’indice degli appunti
Main loop e Signals
GTK+ utilizza un modello di programmazione event-driven, ovvero GTK+ attende nel mainloop che un
utente esegua un’azione. Quando questo avviene, ad esempio un click su un pulsante,
il mainloop se ne accorge e spedisce l’evento corrispondente a GTK+.
Quando un widget (es. Button) riceve un evento (es. viene premuto), emette uno o più segnali.
Questi segnali notificano al programma che sta accadendo qualcosa di interessante ed invocano le
funzioni (callbacks) che ad essi sono collegate.
Quando la callback ha terminato il suo compito, GTK+ ritorna nel mainloop attendendo una nuova
azione da parte dell’utente.
Il metodo che lega un widget ad un evento è connect(event, callback, *data):
handler_id = widget.connect("event", callback, data)
widget: è un’istanza di un widget creata in precedenza;
Parametri:
event: è l’evento al quale siamo interessati. In genere ogni
widget ha un evento particolare, ad esempio Button sarà interessato all’evento “clicked”.
callback: il nome della funzione di callback che verrà invocata
quando quel determinato evento accadrà;
data: opzionale ed indica i valori da passare alla callback;
Il metodo connect(), ritorna il numero identificativo dell’handler che gestisce
la coppia signal-callback.
>>> import gi
>>> gi.require_version("Gtk", "3.0")
>>> from gi.repository import Gtk
>>> button = Gtk.Button(label="Ok")
>>> button.connect("clicked", lambda widget: print("clicked"))
23
>>> button.clicked()
clicked
Qualora dovessimo disconnettere il widget da quel segnale, è possibile utilizzare il metodo
disconnect(handler_id):
>>> button.disconnect(23) >>> button.clicked() >>>
E’ possibile anche disconnettere un widget da un evento, via funzione, con il metodo
disconnect_by_func(callback):
>>> def on_click(button):
... print("clicked")
...
>>> button.connect("clicked", on_click)
24
>>> button.clicked()
clicked
>>> button.disconnect_by_func(on_click)
1
>>> button.clicked()
>>>
Gtk.main_quit()
Connettere l’applicazione al segnale “destroy” della top-level window.
Quando l’utente chiude la toplevel window, l’handler di default per questo segnale distrugge
la window, ma non termina l’applicazione.
Connettendo il segnale “destroy” della top-level window alla Gtk.main_quit() darà invece il
risultato desiderato.
window.connect("destroy", Gtk.main_quit)
La chiamata a Gtk.main_quit() fa ritornare il main loop precedentemente creato
con Gtk.main().
Objects
GObject è il “tipo” fondamentale che fornisce gli attributi e i metodi per tutti
i tipi di oggetto di GTK+, Pango e le altre librerie basate su GObject.
La classe GObject.GObject fornisce i metodi per la costruzione e la distruzione
degli oggetti, i metodi per l’accesso alle properties degli oggetti, il supporto ai segnali.
Signals
I Signals connettono eventi arbitrari ai “listeners” di competenza.
Per esempio in GTK+, ogni evento (pressione di un tasto o movimento del mouse), viene ricevuto dal
server X che genera un evento GTK+ sotto forma di emissione di segnale.
Ogni segnale viene registrato nel type system insieme al type, sul quale può eseere emesso.
Per quel type, verrà registrata una funzione che sarà invocata ogni volta che sarà emesso quel
segnale specifico. Un segnale può essere emesso anche volontariamente o si può decidere di fermare
l’emissione del segnale dall’interno di una delle funzioni connesse a quel segnale.
Creare un nuovo segnale
Possiamo creare nuovi segnali aggiungendoli al dizionario GObject.GObject.__gsignals__:
Quando un nuovo segnale viene creato, può essere definito anche un method-handler, che sarà
invocato ogni volta che il segnale verrà emesso.
class CustomObject(GObject.GObject):
__gsignals__ = {'custom_signal': (GObject.SIGNAL_RUN_FIRST, None, (int,)),}
def emit_signal(self, arg):
print("method handler for 'custom_signal' called with argument", arg)
Parametri:
GObject.SIGNAL_RUN_FIRST: indica che questo segnale invocherà
il method handler definito (emit_signal()) nella fase di prima emissione.
Le alternative sono:
GObject.SIGNAL_RUN_LAST: il method handler sarà invocato nella terza fase di emissione;
GObject.SIGNAL_RUN_CLEANUP: invoca il method handler nell’ultima fase di emissione.
None: indica cosa ritorna il segnale, di solito None.
(int,): indica gli argomenti del segnale.
Nel nostro caso il segnale prende un solo argomento di tipo int.
I segnali possono essere emessi con il metodo GObject.GObject.emit():
>>> from gi.repository import GObject
>>> class CustomObject(GObject.GObject):
... __gsignals__ = {'custom_signal': (GObject.SIGNAL_RUN_FIRST, None, (int,)),}
...
... def do_custom_signal(self, arg):
... print("method handler for 'custom_signal' called with argument", arg)
...
>>> obj = CustomObject()
>>> obj.emit("custom_signal", 23)
method handler for 'custom_signal' called with argument 23
link di riferimento:
torna all’indice degi appunti
python gtk3 tutorial
Gtk3
PyGObject: Properties
torna all’indice degli appunti
Properties
Le Properties descrivono la configurazione e lo stato dei widgets.
Come per i segnali, ogni widget ha il proprio set di properties.
Ad esempio un Button ha la property “label” che contiene il testo della label dentro al button.
Quando creiamo un’istanza di un widget, possiamo specificare il nome e il valore di una property,
passandola come keyword argument.
Ad esempio per creare una label allineata sulla destra con il testo “Hello World” ed un angolo
di 25 gradi, useremo la sintassi:
label = Gtk.Label(label="Hello World", angle=25, halign=Gtk.Align.END)
che è l’equivalente di scrivere:
label = Gtk.Label()
label.set_label("Hello World")
label.set_angle(25)
label.set_halign(Gtk.Align.END)
Invece di usare i getters e i setters, possiamo ottenere e settare le properties attraverso la
property props, con la sintassi:
widget.props.prop_name = value
Per sapere quali properties sono disponibili per un widget, possiamo scrivere:
>>> for prop in dir(button.props): ... print(prop) ... action_name action_target always_show_image app_paintable ... >>> button.props.label 'Ok' >>> button.props.label = "Click" >>> button.props.label 'Click'
Utilizzo di properties esistenti
La classe GObject.GObject fornisce le seguenti funzioni per gestire le properties esistenti:
GObject.GObject.get_property() e GObject.GObject.set_property().
Come accennato in precedenza, alcune properties hanno funzioni ad esse dedicate (getter e setter).
Ad esempio per la property “label” di un Button, ci sono 2 funzioni, la getter Gtk.Button.get_label()
e la setter Gtk.Button.set_label(label).
Creare nuove properties
Una property viene definita tramite “name” e “type”.
Nonostante Python stesso sia tipizzato dinamicamente, non potremo modificare una property,
una volta che questa è stata definita. Per creare una property utilizzaiamo GObject.Property:
from gi.repository import GObject
class CustomObject(GObject.GObject):
pr_string = GObject.Property(type=str, default='bancaldo')
pr_float = GObject.Property(type=float)
def __init__(self):
super().__init__()
Possiamo decidere che una property sia “readable”, “writable”, o “readwrite”.
Per farlo è necessario settare alcuni flags, in fase di definizione della property stessa.
Queste Flags sono:
GObject.ParamFlags.READABLE: solo accesso in lettura;
GObject.ParamFlags.WRITABLE: solo accesso in scrittura;
GObject.ParamFlags.READWRITE: property pubblica, con accesso in
lettura e scrittura.
pr_1 = GObject.Property(type=str, flags = GObject.ParamFlags.READABLE) # non scrivibile pr_2 = GObject.Property(type=str, flags = GObject.ParamFlags.WRITABLE) # non leggibile
Per definire una nuova property read-only possiamo utilizzare un metodo
con decoratore GObject.Property:
from gi.repository import GObject
class CustomObject(GObject.GObject):
def __init__(self):
super().__init__()
@GObject.Property
def readonly(self):
return 'This is read-only property.'
Per accedere a questa property:
>>> myobj = CustomObject()
>>> myobj.readonly
'This is read-only property.'
>>> myobj.get_property("readonly")
'This is read-only property.'
La API di GObject.Property è molto simile alla built-in property() di python.
Possiamo creare i setter in maniera simile:
class CustomObject(GObject.Object):
value = 0
@GObject.Property
def readonly(self):
'Read only property.'
return 1
@GObject.Property(type=int)
def my_int(self):
'Read-write integer property.'
return self.value
@my_int.setter
def my_int(self, value):
self.value = value
>>> myobj = CustomObject() >>> myobj.readonly 1 >>> myobj.my_int 0 >>> myobj.my_int = 2 >>> myobj.my_int 2
Ad esempio è possibile anche definire un valore minimo e massimo per i numeri:
from gi.repository import GObject
class CustomObject(GObject.GObject):
__gproperties__ = {
"int-prop": (int, # type
"integer prop", # nick
"A property that contains an integer", # desc
1, # min
5, # max
2, # default
GObject.ParamFlags.READWRITE # flags
),
}
def __init__(self):
super().__init__()
self.int_prop = 2
def do_get_property(self, prop):
return self.int_prop
def do_set_property(self, prop, value):
self.int_prop = value
Le properties, come si nota, vanno definite nel dizionario __gproperties__ di
GObject.GObject, e gestite con i metodi:
do_get_property e do_set_property.
>>> obj = CustomObject()
>>> obj.get_property("int-prop")
2
>>> obj.set_property("int-prop", 10)
:1: Warning: value "10" of type 'gint' is invalid or out of range for property 'int-prop' of type 'gint'
>>> obj.set_property("int-prop", -2)
:1: Warning: value "-2" of type 'gint' is invalid or out of range for property 'int-prop' of type 'gint'
>>> obj.set_property("int-prop", 4)
>>> obj.get_property("int-prop")
4
se la property richiesta non è esistente, ovvero non fa parte del dizionario __gproperties__,
verrà sollevata una eccezione TypeError:
obj = CustomObject()
myprop = "int-propp"
try:
obj.get_property(myprop)
except TypeError:
print("ERROR: %s property not found!" % myprop)
ERROR: int-propp property not found!
Segnale modifica property
Quando una property viene modificata, viene emesso un segnale il cui nome è
“notify::property-name”.
E’ quindi possibile connettere il segnale di modifica della property, del nostro oggetto, ad una
callback, con il metodo connect(signal, callback):
>>> def on_notify_int_prop(obj, string):
... print("INFO: 'int-prop' property changed")
...
>>> obj.connect("notify::int-prop", on_notify_int_prop)
1
>>> obj.set_property("int-prop", 2)
INFO: 'int-prop' property changed
Nota:
Per convenzione il nome della callback da usare con il metodo connect(), per un segnale
“notify::property-name”, sarà “on_notify_property_name”.
API
Ricapitolando vediamo i metodi principali della classe GObject.GObject:
get_property(property_name)
Recupera il valore di una property di nome “property_name”.
set_property(property_name, value)
Setta il valore di una property di nome “property_name” al valore “value”, passato come argomento.
emit(signal_name, …)
Emette un segnale di nome “signal_name”. Gli argomenti opzionali da passare al segnale devono
seguire “signal_name”. Se ad esempio il nostro segnale è di tipo (int,), viene emesso come segue:
self.emit(signal_name, 42)
freeze_notify()
Questo metodo congela tutti i segnali “notify::” (che vengono cioè emessi ogni volta che una
property viene modificata), finchè non viene invocato il metodo thaw_notify().
E’ consigliato utilizzare il metodo freeze_notify(), all’interno di un
with statement, in modo da assicurarsi che il metodo thaw_notify(),
sia invocato implicitamente alla fine del blocco with utilizzato.
with an_object.freeze_notify():
# Do stuff
...
thaw_notify()
“scongela” tutti i segnali “notify::” che erano stati congelati dal metodo freeze_notify().
Come detto in precedenza non è consigliato utilizzare thaw_notify() esplicitamente,
ma utilizzare freeze_notify() con un with statement.
handler_block(handler_id)
Blocca un handler di un’istanza che non potrà essere chiamato durante l’emissione di un segnale
che lo coinvolga, fino a chè non sarà chiamato il complementare handler_unblock().
Questo blocco significa disattivare l’handler temporaneamente.
Un signal-handler deve essere sbloccato lo stesso numero di volte che è stato bloccato, prima di
tornare attivo. Come per freeze/thaw, è raccomandato utilizzare handler_block()
all’interno di un with statement, che, raggiunta la fine, chiamerà implicitamente
handler_unblock():
with an_object.handler_block(handler_id):
# Do stuff
...
handler_unblock(handler_id)
Annulla l’effetto di handler_block(). Un handler boccato viene saltato durante
l’emissione di un segnale e non sarà invocato fino a quando non verrà sbloccato lo stesso numero
di volte per cui è stato bloccato.
Come già visto non è consigliabile chiamare handler_unblock() esplicitamente,
ma usare handler_block() all’interno di un with statement.
__gsignals__
Un dizionario dove le classi ereditate possono definire nuovi segnali.
Ogni elemento nel dizionario è un nuovo segnale. La chiave è il nome del segnale, il valore
invece, una tupla con la forma (GObject.SIGNAL_RUN_FIRST, None, (int,))
GObject.SIGNAL_RUN_FIRST: può essere rimpiazzato con
GObject.SIGNAL_RUN_LAST o GObject.SIGNAL_RUN_CLEANUP.
None: ciò che ritorna quel segnale;
(int,): lista dei parametri del segnale, deve finire con virgola.
__gproperties__
Un dizionario dove è possibile definire le properties del nostro oggetto.
Questo non è il metodo raccomandato per definire nuove proprietà, ma è utile per aggiungere
caratteristiche supplementari come valore minimo e massimo ammessi.
La chiave è il nome della property, mentre il valore è una tupla che descrive tale property.
Il numero degli elementi di questa tupa è variabile e dipende dal primo elemento, ma la tuple
conterrà sempre, almeno i seguenti elementi in questo ordine:
property’s type esmepio int, float,
property’s nick name: una breve descrizione della property
(utilizzato da programmi come Glade);
property’s description (blurb): un’altra stringa con descrizione
più esaustiva (usata da Glade e programmi simili);
property’s flags: indica il tipo di accesso alla property,
GObject.PARAM_READABLE, GObject.PARAM_WRITABLE o GObject.PARAM_READWRITE;
In base al primo elemento della tupla (property’s type), possono seguire altri elementi.
gli scenari sono:
– il primo elemento è di tipo bool o str, l’elemento successivo sarà:
default: valore di default della property;
– il type è int o float:
minimum: il minimo valore accettato,
maximum: il valore massimo accettato;
default: valore di default della property;
– il type non è nessuno di essi: nessun extra elemento
GObject.SIGNAL_RUN_FIRST
Invoca il method handler dell’oggetto nel primo stadio dell’emissione;
GObject.SIGNAL_RUN_LAST
Invoca il method handler dell’oggetto nel terzo stadio dell’emissione;
GObject.SIGNAL_RUN_CLEANUP
Invoca il method handler dell’oggetto nell’ultimo stadio dell’emissione;
GObject.ParamFlags.READABLE
La property è in sola lettura e non soggetta a modifica;
GObject.ParamFlags.WRITABLE
La property è in scrittura e quindi soggetta a modifica;
GObject.ParamFlags.READWRITE
La property è in lettura e scrittura (pubblica);
Unicode
Da Python3.0, tutte le stringhe sono memorizzate come Unicode in un’istanza di str type.
Le Encoded strings, d’altro canto, sono rappresentate come binary data, in forma di istanza di byte type.
In parole povere str fa riferimento a text, mentre bytes
fa riferimento a data.
Per convertire da str a bytes, usare str.encode(),
da bytes a str, usare bytes.decode().
Inoltre non è più possibile mixare strings con encoded strings:
>>> s = "àòè"
>>> s.encode()
b'\xc3\xa0\xc3\xb2\xc3\xa8'
>>> s.encode("utf-8")
b'\xc3\xa0\xc3\xb2\xc3\xa8'
>>> b = s.encode("utf-8")
>>> b
b'\xc3\xa0\xc3\xb2\xc3\xa8'
>>> b.decode("utf-8")
'àòè'
In GTK+ le cose sono molto più comode perchè PyGObject fa automaticamente l’encode/decode da/in
UTF-8, quando passeremo una stringa ad un metodo, o un metodo ritornerà una stringa.
In ogni caso verrà sempre rappresentato un testo/stringa come instanza di str:
>>> import gi
>>> gi.require_version("Gtk", "3.0")
>>> from gi.repository import Gtk
>>> label = Gtk.Label()
>>> text = "\xc3\xa7\xc3\xa7\xc3\xa7"
>>> label.set_text(text)
>>> txt = label.get_text()
>>> type(txt), txt
(, 'ççç')
>>> txt == text
True
link di riferimento:
torna all’indice degi appunti
python gtk3 tutorial
Gtk3
PyGObject: Drag and Drop
torna all’indice degli appunti
Drag and drop
Impostare un Drag and Drop tra widgets consiste nel selezionare un Drag Source,
ovvero il widget dal quale cominceremo il Drag, selezionare un Drag Destination,
ovvero il widget sul quale eseguiremo il Drop, gestire i segnali su entrambi i widget.
In maniera molto generica, un Drag Source viene selezionato con il metodo
Gtk.Widget.drag_source_set(),
mentre il Drag Destination, viene selezionato con il metodo
Gtk.Widget.drag_dest_set().
Alcuni widget specializzati, come Gtk.TreeView and Gtk.IconView, usano metodi specifici per questa
operazione.
Un drag and drop basico richiede che il source sia connesso al segnale “drag-data-get”
e il destination sia connesso al segnale “drag-data-received”.
Se invece abbiamo bisogno di maggior complessità, come aree di drop specifiche, o icone di drag
personalizzate, sarà necessaria la connessione a segnali aggiuntivi e dovremo interagire con
l’oggetto Gdk.DragContext.
Per trasferire dati tra source e destination, dobbiamo
interagire con la variabile Gtk.SelectionData fornita nei segnali “drag-data-get”
e “drag-data-received”, usando i metodi getter e setter di Gtk.SelectionData.
Target Entries
Per permettere al drag source e al destination di conoscere quali dati stanno rispettivamente
spedendo e ricevendo, è necessaria una lista comune di Gtk.TargetEntry.
Possiamo costruirla creando direttamente una lista di istanze Gtk.TargetEntry, o creando
un oggetto Gtk.TargetList:
>>> targets = [
... Gtk.TargetEntry.new("STRING", Gtk.TargetFlags.SAME_APP, 0),
... Gtk.TargetEntry.new("image/png", Gtk.TargetFlags.SAME_APP, 1),
... ]
>>> targets = Gtk.TargetList.new([
... Gtk.TargetEntry.new("STRING", Gtk.TargetFlags.SAME_APP, 0),
... Gtk.TargetEntry.new("image/png", Gtk.TargetFlags.SAME_APP, 1),
... ])
>>> targets.find(Gdk.Atom.intern_static_string("STRING"))
(True, info=0)
Oppure utilizzare i metodi che mette a disposizione la classe Gtk.TargetList:
Gtk.TargetList.add_image_targets(info, writable), Gtk.TargetList.add_text_targets(info), ecc.
Una volta creata la lista targets e abilitati i widget all’operazione di drag and drop con
i metodi enable_model_drag_source(button_mask, targets, actions) ed
enable_model_drag_dest(targets, actions), non resta che associarla ai widget
source e destination, preposti al drag and drop, con i metodi drag_dest_set_target_list(targets) e
drag_source_set_target_list(targets).
>>> drag_source = Gtk.IconView() >>> drag_source.enable_model_drag_source(start_button_mask=Gdk.ModifierType.BUTTON1_MASK, targets=[], ... actions=Gdk.DragAction.COPY) >>> drag_dest = Gtk.IconView() >>> drag_dest.enable_model_drag_dest(targets=[], actions=Gdk.DragAction.COPY) >>> drag_source.drag_source_set_target_list(targets) >>> drag_dest.drag_dest_set_target_list(targets)
Segnali
Drag Source Signals:
| Name | Emesso | Scopo |
|---|---|---|
| drag-begin | Quando lo User unizia il drag | Setta la icona di drag |
| drag-data-get | Quando i dati sono richiesti dal destination | Trasferisce i dati del drag da source a destination |
| drag-data-delete | Quando un drag con la action Gdk.DragAction.MOVE è completata | Elimina i dati dal source per completare il “move” |
| drag-end | Quando il drag è completo | Anunlla quello fatto in drag-begin |
Drag Destination Signals:
| Name | Emesso | Scopo |
|---|---|---|
| drag-motion | Quando la icon Drag va sopra un’area di drop | Permette di eseguire il drop solo su certe aree |
| drag-drop | Quando la icona viene lasciata su un’area di drop | Permette di eseguire il drop solo su certe aree |
| drag-data-received | Quando i dati di drag sono ricevuti dal destination | Trasferisce i dati del drag da source a destination |
Ecco un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gdk, GdkPixbuf
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Drag and Drop Example")
self.set_default_size(300, 400)
label_source = Gtk.Label(label="Drag source")
label_destination = Gtk.Label(label="Drop Area")
self.drag_source = DragSourceIconView() # Source widget
self.drag_dest = DragDestination() # Destination widget
button_img = Gtk.RadioButton.new_with_label_from_widget(
None, "Drag image only")
button_text = Gtk.RadioButton.new_with_label_from_widget(
button_img, "Drag text only")
# layout
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
label_box = Gtk.Box(spacing=12)
label_box.pack_start(label_source, True, True, 0)
label_box.pack_start(label_destination, True, True, 0)
dnd_box = Gtk.Box(spacing=5)
dnd_box.pack_start(self.drag_source, True, True, 0)
dnd_box.pack_start(self.drag_dest, True, True, 0)
button_box = Gtk.Box(spacing=6)
button_box.pack_start(button_img, True, False, 0)
button_box.pack_start(button_text, True, False, 0)
vbox.pack_start(label_box, True, False, 0)
vbox.pack_start(dnd_box, True, False, 0)
vbox.pack_start(button_box, True, False, 0)
self.add(vbox)
# bindings
button_img.connect("toggled", self.add_image_targets)
button_text.connect("toggled", self.add_text_targets)
self.add_image_targets()
def add_image_targets(self, button=None):
targets = Gtk.TargetList.new([])
targets.add_image_targets(info=1, writable=True)
self.drag_dest.drag_dest_set_target_list(targets)
self.drag_source.drag_source_set_target_list(targets)
def add_text_targets(self, button=None):
targets = Gtk.TargetList.new([])
targets.add_text_targets(info=0)
self.drag_dest.drag_dest_set_target_list(targets)
self.drag_source.drag_source_set_target_list(targets)
class DragSourceIconView(Gtk.IconView):
def __init__(self):
super().__init__()
self.set_text_column(0)
self.set_pixbuf_column(1)
model = Gtk.ListStore(str, GdkPixbuf.Pixbuf)
self.set_model(model)
for text, icon in [("Item 1", "image-missing"),
("Item 2", "help-about"), ("Item 3", "edit-copy")]:
pixbuf = Gtk.IconTheme.get_default().load_icon(icon, 32, 0)
self.get_model().append([text, pixbuf])
self.enable_model_drag_source(
start_button_mask=Gdk.ModifierType.BUTTON1_MASK, targets=[],
actions=Gdk.DragAction.COPY)
# bindings
self.connect("drag-data-get", self.on_drag_data_get)
def on_drag_data_get(self, widget, drag_context, data, info, time):
selected_path = self.get_selected_items()[0]
selected_iter = self.get_model().get_iter(selected_path)
if info == 0:
text = self.get_model().get_value(selected_iter, 0)
data.set_text(text, -1)
elif info == 1:
pixbuf = self.get_model().get_value(selected_iter, 1)
data.set_pixbuf(pixbuf)
class DragDestination(Gtk.IconView):
def __init__(self):
super().__init__()
self.set_text_column(0)
self.set_pixbuf_column(1)
model = Gtk.ListStore(str, GdkPixbuf.Pixbuf)
self.set_model(model)
self.enable_model_drag_dest(targets=[], actions=Gdk.DragAction.COPY)
# bindings
self.connect("drag-data-received", self.on_drag_data_received)
def on_drag_data_received(self, w, context, x, y, data, info, time, *args):
model = w.get_model()
pixbuf = text = None
if info == 0:
text = data.get_text() # None if 'only image' is toggled
elif info == 1:
pixbuf = data.get_pixbuf() # None if 'only text' is toggled
model.append([text, pixbuf])
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.Notebook
torna all’indice degli appunti
Notebook
Il widget Gtk.Notebook è un Gtk.Container i cui widget child sono pagine sulle
quali posso spostarmi agilmente semplicemente utilizzando i tab presenti sul proprio bordo.
E’ possibile scegliere su quale bordo posizionare i tabs utilizzando il metodo .set_tab_pos(),
qualora invece i tabs dovessere essere troppi, rispetto allo spazio disponibile, potremo
aggiungere le scrolling arrows, utilizzando il metodo set_scrollable().
Infine sarà possibile aggiungere dei popup menu con il metodo popup_enable().
Le properties ereditate da Gtk.Container sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| enable-popup | bool | r/w/en | Se True, premendo con il bottone destro del mouse apparirà un popup menu che permetterà di scegliere la pagina su cui spostarsi |
| group-name | str | r/w/en | Il nome del Group per il drag and drop dei tab |
| page | int | r/w/en | l’indice della pagina corrente |
| scrollable | bool | r/w/en | Se True, abilitiamo le scroll arrows da usare se ci sono troppe tabs |
| show-border | bool | r/w/en | Se visualizzare il bordo |
| show-tabs | bool | r/w/en | Se visualizzare i tabs |
| tab-pos | Gtk.PositionType | r/w/en | Su quale bordo del notebook mettere i tabs |
Le properties relative ai children sono:
| Name | Type | Default | Flags | Short Description |
|---|---|---|---|---|
| detachable | bool | False | r/w | se il tab è “staccabile” |
| menu-label | str | None | r/w | la label visualizzata nel menu entry del child |
| position | int | 0 | r/w | L’indice del child nel notebook |
| reorderable | bool | False | r/w | Se il tab è is riordinabile |
| tab-expand | bool | False | r/w | Se espandere il tab del child |
| tab-fill | bool | True | r/w | Se il tab del child riempie lo spazio allocato |
| tab-label | str | None | r/w | La label visualizzata sul tab del child |
Segnali
I principali segnali sono:
| Name | Short Description |
|---|---|
| create-window | Il segnale “create-window” viene emesso quando un tab “detachable” viene rimosso dalla root window |
| page-added | Il segnale “page-added” viene emesso nel notebook appena una pagina viene aggiunta al notebook |
| page-removed | Il segnale “page-removed” viene emesso quando una pagina viene rimossa dal notebook |
| page-reordered | Il segnale “page-reordered” viene emesso quando la pagine vengono riordinate |
| switch-page | Emesso quando lo User o una funzione, cambia la pagina corrente |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.Notebook,
i principali metodi sono:
new()
Crea un nuovo widget Gtk.Notebook privo di pagine.
append_page(child, tab_label)
Aggiunge una pagina (append) al notebook e ritorna l’indice della pagina.
Se l’operazione fallisce, il metodo ritorna -1.
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
>>> notebook = Gtk.Notebook.new()
>>> page_1 = Gtk.Label(label="First content")
>>> notebook.append_page(child=page_1, tab_label=Gtk.Label(label='First Page'))
0
Parametri:
child: il widget da utilizzare come contenuto della pagina;
tab_label: il widget da usare come label della pagina, o None
per usare la label di default “page N”;
append_page_menu(child, tab_label, menu_label)
Aggiunge una pagina (append) al notebook specificando il widget da usare come label nel popup
menu. Se l’operazione fallisce, il metodo ritorna -1.
Parametri:
child: il widget da utilizzare come contenuto della pagina;
tab_label: il widget da usare come label della pagina, o None
per usare la label di default “page N”;
menu_label: il widget da usare come label per il page-switch menu,
se questo è abilitato. Se menu_label=None e tab_label è un widget Gtk.Label (o None), allora la
label del menu sarà una nuova label creata con lo stesso testo di tab_label;
se invece tab_label non è una Gtk.Label, menu_label deve essere specificato in caso di utilizzo
del page-switch menu;
detach_tab(child)
Rimuove un child dal notebook.
>>> page_temp = Gtk.Label(label="Temp content") >>> notebook.append_page(child=page_temp, tab_label=Gtk.Label(label='Temp Page')) 1 >>> notebook.get_children() [<Gtk.Label object at 0x000000000583ae80 (GtkLabel at 0x0000000004d851f0)>, <Gtk.Label object at 0x0000000005815200 (GtkLabel at 0x0000000004d85530)>] >>> notebook.detach_tab(page_temp) >>> notebook.get_children() [<Gtk.Label object at 0x000000000583ae80 (GtkLabel at 0x0000000004d851f0)>]
Parametri:
child: il widget che rappresenta il child da rimuovere.
get_action_widget(pack_type)
Ritorna l’action widget con il pack_type passato come argomento, o None se non è stato settato
alcun action widget. Vedere Gtk.Notebook.set_action_widget().
Parametri:
pack_type: il Gtk.PackType dell’action widget;
L’enum Gtk.PackType rappresenta il tipo di impacchettamento, che può essere: START (0) o END (1).
get_current_page()
Ritorna il numero della pagina corrente del Notebook. Se il notebook non ha ancora pagine, il
metodo ritornerà -1.
get_group_name()
Ritorna il nome del Group corrente.
get_menu_label(child)
Ritorna la label del menu se presente, o None se la pagina del notebook non ha label di menu che
non siano quelle di default (la label del Tab).
>>> notebook.get_menu_label(page_1) >>> page_2 = Gtk.Label(label="Second content") >>> notebook.append_page_menu(child=page_2, tab_label=Gtk.Label(label='Second Page'), ... menu_label=Gtk.Label(label='Second page menu label')) 1 >>> notebook.get_menu_label(page_2) <Gtk.Label object at 0x000000000571bd40 (GtkLabel at 0x0000000004d85a10)>
Parametri:
child: il widget contenuto in una pagina del notebook;
get_menu_label_text(child)
Ritorna il testo della label del menu relativo alla pagina passata in argomento.
>>> notebook.get_menu_label_text(page_2) 'Second page menu label'
Parametri:
child: il widget contenuto in una pagina del notebook;
get_n_pages()
Ritorna il numero di pagine del notebook.
get_nth_page(page_num)
Ritorna il child widget della pagina con l’indice passato come argomento, o None.
>>> notebook.get_nth_page(0) <Gtk.Label object at 0x000000000583ae80 (GtkLabel at 0x0000000004d851f0)>
Parametri:
page_num: l’indice della pagina nel notebook o -1 per ritornare
l’ultima pagina;
get_scrollable()
Ritorna True se sono presenti le scrollabe arrows nell’area dei tabs.
Vedere Gtk.Notebook.set_scrollable() per il settaggio.
get_show_border()
Ritorna True se viene disegnato il bordo del notebook.
Vedere Gtk.Notebook.set_show_border() per il settaggio.
get_show_tabs()
Ritorna True se vengono visualizzati i tabs.
Vedere Notebook.set_show_tabs() per il settaggio.
get_tab_detachable(child)
Ritorna True se il tab relativo al child passato in argomento, è “staccabile”.
Parametri:
child: il child widget di cui vogliamo la caratteristica del tab;
get_tab_label(child)
Ritorna il widget che fa da label al tab, del child passato come argomento.
>>> notebook.get_tab_label(page_1) <Gtk.Label object at 0x0000000005815080 (GtkLabel at 0x0000000004d85390)>
Parametri:
child: la pagina della quale vogliamo il widget label del tab;
get_tab_label_text(child)
Ritorna il testo della label, del tab, del child passato come argomento.
>>> notebook.get_tab_label_text(page_1) 'First Page'
Parametri:
child: la pagina della quale vogliamo il testo della tab label;
get_tab_pos()
Ritorna il Gtk.PositionType che rappresenta il bordo sul quale appaiono i tabs.
>>> notebook.get_tab_pos() <enum GTK_POS_TOP of type Gtk.PositionType>
get_tab_reorderable(child)
Ritorna True se il tab del child passato come argomento, può essere riordinato via drag and drop.
insert_page(child, tab_label, position)
Inserisce una pagina nel notebook, alla posizione specificata.
Parametri:
child: il widget usato come contenuto della pagina;
tab_label: il widget usato come label per la pagina, o None
per utilizzare la label di default “page N”;
position: l’indice (partendo da 0) al quale inserire la pagina.
Passando -1, la pagina verrà inserita alla fine (append);
insert_page_menu(child, tab_label, menu_label, position)
Inserisce una pagina alla posizione specificata, specificando anche il widget da usare come label
nel popup menu.
Parametri:
child: il widget usato come contenuto della pagina;
tab_label: il widget usato come label per la pagina, o None
per utilizzare la label di default “page N”;
menu_label: il widget da usare come label per il page-switch menu,
se questo è abilitato. Se menu_label=None e tab_label è un widget Gtk.Label (o None), allora la
label del menu sarà una nuova label creata con lo stesso testo di tab_label;
se invece tab_label non è una Gtk.Label, menu_label deve essere specificato in caso di utilizzo
del page-switch menu;
position: l’indice (partendo da 0) al quale inserire la pagina.
Passando -1, la pagina verrà inserita alla fine (append);
next_page()
Passa alla pagina successiva. Se siamo già all’ultima, non succede nulla.
page_num(child)
Ritorna l’indice della pagina che contiene il child passato come argomento.
Se il child non è nel notebook, il metodo ritorna -1.
Parametri:
child: il widget di cui vogliamo l’indice nel notebook;
popup_disable()
Disabilita il popup menu.
popup_enable()
Abilita il popup menu: se lo user clicca con il bottone destro sui tabs, apparirà un menu con
tutte le pagine del notebook.
prepend_page(child, tab_label)
Antepone una pagina al notebook.
Parametri:
child: il widget usato come contenuto della pagina;
tab_label: il widget usato come label per la pagina, o None
per utilizzare la label di default “page N”;
prepend_page_menu(child, tab_label, menu_label)
Antepone una pagina al notebook, specificando il widget da usare come label nel popup menu.
Parametri:
child: il widget usato come contenuto della pagina;
tab_label: il widget usato come label per la pagina, o None
per utilizzare la label di default “page N”;
menu_label: il widget da usare come label per il page-switch menu,
se questo è abilitato. Se menu_label=None e tab_label è un widget Gtk.Label (o None), allora la
label del menu sarà una nuova label creata con lo stesso testo di tab_label;
se invece tab_label non è una Gtk.Label, menu_label deve essere specificato in caso di utilizzo
del page-switch menu;
prev_page()
Passa alla pagina precedente. Se siamo nella prima pagina, non succede nulla.
remove_page(page_num)
Rimuove la pagina specificata dall’indice passato come argomento.
Parametri:
page_num: l’indice della pagina del notebook (partendo da 0) da
rimuovere. Se page_num = -1, verrà rimossa l’ultima pagina.
reorder_child(child, position)
Riordina la pagina contenente il child passato in argomento, cosicchè appaia nella posizione
specificata. Se position è maggiore o uguale al numero di children nella lista o -1, il child
specificato verrà spostato alla fine della lista.
Parametri:
child: il widget child da spostare;
position: la nuova positione in cui spostare il child, o -1
per spostare il child alla fine;
set_action_widget(widget, pack_type)
Setta il widget come appartenente al gruppo degli action widgets. A seconda del tipo di pack type,
il widget sarà posizionato prima o dopo i tabs. Nel caso si vogliano impacchettare più widget
dallo stesso lato, utilizzare un widget contenitore come Gtk.Box.
Notare che gli action widgets con child “interni” del notebook, quindi non sono inclusi nella
lista di children ritornata con il metodo Gtk.Container.foreach().
Parametri:
widget: un Gtk.Widget da settare come action widget;
pack_type: il tipo di Gtk.PackType dell’action widget;
set_current_page(page_num)
Passa alla pagina indicata dall’indice passato come argomento. Questa diventa la pagina corrente.
Parametri:
page_num: l’indice della pagina a cui passare (partendo da 0).
Se l’indice è -1, la pagina corrente diventerà l’ultima. Se l’indice è maggiore del numero di
pagine presenti nel notebook, non accadrà nulla.
set_group_name(group_name)
Setta un group name per il notebook. I Notebook con lo stesso group name potranno scambiarsi
i tabs tramite drag and drop.
Parametri:
group_name: il group name da associare al group;
set_menu_label(child, menu_label)
Setta il widget della label, del menu, della pagina contenente il child passato come argomento.
Parametri:
child: il widget usato come contenuto della pagina;
menu_label: il widget della label del menu, o None per il default;
set_menu_label_text(child, menu_text)
Setta il testo della label, del menu, della pagina contenente il child passato come argomento.
Parametri:
child: il widget usato come contenuto della pagina;
menu_text: il testo della label del menu;
set_scrollable(scrollable)
Setta la presenza o meno delle scrolling arrows, in caso ci siano più tabs dello spazio
disponibile nella tab area del notebook.
Parametri:
scrollable: il boolean che settato a True visualizza le scrollable
arrows;
set_show_border(show_border)
Settato a True visualizza il bordo attorno alle pagine del notebook.
Parametri:
show_border: il boolean che settato a True visualizza il bordo;
set_show_tabs(show_tabs)
Settato a True visualizza i tabs.
Parametri:
show_tabs: il boolean che settato a True visualizza i tabs;
set_tab_detachable(child, detachable)
Settato a True permette al tab di essere svincolato dal notebook per un altro notebook o widget.
Ovviamente perchè questo passaggio accada, i due notebooks devono condividere lo stesso name group
(vedi Gtk.Notebook.set_group_name()), così facendo i tabs potranno essere intercambiabili.
Se vogliamo che un widget interagisca con il notebook via Drag and Drop (ad esempio accetti i tabs
trascinati dal notebook stesso), dobbiamo settarlo come drop destination e accettare
il target “GTK_NOTEBOOK_TAB”. Così facendo il notebook salverà sulla selection
(Gtk.SelectionData) il child widget corrispondente al tab rimosso dal notebook.
Quando dovremo rimuovere il tab dal notebook (source), per completare l’operazione di drag and
drop sul widget (destination), dovremo utilizzare il metodo Gtk.Notebook.detach_tab().
Il drag and drop tra differenti notebook non è automatico, quindi dovremo codificarlo manualmente.
Parametri:
child: il widget che vogliamo rendere svincolabile;
detachable: il boolean che settato a True rende il tab detachable;
set_tab_label(child, tab_label)
Modifica il widget della label del tab, del child passato come argomento.
Se tab_label è None verrà utilizzata la label di default “page N”.
Parametri:
child: il widget usato per il contenuto della pagina;
tab_label: il widget della label del tab, o None per il default;
set_tab_label_text(child, tab_text)
Modifica il testo della label del tab, del child passato come argomento.
Parametri:
child: il widget usato per il contenuto della pagina;
tab_text: il testo della label;
set_tab_pos(pos)
Setta la posizione dove verranno visualizzati i tabs per spostarsi tra le pagine.
Parametri:
pos: l’enum Gtk.PositionType che indica il bordo dove verranno
visualizzati i tabs. I valori di Gtk.PositionType possono essere:
LEFT (0): i tabs vengono visualizzati sul bordo sinistro del notebook;
RIGHT (1): i tabs vengono visualizzati sul bordo destro del notebook;
TOP (2): i tabs vengono visualizzati nella parte superiore del notebook;
BOTTOM (3): i tabs vengono visualizzati nella parte inferiore del notebook;
set_tab_reorderable(child, reorderable)
Settato a True rende il tab del child passato come argomento, riordinabile tramite drag and drop.
Parametri:
child: il widget usato per il contenuto della pagina;
reorderable: il boolean che rende il tab riordinabile o meno;
Ecco un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Simple Notebook Example")
self.set_border_width(3)
self.set_default_size(200, 200)
notebook = Gtk.Notebook.new()
notebook.popup_enable()
page_1 = Gtk.Box()
page_1.set_border_width(10)
page_1.add(Gtk.Label(label='Default Page!'))
notebook.append_page_menu(child=page_1,
tab_label=Gtk.Label(label='Plain Title'),
menu_label=Gtk.Label(label='First Page'))
page_2 = Gtk.Box()
page_2.set_border_width(10)
page_2.add(Gtk.Label(label='A page with an image for a Title.'))
image = Gtk.Image.new_from_icon_name("go-next", Gtk.IconSize.MENU)
notebook.append_page_menu(child=page_2, tab_label=image,
menu_label=Gtk.Label(label='Second Page'))
notebook.set_tab_reorderable(page_2, True)
self.add(notebook)
#bindings
notebook.connect("switch-page", self.on_change_cur_page)
def on_change_cur_page(self, notebook, page, page_num):
print("INFO: current page is '%s'" % notebook.get_menu_label_text(page))
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.IconView
torna all’indice degli 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:
PyGObject: Gtk.TextView
torna all’indice degli appunti
TextView
Il widget Gtk.TextView viene utilizzato per visualizzare e modificare una grande quantità di
testo formattato. Come il Gtk.TreeView, sposa il pattern model/view.
In questo caso il Gtk.TextBuffer è il model che rappresenta il testo che deve
essere modificato. Questo permette a due o più widget Gtk.TextView di condividere lo stesso
Gtk.TextBuffer e permette a questi text buffers di essere visualizzati in maniera differente.
View
Il Gtk.TextView è il frontend con il quale lo user può aggiungere, editare e cancellare i dati
in formato testo. Viene comunemente usato per editare linee multiple di testo.
Quando creiamo un Gtk.TextView questo contiene il proprio Gtk.TextBuffer di default, al quale
possiamo accedere con il metodo Gtk.TextView.get_buffer().
Di default, il testo può essere aggiunto, editato e rimosso dal Gtk.TextView.
E’ possibile disabilitare questa caratteristica chiamando il metodo Gtk.TextView.set_editable().
Se il testo non è editabile può essere utile nascondere il cursore con il metodo
Gtk.TextView.set_cursor_visible().
E’ settabile anche il tipo di giustificazione, con il metodo Gtk.TextView.set_justification():
Gtk.Justification.LEFT): visualizza il testo giustificato a sinistra;
Gtk.Justification.RIGHT: visualizza il testo giustificato a destra;
Gtk.Justification.CENTER: visualizza il testo centrato;
Gtk.Justification.FILL: visualizza il testo riempiendo la riga.
Un altro settaggio di default è che le righe di testo molto lunghe, continuino orizzontalmente
oltre il bordo del TextView, fino a che non incontriamo un break.
Se vogliamo “wrappare” il testo per prevenire la fuoriuscita del testo dal bordo, utilizzare il
metodo Gtk.TextView.set_wrap_mode().
Model
Il Gtk.TextBuffer è il cuore del widget Gtk.TextView e viene usato per gestire
ogni aspetto del testo visualizzato nel Gtk.TextView.
Il settaggio del contenuto del TextBuffer è possibile con il metodo Gtk.TextBuffer.set_text(),
mentre per ottenerne il contenuto si utilizza il metodo Gtk.TextBuffer.get_text().
La maggiorparte delle manipolazioni del testo si ottengono con l’uso degli iterators,
rappresentati da istanze di Gtk.TextIter.
Un iterator rappresenta la posizione tra due caratteri in un text buffer.
Ogni volta che il buffer viene modificato nel proprio contenuto, tutti gli iterators
precedentemente creati, diventano invalidi.
Quindi gli iterators non possono essere usati per preservare la posizione durante le modifiche del
buffer. Per mantenere la posizione utilizzare un Gtk.TextMark.
Un text buffer contiene due built-in marks; un “insert” mark (che rappresenta la posizione del
cursoe) e il “selection_bound” mark. Entrambi possono essere recuperati rispettivamente con i
metodi Gtk.TextBuffer.get_insert() e Gtk.TextBuffer.get_selection_bound().
Di default, la posizione di un Gtk.TextMark non è mostrata, ma si può fare diversamente chiamando
il metodo Gtk.TextMark.set_visible().
Esistono molti metodi per recuperare un Gtk.TextIter.
Per esempio Gtk.TextBuffer.get_start_iter() ritorna un iterator che indica la
prima posizione nel text buffer, mentre Gtk.TextBuffer.get_end_iter(), ritorna un
iterator che indica l’ultimo carattere valido.
Per ottenere i limiti del testo selezionato si può utilizzare il metodo
Gtk.TextBuffer.get_selection_bounds().
Per inserire un testo in una posizione specifica, utilizzare il metodo Gtk.TextBuffer.insert().
Per inserire invece un testo nella posizione del cursore, usare Gtk.TextBuffer.insert_at_cursor().
Per rimuovere porzioni di text buffer usare il metodo Gtk.TextBuffer.delete().
Gtk.TextIter può anche essere usato per trovare testi nel buffer, usando la ricerca “in avanti”
con il metodo Gtk.TextIter.forward_search() e la ricerca all’indietro con il
metodo Gtk.TextIter.backward_search().
Tags
Il testo in un buffer può contenere i tags. Un tag è un attributo che può essere applicato ad una
porzione di testo. Ad esempio un tag chiamato “bold” permette alla porzione di testo racchiusa
tra i tags bold, di essere in grassetto. Qui il concetto è più generico, i tags non hanno effetto
solo sull’aspetto del testo, ma anche sul comportamento del mouse e sulla pressione dei tasti.
Ad esempio è possibile comprendere una porzione di testo tra tag ed evitare che questa possa
essere editata. Un tag viene rappresentato da un oggetto Gtk.TextTag.
Un singolo Gtk.TextTag può essere applicato a multiple porzioni di testo su multipli text buffers.
Ogni tag viene memorizzato in una Gtk.TextTagTable.
Una tagtable definisce un set di tags che possono essere usati insieme.
Ogni buffer ha una tagtable associata ad esso e solo i tags associati a tale tagtable possono
essere utilizzati su quel buffer. Una tagtable però può essere condivisa tra multipli buffers.
Per specificare che un testo nel buffer debba avere una specifica formattazione, dobbiamo definire
un tag con quelle informazioni di formattazione con il metodo Gtk.TextBuffer.create_tag()
e applicarlo al testo interessato con il metodo Gtk.TextBuffer.apply_tag():
tag = textbuffer.create_tag("orange_bg", background="orange")
textbuffer.apply_tag(tag, start_iter, end_iter)
Di seguito alcune delle properties più comuni
di text tag:
Background colour (“background” property)
Foreground colour (“foreground” property)
Underline (“underline” property)
Bold (“weight” property)
Italics (“style” property)
Strikethrough (“strikethrough” property)
Justification (“justification” property)
Size (“size” and “size-points” properties)
Text wrapping (“wrap-mode” property)
Per rimuovere un tag dal buffer si utilizza il metodo Gtk.TextBuffer.remove_tag();
per rimuovere invece tutti i tags di una regione, si usa il metodo Gtk.TextBuffer.remove_all_tags().
Le properties principali di Gtk.TextView sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| accepts-tab | bool | r/w/en | Se Tab risulta come inserimento di un carattere tab |
| bottom-margin | int | r/w/en | L’altezza del margine inferiore in pixels |
| buffer | Gtk.TextBuffer | r/w | Il buffer visualizzato |
| cursor-visible | bool | r/w/en | Se il cursore di inserimento è visibile |
| editable | bool | r/w/en | se il testo può essere modificato dallo user |
| im-module | str | r/w | Quale IM (input method) module usare |
| indent | int | r/w/en | La quantità di indentazione del paragrafo, in pixels |
| input-hints | Gtk.InputHints | r/w/en | Hints per il comportamento del campo di testo |
| input-purpose | Gtk.InputPurpose | r/w/en | Scopo del campo di testo |
| justification | Gtk.Justification | r/w/en | La giustificazione (Left, right, o center) |
| left-margin | int | r/w/en | Larghezza del margine sinistro in pixels |
| monospace | bool | r/w/en | Se usare un font monospace |
| overwrite | bool | r/w/en | Se il testo inserito sovrascrive quello esistente |
| pixels-above-lines | int | r/w/en | Pixels di spazio vuoto sopra i paragrafi |
| pixels-below-lines | int | r/w/en | Pixels di spazio vuoto sotto i paragrafi |
| pixels-inside-wrap | int | r/w/en | Pixels di spazio vuoto tra le wrapped lines di un paragrafo |
| populate-all | bool | r/w/en | Se emettere il segnale “populate-popup” |
| right-margin | int | r/w/en | Larghezza del margine destro in pixels |
| tabs | Pango.TabArray | r/w | tabs personalizzati per il testo |
| top-margin | int | r/w/en | L’altezza del margine superiore in pixels |
| wrap-mode | Gtk.WrapMode | r/w/en | Il wrap-mode utilizzato (never, word boundaries, o character boundaries) |
Le properties relative allo style:
| Name | Type | Default | Flags | Short Description |
|---|---|---|---|---|
| error-underline-color | Gdk.Color | None | r | Il colore con il quale indicare l’errore |
Segnali
I principali segnali sono:
| Name | Short Description |
|---|---|
| backspace | Il segnale “backspace” è un keybinding signal emesso quando lo user richiede il backspace |
| copy-clipboard | Il segnale “copy-clipboard” è un keybinding signal emesso per copiare la selezione al clipboard |
| cut-clipboard | Il segnale “cut-clipboard” è un keybinding signal emesso per “tagliare” la selezione al clipboard |
| delete-from-cursor | Il segnale “delete-from-cursor” signal è un keybinding signal emesso quando lo user inizia a cancellare il testo |
| extend-selection | Il segnale “extend-selection” viene emesso quando la selezione viene estesa |
| insert-at-cursor | Il segnale “insert-at-cursor” è un keybinding signal emesso quando lo user inizia l’inserimento di un testo alla posizione del cursor |
| insert-emoji | Il segnale “insert-emoji” è un keybinding signal emesso quando si attiva l’Emoji chooser |
| move-cursor | Il segnale “move-cursor” è un keybinding signal emesso quando lo user inizia a spostare il cursore |
| move-viewport | Il segnale “move-viewport” è un keybinding signal che può essere legato ad una combinazione di tasti con cui lo user muove il viewport |
| paste-clipboard | Il segnale “paste-clipboard” è un keybinding signal emesso per incollare il contenuto del clipboard nel textview |
| populate-popup | Il segnale “populate-popup” viene emesso prima di visualizzare il context menu del textview |
| preedit-changed | Se viene usato un input method, il testo digitato non verrà inserito immediatamente nel buffer |
| select-all | Il segnale “select-all” è un keybinding signal emesso per selezionare o deselezionare il contenuto completo del textview |
| set-anchor | Il segnale “set-anchor” è un keybinding signal emesso quando lo user setta l “anchor” mark |
| toggle-cursor-visible | Il segnale “toggle-cursor-visible” è un keybinding signal emesso quando cambia (toggle) la propertu “cursor-visible” |
| toggle-overwrite | Il segnale “toggle-overwrite” è un keybinding signal emesso quando cambia (toggle) l’overwrite mode del text view |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.TextView, i principali
metodi sono:
new()
Crea un nuovo widget Gtk.TextView. Se prima di utilizzare il textview, non chiamiamo il metodo
Gtk.TextView.set_buffer(), un buffer di default vuoto verrà creato.
Il buffer si ottiene con il getter Gtk.TextView.get_buffer().
Per creare un nuovo textview con un proprio buffer, è consigliato l’utilizzo del costruttore
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk, Pango
>>> textview = Gtk.TextView.new() # viene creato un buffer di default vuoto
>>> buffer = textview.get_buffer()
>>> buffer
<Gtk.TextBuffer object at 0x00000000033d9fc0 (GtkTextBuffer at 0x0000000004ad6c80)>
Gtk.TextView.new_with_buffer().
new_with_buffer(buffer)
Crea un nuovo widget Gtk.TextView che visualizza il buffer passato in argomento.
Un buffer può essere condiviso tra multipli widgets.
Parametri:
buffer: un oggetto Gtk.TextBuffer. None per un buffer di default;
add_child_at_anchor(child, anchor)
Aggiunge un child widget nel text buffer, all’anchor dato.
Parametri:
child: un Gtk.Widget da inserire all’anchor dato;
anchor: un Gtk.TextChildAnchor alla cui pos. inserire il child;
add_child_in_window(child, which_window, xpos, ypos)
Aggiunge un child all coordinate date, nella window indicata.
La window deve avere una size maggiore di zero (vedi Gtk.TextView.set_border_window_size()).
Le coordinate del child sono relative allo scrolling. Quando piazziamo un child in una window
Gtk.TextWindowType.WIDGET, lo scrolling è irrilevante, ovvero il child è floattante su tutte le
aree scrollable. Se invece piazziamo un child in una delle scrollable windows (border windows o
text window) si sposterà come richiesto dallo scrolling.
Parametri:
child: un Gtk.Widget da aggiungere;
which_window: la Gtk.TextWindowType alla quale aggiungere il child;
xpos: la posizione X relativa alle coordinate di window;
ypos: la posizione Y relativa alle coordinate di window;
backward_display_line(iter)
Sposta l’iter indietro di una display line (wrapped).
Una display line è differente da un paragrafo. I paragrafi sono separati da newlines o altri
caratteri separatori di paragrafo.
Le xlib.Display lines sono create quando facciamo il line-wrapping di un paragrafo.
Se il wrapping non è attivo, le display lines e i paragrafi saranno gli stessi.
Le xlib.Display lines sono divise diversamente per ogni view, dal momento che dipendono dalla
larghezza della view; i paragrafi sono gli stessi in tutte le views, dal momento che dipendono
dai contenuti del Gtk.TextBuffer.
Parametri:
iter: l’oggetto Gtk.TextIter;
backward_display_line_start(iter)
Sposta l’iter all’inizio della display line (wrapped) precedente.
Parametri:
iter: l’oggetto Gtk.TextIter;
buffer_to_window_coords(win, buffer_x, buffer_y)
Converte le coordinate (buffer_x, buffer_y) in coordinate per la window win e ne memorizza i
valori in (window_x, window_y). Non si possono convertire coordinate per window non esistenti
(vedi Gtk.TextView.set_border_window_size()).
Parametri:
win: una Gtk.TextWindowType eccetto Gtk.TextWindowType.PRIVATE;
buffer_x: coordinate X del buffer;
buffer_y: coordinate Y del buffer;
forward_display_line(iter)
Sposta l’iter avanti di una display line (wrapped).
iter: l’oggetto Gtk.TextIter;
forward_display_line_end(iter)
Sposta l’iter alla fine della display line (wrapped) successiva.
Parametri:
iter: l’oggetto Gtk.TextIter;
get_accepts_tab()
Ritorna True se premendo il tasto Tab viene inserito un tab character,
altrimenti False, se premendo il tasto Tab, viene spostato il focus.
get_border_window_size(type)
Ritorna la larghezza del bordo della window specificata.
Vedere Gtk.TextView.set_border_window_size() per il corrispondente setter.
Parametri:
type: la window Gtk.TextWindowType;
get_bottom_margin()
Ritorna il valore del bottom margin in pixels.
get_buffer()
Ritorna il Gtk.TextBuffer associato al text view.
get_cursor_locations(iter)
Dato un iter all’interno di un text layout, determina le posizioni dello strong cursor
e del weak cursor se il punto di inserzione è a quell’iterator.
La posizione di ogni cursore viene memorizzata come zero-width rectangle.
La pozizione dello strong cursor è la posizione dove i caratteri della direzionalità
sono uguali alla direzione di base del paragrafo dove sono inseriti.
La posizione del weak cursor è la posizione dove i caratteri della direzionalità
sono opposti alla direzione di base del paragrafo dove sono inseriti.
Se l’iter è None, viene utilizzata la posizione corrente del cursore.
Se capita che l’iter sia la posizione corrente del cursore e ci sia un inserimento con
input method pre-edit, le posizioni ritornate dal metodo saranno aggiustate per tenere conto
dell’offset del cursore del pre-edit, all’interno della sequanza di pre-edit.
La posizione del rectangle è in coordinate del buffer; per convertirle in coordinate win, usare
Gtk.TextView.buffer_to_window_coords().
Parametri:
iter: il Gtk.TextIter o None;
get_cursor_visible()
Ritorna True se l’insertion mark del cursore è visibile.
get_default_attributes()
Ritorna una copia degli attributi di default del testo (Gtk.TextAttributes).
get_editable()
Ritorna True se il textview è editabile.
get_indent()
Ritorna l’indentazione di default dei paragrafi del textview.
I Tags del buffer potrebbero sovrascrivere i valori di default. L’indentazione potrebbe essere
negativa.
get_input_hints()
Ritorna il valore della property “input-hints”.
get_input_purpose()
Ritorna il valore della property “input-purpose”.
get_iter_at_location(x, y)
Ritorna una tupla (bool, iter).
Il primo elemento è True, se la posizione di iter o sopra al testo, altrimenti False.
Il secondo elemento è l’iterator con coordinate del buffer X e Y.
Le coordinate buffer sono relative all’intero buffer e non alla porzione visualizzata.
Se siamo in possesso di coordinate derivate da un event, dobbiamo convertirle in
coordinate buffer con il metodo Gtk.TextView.window_to_buffer_coords().
Parametri:
x: la posizione X in coordinate buffer;
y: la posizione Y in coordinate buffer;
get_iter_at_position(x, y)
Ritorna una tupla (bool, iter, trailing).
bool è True se la posizione dell’iterator è sopra al testo, altrimenti False.
iter è l’iterator che punta al carattere con coordinate buffer X e Y.
trailing è la posizione dove viene memorizzato l’intero che indica dove lo user ha
cliccato nel grafema (0 indica il bordo posteriore del grafema).
Le coordinate buffer sono relative all’intero buffer e non alla porzione visualizzata.
Se siamo in possesso di coordinate derivate da un event, dobbiamo convertirle in
coordinate buffer con il metodo Gtk.TextView.window_to_buffer_coords().
Questo metodo è differente dal precedente Gtk.TextView.get_iter_at_location(), il quale ritornaa
le posizioni del cursore, ad esempio le posizioni tra caratteri.
Parametri:
x: la posizione X in coordinate buffer;
y: la posizione Y in coordinate buffer;
get_iter_location(iter)
Ritorna un rettangolo (semplicemente gli estremi) che contengono approssimativamente il
carattere dell’iter. La posizione del rettangolo è in coordinate buffer.
Usare Gtk.TextView.buffer_to_window_coords() per convertirle da coordinate win.
Parametri:
iter: il Gtk.TextIter;
get_justification()
Ritorna la giustificazione di default del paragrafo nel textview.
I Tags nel buffer potrebbero sovrascrivere tale valore.
get_left_margin()
Ritorna il margine sinistro (in pixels) del paragrafo nel textview.
I Tags nel buffer potrebbero sovrascrivere tale valore.
get_line_at_y(y)
Ritorna una tupla (target_iter, line_top)
target_iter è il Gtk.TextIter all’inizio della linea che contiene la coordinata Y.
Y è espressa in coordinate buffer, convertirle in caso siano espresse in coordinate win, con il
metodo Gtk.TextView.window_to_buffer_coords().
line_top è la posizione della coordinata del TOP della linea.
Se diversa da None, line_top sarà riempita con le coordinate del bordo superiore della linea.
Parametri:
y: la coordinata Y;
get_line_yrange(iter)
Ritorna la coordinata Y del TOP della linea contenente l’iterator e l’altezza della linea.
Y è espressa in coordinata buffer; per convertirla usare Gtk.TextView.buffer_to_window_coords().
Parametri:
iter: il Gtk.TextIter;
get_monospace()
Ritorna il valore della property “monospace”.
get_overwrite()
Ritorna True se il textview è in modalità overwrite (sovrascrittura).
get_pixels_above_lines()
Ritorna il numero di pixels di default, da mettere sopra ai paragrafi.
Usare questo metodo insieme a Gtk.TextView.get_pixels_below_lines() uquivale a settare il
line-space tra paragrafi.
get_pixels_below_lines()
Ritorna il numero di pixels di default, da mettere sotto ai paragrafi.
Usare questo metodo insieme a Gtk.TextView.get_pixels_above_lines() uquivale a settare il
line-space tra paragrafi.
get_pixels_inside_wrap()
Ritorna il valore settato con il metodo Gtk.TextView.set_pixels_inside_wrap(), ovvero il numero di
pixels di spazio vuoto tra wrapped lines.
get_right_margin()
Ritorna il valore del margine destro del testo, in pixels.
I Tags nel buffer potrebbero sovrascrivere tale valore.
get_tabs()
Ritorna un oggetto Pango.TabArray, ovvero la lista dei tabs nel textview.
I Tags nel buffer potrebbero sovrascrivere il default.
L’oggetto ritornato potrebbe essere None se i tabs utilizzati saranno quelli standard di 8 spazi.
get_top_margin()
Ritorna il valore del margine superiore del testo, in pixels.
get_visible_rect()
Riempie “visible_rect” con la regione visibile corrente del buffer, in coordinates buffer.
Convertire, nel caso, le coordinate win con il metodo Gtk.TextView.buffer_to_window_coords().
get_window(win)
Ritorna la Gdk.Window corrispondente a un’area del textview. Le window possibili includono
complessivamente widget window, child windows su left, right, top, bottom e la window che
visualizza il text buffer.
Parametri:
win: il widget Gtk.TextWindowType ovvero la window richiesta;
get_window_type(window)
Di solito il metodo utilizzato per sapere a chi corrisponde un determinato evento.
Parametri:
window: il tipo di window (Gdk.Window);
get_wrap_mode()
Ritorna il line wrapping per la view.
im_context_filter_keypress(event)
Permette all’IM del Gtk.TextView di gestire internamente gli eventi key press e key release.
Se questo metodo ritorna True, nessun processo ulteriore verrà fatto per il key event specificato.
Vedere Gtk.IMContext.filter_keypress().
Parametri:
event: il key event (Gdk.EventKey);
move_child(child, xpos, ypos)
Sposta il child widget, alla posizione data.
Parametri:
child: il widget presente nel text view;
xpos: la nuova posizione X in coordinates window;
ypos: la nuova posizione Y in coordinates window;
move_mark_onscreen(mark)
Sposta un mark all’interno del buffer cosicchè sia piazzato all’interno della text area visibile.
Ritorna True se l’operazione avviene con successo.
Parametri:
mark: il Gtk.TextMark;
move_visually(iter, count)
Ritorna True se l’iter viene spostato e non è sull’end iterator.
Sposta l’iterator del numero di caratteri specificato, trattandolo come la posizione di uno
strong cursor. Se count è positivo, allora la nuova posizione
dello strong cursor sarà tante count posizioni verso destra, rispetto alla posizione del vecchio
cursore. Se count è negativo la nuova posizione dello strong cursor sarà
tante count posizioni a sinistra della posizione del vecchio cursore.
Parametri:
iter (Gtk.TextIter): il Gtk.TextIter;
count: il numero di caratteri di cui spostarsi (se count è
negativo si sposta a sinistra, se count è positivo, a destra);
place_cursor_onscreen()
Sposta il cursore nella regione visibile del buffer, e ritorna True se lo spostamento avviene con
successo.
reset_cursor_blink()
Assicura che il cursore sia visualizzato (senza che il intervallo di lampeggio sia “off”) e
resetta il tempo in cui resterà lampeggiante (o visibile, se il blinking è disabilitato).
reset_im_context()
Resetta il contesto dell’input method (IM) del text view, se necessario.
Questo è utile se la modifica del buffer rende il comportamento dell’IM in corso, confuso.
scroll_mark_onscreen(mark)
Scrolla il text view del minimo necessario, perchè il mark sia presente nell’are visibile.
Parametri:
mark: il Gtk.TextMark nel buffer;
scroll_to_iter(iter, within_margin, use_align, xalign, yalign)
Scrolla il text view in modo che l’iterator sia sullo schermo nella posizione indicata da xalign
e yalign. Un allineamento di 0.0 indica sinistra, o top; 1.0 indica destra,
o bottom; 0.5 singnifica centrato.
Se use_align è False, il testo scrolla la distanza minima per avere il mark sullo
schermo, possibilmente non scrollando affatto.
Lo schermo effettivo per lo scopo di questo metodo è ridotto di un margine di within_margin.
Questo metodo usa l’altezza calcolata delle linee correnti, nel text buffer.
Le altezze delle linee sono calcolate in un idle handler; così facendo con questo metodo non si
otterrà l’effetto desiderato se questo verrà chiamato prima del calcolo dell’altezza.
Per evitare effetti strani, utilizzare il metodo Gtk.TextView.scroll_to_mark() che salva un punto
su cui scrollare, quando la validazione delle linee sarà terminato.
Parametri:
iter: il Gtk.TextIter;
within_margin: il margine come 0.0, 0.5 frazione di schermo;
use_align: se utilizzare gli argomenti di alignment (se False,
si occupa solo di avere il mark sullo schermo;
xalign: l’alignment orizzontale del mark, nell’area visibile;
yalign: l’alignment verticale del mark, nell’area visibile;
scroll_to_mark(mark, within_margin, use_align, xalign, yalign)
Scrolla il text view in modo che il mark sia sullo schermo nella posizione indicata da xalign
e yalign. Un allineamento di 0.0 indica sinistra, o top; 1.0 indica destra,
o bottom; 0.5 singnifica centrato.
Se use_align è False, il testo scrolla la distanza minima per avere il mark sullo
schermo, possibilmente non scrollando affatto.
Lo schermo effettivo per lo scopo di questo metodo è ridotto di un margine di within_margin.
Parametri:
mark: il Gtk.TextMark);
within_margin: il margine come 0.0, 0.5 frazione di schermo;
use_align: se utilizzare gli argomenti di alignment (se False,
si occupa solo di avere il mark sullo schermo;
xalign: l’alignment orizzontale del mark, nell’area visibile;
yalign: l’alignment verticale del mark, nell’area visibile;
set_accepts_tab(accepts_tab)
Setta il comportamento del text view quando viene premuto il Tab key.
Se accepts_tab è True, un carattere tab viene inserito. If accepts_tab è False
il focus viene spostato sul child successivo della focus chain.
Parametri:
accepts_tab il boolean che decide se inserire un carattere di tab
(True) o spostare il focus (False);
set_border_window_size(type, size)
Setta la larghezza del bordo ai seguenti valori dell’enum Gtk.TextWindowType:
PRIVATE (0): valore non valido, usato come marker;
WIDGET (1): window floattante sulle aree di scroll;
TEXT (2): scrollable text window;
LEFT (3): il bordo sinistro della window;
RIGHT (4): il bordo destro della window;
TOP (5): il bordo superiore della window;
BOTTOM (6): il bordo inferiore della window;
Parametri:
type: il Gtk.TextWindowType sul quale applicare il size;
size: larghezza, o altezza, della window;
set_bottom_margin(bottom_margin)
Setta il margine inferiore del testo nel text view. Il nome del metodo può confondere, ma in
termini di CSS, settiamo il valore del padding.
Parametri:
bottom_margin: il margine inferiore in pixels;
set_buffer(buffer)
Setta il buffer da visualizzare nel text view.
Parametri:
buffer: il Gtk.TextBuffer da visualizzare nel text view, o None;
set_cursor_visible(setting)
Setta la visibilità del cursore. Ad esempio in un buffer non editabile è giustificabile non voler
vedere il cursore.
Parametri:
setting: il boolean che rende visibile o meno il cursore;
set_editable(setting)
Setta l’editabilità del Gtk.TextView. E’ possibile sovrascrivere questo settaggio con i tags
nel buffer, usando l’attributo del tag “editable”.
Parametri:
setting: il boolean che rende il text view editabile o meno;
set_indent(indent)
Setta l’indentazione di default per i paragrafi del text view.
I Tags nel buffer potrebbero sovrascrivere questo settaggio..
Parametri:
indent: l’indentazione in pixels;
set_input_hints(hints)
Setta la property “input-hints” che permette agli input methods (IM) di affinare il proprio
comportamento.
Parametri:
hints: i Gtk.InputHints da settare;
set_input_purpose(purpose)
Setta la property “input-purpose” che può essere usata dalle on-screen keyboards e altri IM.
Parametri:
purpose: il Gtk.InputPurpose;
set_justification(justification)
Setta la giustificazione del testo nel text view.
I valori possono essere Gtk.Justification.LEFT, Gtk.Justification.RIGHT, Gtk.Justification.CENTER,
Gtk.Justification.FILL. I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
justification: il Gtk.Justification (LEFT, RIGHT, CENTER, FILL);
set_left_margin(left_margin)
Setta il valore in pixels del margine sinistro del testo (inteso come padding).
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
left_margin: il margine sinistro (padding) in pixels;
set_monospace(monospace)
Setta la property “monospace”, che indica che il text view deve usare o meno fonts monospace.
Parametri:
monospace: il boolean che setta, o meno, lo styling monospace;
set_overwrite(overwrite)
Setta la modalità sovrascrittura (overwrite mode) del text view.
Parametri:
overwrite: il boolean che setta, o meno, l’ overwrite mode;
set_pixels_above_lines(pixels_above_lines)
Setta il numero di pixels vuoti sopra ai paragrafi.
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
pixels_above_lines: il numero di blank pixels sopra ai paragrafi;
set_pixels_below_lines(pixels_below_lines)
Setta il numero di pixels di spazio vuoto da mettere sotto ai paragrafi.
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
pixels_below_lines: il numero di pixels vuoti sotto ai paragrafi;
set_pixels_inside_wrap(pixels_inside_wrap)
Setta il numero di pixels di spazio vuoto dalasciare tra le wrapped lines dentro a un paragrafo.
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
pixels_inside_wrap: il numero di pixels vuoti tra wrapped lines;
set_right_margin(right_margin)
Setta il valore in pixels del margine destro del testo (inteso come padding).
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
right_margin: il margine destro (padding) in pixels;
set_tabs(tabs)
Setta i tab stops per i paragrafi nel text view.
I Tags nel buffer potrebbero sovrascrivere questo settaggio.
Parametri:
tabs: un oggetto Pango.TabArray;
set_top_margin(top_margin)
Setta il margine superiore per il testo, inteso come padding).
Parametri:
top_margin: il margine superiore (padding) in pixels;
set_wrap_mode(wrap_mode)
Setta il line wrapping per il text view. L’enum che lo definisce, può assumere i seguenti valori:
NONE (0): nessun wrap;
CHAR (1): esegue il wrap del testo, ovunque il cursore possa apparire (tra i caratteri);
WORD (2): esegue il wrap del testo, spezzando la linea tra parole intere;
WORD_CHAR (3): esegue il wrap del testo, spezzando la linea tra parole, o, se non è sufficiente,
anche tra grafemi;
Parametri:
wrap_mode: l’enum (Gtk.WrapMode) che definisce il wrap mode;
starts_display_line(iter)
Ritorna True se un iter è all’inizio di una display line, altrimenti False.
vedere Gtk.TextView.forward_display_line() per la differenza tra display lines e paragrafi.
Parametri:
iter: l’oggetto Gtk.TextIter da verificare;
window_to_buffer_coords(win, window_x, window_y)
Converte le coordinate sulla window identificate da win, in coordinate buffer.
Ritorna una tupla (buffer_x, buffer_y).
Parametri:
win: una Gtk.TextWindowType eccetto Gtk.TextWindowType.PRIVATE
window_x: le coordinate window X da convertire;
window_y: le coordinate window Y da convertire;
Ecco un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Pango
class SearchDialog(Gtk.Dialog):
def __init__(self, parent):
super().__init__("Search", parent)
self.add_buttons(Gtk.STOCK_FIND, Gtk.ResponseType.OK,
Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL)
box = self.get_content_area()
box.add(Gtk.Label(label="Inserisci il testo da cercare"))
self.entry = Gtk.Entry.new()
box.add(self.entry)
self.show_all()
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="TextView Example")
self.text_view = None
self.text_buffer = None
self.tag_bold = None
self.tag_italic = None
self.tag_underline = None
self.tag_found = None
self.grid = Gtk.Grid()
self.set_default_size(500, 400)
self.add(self.grid)
self.create_textview()
self.create_toolbar()
self.create_buttons()
def create_toolbar(self):
toolbar = Gtk.Toolbar()
self.grid.attach(toolbar, 0, 0, 3, 1)
# Button Bold
button_bold = Gtk.ToolButton()
button_bold.set_icon_name("format-text-bold-symbolic")
toolbar.insert(button_bold, 0)
button_bold.connect("clicked", self.on_button_clicked, self.tag_bold)
# Button Italic
button_italic = Gtk.ToolButton()
button_italic.set_icon_name("format-text-italic-symbolic")
toolbar.insert(button_italic, 1)
button_italic.connect("clicked", self.on_button_clicked,
self.tag_italic)
# Button underline
button_underline = Gtk.ToolButton()
button_underline.set_icon_name("format-text-underline-symbolic")
toolbar.insert(button_underline, 2)
button_underline.connect("clicked", self.on_button_clicked,
self.tag_underline)
toolbar.insert(Gtk.SeparatorToolItem(), 3)
# RadioButtons
radio_j_left = Gtk.RadioToolButton()
radio_j_left.set_icon_name("format-justify-left-symbolic")
toolbar.insert(radio_j_left, 4)
radio_j_center = Gtk.RadioToolButton.new_from_widget(radio_j_left)
radio_j_center.set_icon_name("format-justify-center-symbolic")
toolbar.insert(radio_j_center, 5)
radio_j_right = Gtk.RadioToolButton.new_from_widget(radio_j_left)
radio_j_right.set_icon_name("format-justify-right-symbolic")
toolbar.insert(radio_j_right, 6)
radio_j_fill = Gtk.RadioToolButton.new_from_widget(radio_j_left)
radio_j_fill.set_icon_name("format-justify-fill-symbolic")
toolbar.insert(radio_j_fill, 7)
radio_j_left.connect("toggled", self.on_justify_toggled,
Gtk.Justification.LEFT)
radio_j_center.connect("toggled", self.on_justify_toggled,
Gtk.Justification.CENTER)
radio_j_right.connect("toggled", self.on_justify_toggled,
Gtk.Justification.RIGHT)
radio_j_fill.connect("toggled", self.on_justify_toggled,
Gtk.Justification.FILL)
toolbar.insert(Gtk.SeparatorToolItem(), 8)
button_clear = Gtk.ToolButton()
button_clear.set_icon_name("edit-clear-symbolic")
button_clear.connect("clicked", self.on_clear_clicked)
toolbar.insert(button_clear, 9)
toolbar.insert(Gtk.SeparatorToolItem(), 10)
button_search = Gtk.ToolButton()
button_search.set_icon_name("system-search-symbolic")
button_search.connect("clicked", self.on_search_clicked)
toolbar.insert(button_search, 11)
def create_textview(self):
scrolled_win = Gtk.ScrolledWindow()
scrolled_win.set_hexpand(True)
scrolled_win.set_vexpand(True)
self.grid.attach(scrolled_win, 0, 1, 3, 1)
# Text View
self.text_view = Gtk.TextView()
self.text_buffer = self.text_view.get_buffer()
self.text_buffer.set_text("This is some text inside of a Gtk.TextView. "
"Select text and click one of the buttons "
"'bold', 'italic', or 'underline' to modify "
"the text accordingly.")
scrolled_win.add(self.text_view)
# Tags
self.tag_bold = self.text_buffer.create_tag(tag_name="bold",
weight=Pango.Weight.BOLD)
self.tag_italic = self.text_buffer.create_tag(tag_name="italic",
style=Pango.Style.ITALIC)
self.tag_underline = self.text_buffer.create_tag(
tag_name="underline", underline=Pango.Underline.SINGLE)
self.tag_found = self.text_buffer.create_tag(tag_name="found",
background="yellow")
def create_buttons(self):
check_editable = Gtk.CheckButton(label="Editable")
check_editable.set_active(True)
check_editable.connect("toggled", self.on_editable_toggled)
self.grid.attach(check_editable, 0, 2, 1, 1)
check_cursor = Gtk.CheckButton(label="Cursor Visible")
check_cursor.set_active(True)
check_editable.connect("toggled", self.on_cursor_toggled)
self.grid.attach_next_to(check_cursor, check_editable,
Gtk.PositionType.RIGHT, 1, 1)
radio_wrapnone = Gtk.RadioButton.new_with_label_from_widget(None,
"No Wrapping")
self.grid.attach(radio_wrapnone, 0, 3, 1, 1)
radio_wrapchar = Gtk.RadioButton.new_with_label_from_widget(
radio_wrapnone, "Character Wrapping")
self.grid.attach_next_to(radio_wrapchar, radio_wrapnone,
Gtk.PositionType.RIGHT, 1, 1)
radio_wrapword = Gtk.RadioButton.new_with_label_from_widget(
radio_wrapnone, "Word Wrapping")
self.grid.attach_next_to(radio_wrapword, radio_wrapchar,
Gtk.PositionType.RIGHT, 1, 1)
radio_wrapnone.connect("toggled", self.on_wrap_toggled,
Gtk.WrapMode.NONE)
radio_wrapchar.connect("toggled", self.on_wrap_toggled,
Gtk.WrapMode.CHAR)
radio_wrapword.connect("toggled", self.on_wrap_toggled,
Gtk.WrapMode.WORD)
def on_button_clicked(self, widget, tag):
bounds = self.text_buffer.get_selection_bounds()
if len(bounds) != 0:
start, end = bounds
self.text_buffer.apply_tag(tag, start, end)
def on_clear_clicked(self, widget):
start = self.text_buffer.get_start_iter()
end = self.text_buffer.get_end_iter()
self.text_buffer.remove_all_tags(start, end)
def on_editable_toggled(self, widget):
self.text_view.set_editable(widget.get_active())
def on_cursor_toggled(self, widget):
self.text_view.set_cursor_visible(widget.get_active())
def on_wrap_toggled(self, widget, mode):
self.text_view.set_wrap_mode(mode)
def on_justify_toggled(self, widget, justification):
self.text_view.set_justification(justification)
def on_search_clicked(self, widget):
dialog = SearchDialog(parent=self)
response = dialog.run()
if response == Gtk.ResponseType.OK:
cursor_mark = self.text_buffer.get_insert()
start = self.text_buffer.get_iter_at_mark(cursor_mark)
if start.get_offset() == self.text_buffer.get_char_count():
start = self.text_buffer.get_start_iter()
self.search_and_mark(dialog.entry.get_text(), start)
dialog.destroy()
def search_and_mark(self, text, start):
end = self.text_buffer.get_end_iter()
match = start.forward_search(text, 0, end)
if match is not None:
match_start, match_end = match
self.text_buffer.apply_tag(self.tag_found, match_start, match_end)
self.search_and_mark(text, match_end)
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.Toolbar
torna all’indice degli appunti
ToolBar
Una toolbar può contenere istanze di sottoclassi di Gtk.ToolItem.
Per aggiungere un’istanza di Gtk.ToolItem
alla toolbar, si utilizza il metodo Gtk.Toolbar.insert().
Per rimuovere un elemento dalla toolbar si usa il metodo Gtk.Container.remove().
Per aggiungere un button alla toolbar, aggiungere un’istanza di Gtk.ToolButton.
Gli elementi della Toolbar possono essere raggruppati visivamente aggiungendo istanze di
Gtk.SeparatorToolItem alla toolbar.
Se la property “expand” del child della Gtk.Toolbar è True e la property “draw”
di Gtk.SeparatorToolItem è False, l’effetto è di forzare tutti gli elementi
seguenti, alla fine della toolbar.
Di default, una toolbar può essere ristretta (shrunk), in tal caso aggiungerà delle arrow button
per mostrare tutti i Gtk.ToolItem non visibili.
Per evitare questo comportamento e avere lo spazio necessario per tutti i children, chiamare il
metodo Gtk.Toolbar.set_show_arrow() per settare la property “show-arrow”
a False.
E’ possibile creare un menu contestuale per la toolbar, connettendo il segnale
“popup-context-menu” a Gtk.Toolbar.
Le properties principali sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| icon-size | Gtk.IconSize | r/w/en | La dimensione delle icone nella toolbar |
| icon-size-set | bool | r/w | Se la property “icon-size” è stata settata |
| show-arrow | bool | r/w/en | Se una freccia deve essere visualizzata quando la toolbar non può contenere tutti gli elementi |
| toolbar-style | Gtk.ToolbarStyle | r/w/en | Lo stile con cui disegnare la toolbar |
| button-relief | Gtk.ReliefStyle | r | Il tipo di bevel attorno ai buttons della toolbar |
| max-child-expand | int | r | Il massimo spazio che un elemento espandibile si prenderà |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.ToolBar,
i principali metodi sono:
new()
Metodo costruttore che crea una nuova ToolBar.
get_drop_index(x, y)
Ritorna la posizione sulla toolbar, corrispondente al punto indicato.
Utile quando trasciniamo elementi sulla toolbar:
Parametri:
x: la coordinata x di un punto sulla toolbar;
y: la coordinata y di un punto sulla toolbar;
get_icon_size()
Ritorna l’oggetto Gtk.IconSize che rappresenta la dimensione dell’icona sulla toolbar
get_item_index(item)
Ritorna l’indice della posizione dell’elemento sulla toolbar.
Parametri:
item: l’elemento (Gtk.ToolItem) del quale vogliamo conoscere
l’indice della posizione;
get_n_items()
Ritorna il numero degli elementi della toolbar.
get_nth_item(n)
Ritorna l “n”esimo elemento sulla toolbar.
Parametri:
n: l’indice della posizione sulla toolbar;
get_relief_style()
Ritorna il tipo di rilievo (Gtk.ReliefStyle) dei bottoni nella toolbar, settati con il metodo
Gtk.Button.set_relief(). L’enum Gtk.ReliefStyle può assumere i seguenti valori:
NORMAL (0): disegna un “relief” normale;
NONE (2): nessun rilievo;
get_show_arrow()
Ritorna True se la ToolBar mostra le frecce in caso di bottoni eccedenti
rispetto allo spazio deisponibile.
get_style()
Ritorna lo style corrente della ToolBar. L’enum Gtk.ToolbarStyle indica se la toolbar debba
visualizzare sono i testi, le icone, o entrambi.
I valori possibili sono i seguenti:
ICONS (0): i bottoni nella toolbar visualizzano solo le icone;
TEXT (1): i bottoni nella toolbar visualizzano solo i testi (labels);
BOTH (2): i bottoni nella toolbar visualizzano testi e icone;
BOTH_HORIZ (3): i bottoni nella toolbar visualizzano testi e icone gli accanto alle altre, invece
che gli uni sopra le altre (default);
insert(item, pos)
Inserisce un Gtk.ToolItem alla posizione data. Se la posizione è 0, il toolitem
viene inserito all’inizio della toolbar,
se la posizione è negativa, il tooitem viene inserito alla fine della toolbar.
Parametri:
item: l’oggetto Gtk.ToolItem da inserire nella toolbar;
pos: la posizione dove inserire il toolitem;
set_drop_highlight_item(tool_item, index_)
Evidenzia la toolbar per dare l’idea di come diventerebbe se l’elemento venisse aggiunto alla
toolbar alla posizione indicata.
Se l’elemento (tool_item) è None, l’evidenziazione viene spenta, così come viene
ignorata la posizione di inserimento (index_).
L’elemento tool_item passato al metodo non deve far parte di nessuna gerarchia di nessun widget e
allo stesso modo, quando un elemento viene settato come drop highlight item,
non può essere aggiunto a nessuna gerarchia di nessun widget e nemmeno usato come highlight item
di un’altra toolbar.
Parametri:
tool_item: l’oggetto Gtk.ToolItem da settare drop highlight item,
o None per spegnere l’highlighting;
index: la posizione del toolitem;
set_icon_size(icon_size)
Setta la dimensione delle stock icons nella toolbar. Possiamo chiamare il metodo, sia prima di
aggiungere le icone, sia dopo. Settando la dimensione con questo metodo, sovrascriverà l’eventuale
default icon size definita dall’utente.
Parametri:
icon_size: il size (Gtk.IconSize) che vogliamo per le stock icons
nella toolbar;
set_show_arrow(show_arrow)
Setta se la toolbar debba avere o meno le frecce indicanti bottoni eccedenti che la toolbar non
può mostrare. Se True, gli elementi che non stanno nella toolbar per motivi di
spazio e che hanno un elemento proxy menu, settato con il metodo
Gtk.ToolItem.set_proxy_menu_item(), saranno appunto disponibili in un
overflow menu, che può essere aperto grazie ad una freccia (arrow button).
Se False, la toolbar richiederà lo spazio necessario per mostrare tutti i suoi elementi.
Parametri:
show_arrow: il boolean che settato a True mostra un
overflow menu;
set_style(style)
Setta lo stile della toolbar. L’enum che ne decreta l’aspetto può assumere i seguenti valori:
ICONS (0): i bottoni nella toolbar visualizzano solo le icone;
TEXT (1): i bottoni nella toolbar visualizzano solo i testi (labels);
BOTH (2): i bottoni nella toolbar visualizzano testi e icone;
BOTH_HORIZ (3): i bottoni nella toolbar visualizzano testi e icone gli accanto alle altre, invece
che gli uni sopra le altre (default);
Parametri:
style: l’enum (Gtk.ToolbarStyle) che indica lo stile della toolbar;
unset_icon_size()
Elimina il settaggio delle dimensioni delle icone effettuato con Gtk.Toolbar.set_icon_size(),
così facendo verranno usate le user preferences, che altrimenti sarebbero sovrascritte dal metodo
precedente.
unset_style()
Elimina il settaggio della toolbar effettuato con Gtk.Toolbar.set_style(),
così facendo verranno usate le user preferences, che altrimenti sarebbero sovrascritte dal metodo
precedente.
Gtk.ToolButton
Come accennato prima, per la toolbar al posto del generico toolitem, è conveniente utilizzare
oggetti Gtk.ToolButton.
L’iter è molto semplice: si costruisce l’oggetto tool_bar, si istanziano gli oggetti toolbuttons e
si sceglie per essi, un’icona tra le stock icons
disponibili, si aggiungono i toolbuttons alla toolbar, si eseguono i bindings dei toolbuttons al
segnale “clicked”.
Ecco un codeice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gio
class AppWindow(Gtk.ApplicationWindow):
def __init__(self):
super().__init__(title="Toolbar Example")
self.set_default_size(250, 100)
tool_bar = Gtk.Toolbar.new()
button_open = Gtk.ToolButton(stock_id=Gtk.STOCK_OPEN, label="Open")
button_new = Gtk.ToolButton(stock_id=Gtk.STOCK_NEW, label="New")
tool_bar.insert(item=button_new, pos=0)
tool_bar.insert(item=button_open, pos=1)
tool_bar.set_style(Gtk.ToolbarStyle.BOTH)
box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
box.pack_start(tool_bar, False, False, 0)
self.add(box)
# bindings
button_new.connect('clicked', self.on_menu)
button_open.connect('clicked', self.on_menu)
self.connect('destroy', Gtk.main_quit)
def on_menu(self, tool_button):
print("INFO: menu '%s' clicked!" % tool_button.get_label())
if __name__ == '__main__':
win = AppWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
Gtk.Builder e XML
Come già visto per la MenuBar, possiamo ottenere lo stesso risultato utilizzando Gtk.Builder.
Gtk.Builder è un oggetto che legge le descrizioni di una UI da un testo e ne
istanzia gli oggetti descritti in esso.
A grandi linee, all’interno del testo, gli oggetti del menu saranno così identificati:
UI ovvero l’interfaccia utente del menu: sarà compresa tra i tag
<interface></interface>
menu_model ovvero l’oggetto menu genitore: sarà compreso tra i tag
<menu></menu>
sub_menu ovvero le voci dei menu: saranno comprese tra i tag
<submenu></submenu>
item ovvero gli elementi interni alle voci di menu: saranno compresi tra i tag
<item></item>
attribute ovvero l’attributo dell’istanza che verrà creata dal buider: sarà
compreso tra i tag
<attribute></attribute>
Come nella MenuBar e a differenza dell’esempio precedente, qui entrano in gioco le actions.
Nel nostro caso precedente il testo che rappresenta il menu della app, sarà:
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<!-- interface-requires gtk+ 3.0 -->
<object class="GtkToolbar" id="toolbar">
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="hexpand">True</property>
<property name="show_arrow">False</property>
<child>
<object class="GtkToolButton" id="new_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.new</property>
<property name="label" translatable="yes">New</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-new</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
<child>
<object class="GtkToolButton" id="open_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.open</property>
<property name="label" translatable="yes">Open</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-open</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
</object>
</interface>
Basterà quindi creare il builder con il class_method Gtk.Builder.new_from_string(string, length).
Sarà quindi il builder stesso ad istanziare gli oggetti descritti nella stringa XML e a
recuperarli con il metodo get_object(string).
Rispetto a prima bisognerà creare le actions che si occuperanno di connettere gli elementi della
toolbar al segnale “activate”.
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gio
TOOLBAR_INFO = """
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<!-- interface-requires gtk+ 3.0 -->
<object class="GtkToolbar" id="toolbar">
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="hexpand">True</property>
<property name="show_arrow">False</property>
<child>
<object class="GtkToolButton" id="new_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.new</property>
<property name="label" translatable="yes">New</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-new</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
<child>
<object class="GtkToolButton" id="open_button">
<property name="use_action_appearance">False</property>
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="use_action_appearance">False</property>
<property name="is_important">True</property>
<property name="action_name">win.open</property>
<property name="label" translatable="yes">Open</property>
<property name="use_underline">True</property>
<property name="stock_id">gtk-open</property>
</object>
<packing>
<property name="expand">False</property>
<property name="homogeneous">True</property>
</packing>
</child>
</object>
</interface>
"""
class AppWindow(Gtk.ApplicationWindow):
def __init__(self):
super().__init__(title="Toolbar Example")
self.set_default_size(250, 100)
builder = Gtk.Builder.new_from_string(TOOLBAR_INFO, -1)
act_new = Gio.SimpleAction.new(name='new', parameter_type=None)
act_open = Gio.SimpleAction.new(name='open', parameter_type=None)
self.add_action(act_new)
self.add_action(act_open)
tool_bar = builder.get_object('toolbar')
tool_bar.set_style(Gtk.ToolbarStyle.BOTH)
box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
box.pack_start(tool_bar, False, False, 0)
self.add(box)
# bindings
act_new.connect('activate', self.on_menu)
act_open.connect('activate', self.on_menu)
self.connect('destroy', Gtk.main_quit)
def on_menu(self, action, value):
print("INFO: menu '%s'" % action.props.name)
if __name__ == '__main__':
win = AppWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
torna all’indice degi appunti
Gtk3 Toolbar
Gnome Stock icons
PyGObject: Gtk.ComboBox
torna all’indice degli appunti
ComboBox
Il widget Gtk.ComboBox permette di selezionare un elemento da una lista.
Una volta selezionato l’elemento, il combobox lo visualizzerà.
Il combobox usa un pattern model-view e la lista degli elementi viene specificata
secondo il modello ad albero (tree-model).
Ci sono due modelli di dati da utilizzare:
il Gtk.ListStore e il Gtk.TreeStore.
Il Gtk.ListStore contiene semplici righe di dati (row), senza children,
mentre il Gtk.TreeStore può contenere dati con children.
La visualizzazione di tali elementi, si adatta al tipo di dato contenuto nel model grazie ai cell-renderers.
Questo è reso possibile dal fatto che Gtk.ComboBox implementa un’interfaccia
Gtk.CellLayout.
Di solito una combobox forza l’utente a scegliere tra gli elementi che dispone, ma dà la
possibilità di aggiungere una scelta, qualora questa non fosse presente, mettendo a disposizione
una Gtk.Entry. Quando la lista di elementi del combobox, riguarda semplici
testi, può essere conveniente utilizzare al posto del widget Gtk.ComboBox, un widget
Gtk.ComboBoxText.
Per creare una ComboBox si utilizza il costruttore Gtk.ComboBox(**kwargs).
Come per tutti gli altri widgets visti fino ad ora, è 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):
Le properties principali di una combobox sono le seguenti:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| active | int | r/w/en | l’item attivo al momento |
| active-id | str | r/w/en | il valore dell’id di colonna per la riga attiva |
| button-sensitivity | Gtk.SensitivityType | r/w/en | Se il dropdown button è sensibile quando il modulo è vuoto |
| cell-area | Gtk.CellArea | r/w/co | il Gtk.CellArea usato per il layout delle celle |
| column-span-column | int | r/w/en | la colonna del TreeModel che contiene i valori del column span |
| entry-text-column | int | r/w/en | la colonna nel model del combobox da associare con le stringhe dalla entry se il combobox è stato crato con la property “has-entry”=True |
| has-entry | bool | r/w/co | se il combobox ha una entry |
| has-frame | bool | r/w/en | se il combobox disegna un frame intorno al child |
| id-column | int | r/w/en | La colonna nel model del combobox che fornisce gli ID per i valori nel model |
| model | Gtk.TreeModelv | r/w/en | Il model per il combobox |
| popup-fixed-width | bool | r/w/en | Se la larghezza del popup debba essere fissa rispetto alla larghezza allocata dal combobox |
| popup-shown | bool | r | Se il dropdown del combobox viene visualizzato |
| row-span-column | int | r/w/en | la colonna del TreeModel contenente i valori del row span |
| wrap-width | int | r/w/en | La larghezza di Wrap per la collocazione degli elementi in una griglia |
| selection-mode | Gtk.SelectionMode | r/w/en | il tipo di selection mode |
La property selection-mode è un enum di tipo Gtk.SelectionMode
che può assumere i seguenti valori:
NONE (0): nessuna selezione possibile;
SINGLE (1): può essere selezionato 1 solo elemento, o nessuno;
BROWSE (2): può essere selezionato 1 solo elemento, ma è possibile anche deselezionarlo;
MULTIPLE (3): è possibile selezionare elementi multipli;
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
>>> ComboBox = Gtk.ComboBox()
>>> ComboBox.set_property("selection-mode", Gtk.SelectionMode.NONE)
>>> ComboBox.get_property("selection-mode")
<enum GTK_SELECTION_NONE of type Gtk.SelectionMode>
Come per gli altri widgets esistono i metodi getter e setter specifici get_*property_name*()
e set_*property_name*(value):
Segnali
I segnali principali sono:
| Name | Short Description |
|---|---|
| changed | il segnale “changed” viene emesso quando cambia l’elemento “attivo”; |
| format-entry-text | usato quando il combobox prevede una entry; |
| move-active | il segnale “move-active” viene emesso quando si sposta la selezione attiva; |
| popdown | il segnale “popdown” è un keybinding emesso quando si apre la lista della combobox con la combinazione ALT+UP; |
| popup | il segnale “popup” è un keybinding emesso quando si chiude la lista della combobox con la combinazione ALT+DOWN; |
Metodi
Di seguito i metodi utilizzabili con il widget Gtk.ComboBox:
new()
Metodo costruttore che crea un nuovo Gtk.ComboBox.
new_with_area(area)
Metodo costruttore che crea un Gtk.ComboBox vuoto usando l’area per disporre le celle.
Parametri:
area: la Gtk.CellArea usata per disporre i cell renderers;
new_with_area_and_entry(area)
Metodo costruttore che crea un Gtk.ComboBox vuoto usando l’area per disporre le celle, con una
entry.
Parametri:
area: la Gtk.CellArea usata per disporre i cell renderers;
new_with_entry()
Metodo costruttore che crea un Gtk.ComboBox vuoto con una entry.
new_with_model(model)
Metodo costruttore che crea un Gtk.ComboBox con un model inizializzato al model specificato.
Parametri:
model: un Gtk.TreeModel da associare al combobox;
new_with_model_and_entry(model)
Metodo costruttore che crea un Gtk.ComboBox con un model inizializzato al model specificato e una
entry.
Parametri:
model: un Gtk.TreeModel da associare al combobox;
get_active()
Ritorna l’indice dell’elemento attivo, o -1 se non ci sono elementi attivi.
Se il model è un treemodel non-flat e l’elemento attivo non è un child immediato della root del
tree, questo metodo ritorna gtk_tree_path_get_indices (path)[0], dove “path” è il Gtk.TreePath
dell’elemento attivo.
get_active_id()
Ritorna l’ID della row attiva del combobox. Questo valore viene preso dalla row attiva e dalla
colonna specificata dalla property “id-column” (vedere Gtk.ComboBox.set_id_column()).
Se la property “id-column” non è settata, o se non c’è una row attiva, o se la row attiva ha
ID=None, il metodo ritorna None.
get_active_iter()
Ritorna l’iter per l’elemento attivo, se esiste.
get_button_sensitivity()
Ritorna True se il combobox ha i dropdown button sensibili anche in caso di model senza elementi.
get_column_span_column()
Ritorna l’indice della colonna con l’informazione “column span” relativa al combobox.
get_entry_text_column()
Ritorna l’indice della colonna che il combobox sta usando per gestire le stringhe di testo
inserite nella entry del combobox stesso.
get_has_entry()
Ritorna True se il combobox ha una entry, altrimenti False.
get_id_column()
Ritorna l’indice della colonna che il combobox sta usando per gestire gli IDs.
get_model()
Ritorna il Gtk.TreeModel che sta funzionando come sorgente dati per il combobox.
get_popup_fixed_width()
Ritorna True se il popup usa una larghezza fissa.
get_row_span_column()
Ritorna l’id della colonna con l’informazione relativa al “row span” del combobox.
get_wrap_width()
Ritorna la larghezza di wrap usata per determinare il numero di colonne per il popup menu.
Se il “wrap width” è > 1, il combobox è in table mode.
popdown()
Nasconde il menu o la dropdown list del combobox.
popup()
Visualizza il menu o la dropdown list del combobox.
popup_for_device(device)
Fa apparire il menu o la dropdown list per il device specificato; la popup window sarà “afferrata”
e solo il device ed i suoi pointer/keyboard associati saranno gli unici Gdk.Devices abilitati a
spedire eventi ad essa.
Parametri:
device: il Gdk.Device sul quale far apparire menu o dropdown list
set_active(index)
Setta come attivo l’elemento con l’indice specificato.
Parametri:
index: un indice del model corrispondente all’elemento che
vogliamo rendere attivo, o -1 per non avere elementi attivi;
set_active_id(active_id)
Cambia la row attiva del combobox con quella della stringa ID uguale ad “active_id”, o,
se active_id=None, disattiva la row corrente.
Le Rows che hanno la stringa ID=None non possono essere rese attive da questo metodo.
Se la property “id-column” del combobox non è settata, o se nessuna row ha l’ID specificato,
allora il metodo non fa nulla e ritorna False. Ritorna True, invece in caso di successo.
Parametri:
active_id: la stringa cheindica l’ID della row da selezionare, o None;
set_active_iter(iter)
Setta l’elemento che ha l’iter specificato com attivo. Se iter=None viene disattivato l’elemento
attivo corrente.
Parametri:
iter: il Gtk.TreeIter o None;
set_button_sensitivity(sensitivity)
Setta il tipo di sensitività del dropdown button del combobox secondo il valore specificato.
sensitivity (enum Gtk.SensitivityType) può assumere i seguenti valori:
AUTO (0): la freccia (dropdown button) diventa “insensitive” quando si giunge alla fine;
ON (1): la freccia (dropdown button) è sempre “sensitive”;
OFF (2): la freccia (dropdown button) è sempre “insensitive”;
Parametri:
sensitivity: l’enum Gtk.SensitivityType che specifica la
sensitività del dropdown button (freccia);
set_column_span_column(column_span)
Setta la colonna con l’informazione “column span”. La colonna “column span” contiene quindi un
intero che indica su quante colonne verrà disposto un elemento.
Parametri:
column_span: l’indice della colonna nella quale inseriremo
l’informazione “column span”;
set_entry_text_column(text_column)
Setta la colonna del model che gestisce le stringhe della text_column (entry).
La colonna text_column nel model del combobox deve essere di tipo GObject.TYPE_STRING.
Ha rilevanza solo se il combobox è stato creato con la property “has-entry”=True.
Parametri:
text_column: l’indice della colonna nel model che gestirà i testi
della entry;
set_id_column(id_column)
Setta la colonna del model da usare per gestire le string IDs.
La colonna id_column nel model deve essere di tipo GObject.TYPE_STRING.
Parametri:
id_column: l’indice della colonna nel model che gestisce
le string IDs;
set_model(model)
Setta il model usato dal combobox. Verrà eliminato il model precedente.
Se model=None, non ci sarà nessun model settato per il combobox.
Questo metodo non azzera i cell renderers, quindi in caso si vogliano settare dei nuovi
cellrenderers per il nuovo model, bisognerà chiamare il metodo Gtk.CellLayout.clear().
Parametri:
model: il Gtk.TreeModel o None;
set_popup_fixed_width(fixed)
Specifica se la larghezza del popup debba essere una larghezza fissa.
Parametri:
fixed: se usare un popup a larghezza fissa;
set_row_separator_func(func, *data)
Setta la funzione di row separator, che è usata per determinare se una row debba essere disegnata
come separator. Se la funzione “row separator” è None, nessun separators verrà visualizzato
(comportamento di default).
Parametri:
func: la funzione Gtk.TreeViewRowSeparatorFunc;
data: i dati da passare alla funzione o None;
set_row_span_column(row_span)
Setta la colonna con l’informazione “row span”. La colonna “row span” contiene quindi un
intero che indica su quante righe verrà disposto un elemento.
Parametri:
row_span: l’indice della colonna nella quale inseriremo
l’informazione “row span”;
set_wrap_width(width)
Setta la larghezza di wrap del combobox. Il wrap è in sostanza il numero di colonne su cui
vogliamo venga disposto il popup, in una tabella
Parametri:
width: il numero di colonne per il wrap;
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="ComboBox Example")
self.set_border_width(10)
name_store = Gtk.ListStore(int, str)
name_store.append([1, "Billy Bob"])
name_store.append([11, "Billy Bob Junior"])
name_store.append([12, "Sue Bob"])
name_store.append([2, "Joey Jojo"])
name_store.append([3, "Rob McRoberts"])
name_store.append([31, "Xavier McRoberts"])
name_combo = Gtk.ComboBox.new_with_model_and_entry(name_store)
name_combo.connect("changed", self.on_name_combo_changed)
name_combo.set_entry_text_column(1)
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
vbox.pack_start(name_combo, False, False, 0)
country_store = Gtk.ListStore(str)
countries = ["Austria", "Brazil", "Belgium", "France", "Germany",
"Switzerland", "United Kingdom",
"United States of America", "Uruguay"]
for country in countries:
country_store.append([country])
country_combo = Gtk.ComboBox.new_with_model(country_store)
country_combo.connect("changed", self.on_country_combo_changed)
renderer_text = Gtk.CellRendererText()
country_combo.pack_start(renderer_text, True)
country_combo.add_attribute(renderer_text, "text", 0)
vbox.pack_start(country_combo, False, False, True)
currencies = ["Euro", "US Dollars", "British Pound", "Japanese Yen",
"Russian Ruble", "Mexican peso", "Swiss franc"]
currency_combo = Gtk.ComboBoxText()
currency_combo.set_entry_text_column(0)
currency_combo.connect("changed", self.on_currency_combo_changed)
for currency in currencies:
currency_combo.append_text(currency)
vbox.pack_start(currency_combo, False, False, 0)
self.add(vbox)
def on_name_combo_changed(self, combo):
tree_iter = combo.get_active_iter()
if tree_iter is not None:
model = combo.get_model()
row_id, name = model[tree_iter][:2]
print("Selected: ID=%d, name=%s" % (row_id, name))
else:
entry = combo.get_child()
print("Entered: %s" % entry.get_text())
def on_country_combo_changed(self, combo):
tree_iter = combo.get_active_iter()
if tree_iter is not None:
model = combo.get_model()
country = model[tree_iter][0]
print("Selected: country=%s" % country)
def on_currency_combo_changed(self, combo):
text = combo.get_active_text()
if text is not None:
print("Selected: currency=%s" % text)
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.Button
torna all’indice degli appunti
Button
Il widget Gtk.Button viene generalmente collegato ad una callback che viene invocata quando lo
stesso widget viene premuto.
Come accade per altri widget, il Gtk.Button può contenere altri widget (child), come ad esempio
Testi (Label) o immagini.
Per creare un Button si utilizza il costruttore Gtk.Button(*args, **kwargs),
dove gli argomenti più significativi sono “label” e “image”.
label: è una stringa di testo visualizzata nel Button
image: un oggetto Gtk.Image che rappresenta l’immagine sul Button.
>>> button = Gtk.Button() >>> button <Gtk.Button object at 0xb4a36edc (GtkButton at 0x88e3330)>
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):
>>> button.get_property("label")
>>> button.set_property("label", "Click")
>>> button.get_property("label")
'Click'
oppure con i metodi getter e setter specifici get_*property_name*() e
set_*property_name*(value):
>>> button.set_label("OK")
>>> button.get_label()
'OK'
Per creare un Button, esiste un metodo “scorciatoia”, new_with_label(label):
button1 = Gtk.Button.new_with_label("Click")
Le properties principali di un Gtk.Button sono:
| Name | Type | Flags | Short Description | |
|---|---|---|---|---|
| always-show-image | bool | r/w/c/en | Se l’immagine verrà sempre visualizzata | |
| image | Gtk.Widget | r/w/en | Il Child widget visualizzato a fianco del testo del button | |
| image-position | Gtk.PositionType | r/w/en | La posizione dell’immagine relativamente al testo | |
| label | str | r/w/c/en | Il testo del widget label nel button (se il button ne contiene una) | |
| relief | Gtk.ReliefStyle | r/w/en | Lo stile del bordo del button | |
| use-underline | bool | r/w/c/en | Se settato, l’underline prima di un carattere, ne identifica il mnemonic accelerator key |
| Name | Type | Flags | Short Description |
|---|---|---|---|
| active | bool | r/w/en | Se lo switch è ON o OFF |
| state | bool | r/w/en | lo stato di backend |
>>> switch.set_active(True) >>> switch.get_active() True
Segnali
I segnali principali sono due:
| Name | Short Description |
|---|---|
| activate | è un action-signal ovvero una volta emesso, causa lo spostamento della slitta del widget |
| state-set | quando viene emesso, cambia lo stato principale del widget |
Nota:
Non si dvrebbe mai connettere lo switch al segnale “activate”, che una volta emesso
(in altri ambiti), causerebbe lo spostamento della slitta del widget stesso.
E’ sempre bene connettere lo switch, al segnale “notify::active”.
Questo segnale si utilizza per notificare il cambiamento di una property.
Metodi
Di seguito i metodi utilizzabili con il widget Gtk.Switch:
new()
Metodo costruttore che crea un nuovo Gtk.Switch.
get_active()
Ritorna lo stato dello Switch.
get_state()
Ritorna lo stato principale dello Switch.
set_active(is_active)
Setta lo stato dello Switch. Se is_active è True, lo Switch sarà su ON, altrimenti su OFF.
Parametri:
is_active: il boolean che setta lo switch attivo;
set_state(state)
Setta lo stato dello Switch. Se non è stato settato appositamente un Delay, è la stessa cosa
di “active”. Ovvero “active” e “state” sono sincronizzati.
Parametri:
state: il boolean che setta lo stato dello switch;
actvate()
emette un segnale di tipo “activate”.
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="Switch Demo")
self.set_border_width(10)
hbox = Gtk.Box(spacing=6)
self.add(hbox)
switch1 = Gtk.Switch(active=False)
switch1.name = "Switch1"
switch2 = Gtk.Switch(active=True)
switch2.name = "Switch2"
# Bindings
switch1.connect("notify::active", self.on_switch_activated)
switch2.connect("notify::active", self.on_switch_activated)
# Layout
hbox.pack_start(switch1, True, True, 0)
hbox.pack_start(switch2, True, True, 0)
def on_switch_activated(self, switch, gparam):
if switch.get_active():
state = "on"
else:
state = "off"
print("%s was turned %s" % (switch.name, state))
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
link di riferimento:
PyGObject: Gtk.Stack, Gtk.StackSwitcher
torna all’indice degli appunti
Stack
Il widget Gtk.Stack è un contenitore che mostra i suoi widget
uno alla volta. Le transizioni tra una “pagina” e l’altra, possono essere a scorrimento o sfumate
a seconda della preferenza. Tale animazione può essere settata con il metodo
Gtk.Stack.set_transition_type() e rispetta il settaggio “gtk-enable-animations” (Gtk.Setting).
Le properties principali del widget-parent contenitore sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| hhomogeneous | bool | r/w/en | Se il sizing orizzontale è omogeneo |
| homogeneous | bool | r/w/en | Se il sizing è Homogeneous |
| interpolate-size | bool | r/w/en | Se la larghezza debba o meno cambiare passando da un child all’altro con size diversi |
| transition-duration | int | r/w/en | La durata dell’animazione in millisecondi |
| transition-running | bool | r | Se la transizione è in corso d’opera o meno |
| transition-type | Gtk.StackTransitionType | r/w/en | Il tipo di animazione usata per la transizione |
| vhomogeneous | bool | r/w/en | Se il sizing Verticale è omogeneo |
| visible-child | Gtk.Widget | r/w/en | il widget attualmente visibile nello stack |
| visible-child-name | str | r/w/en | Il nome del widget attualmente visibile nello stack |
Le properties principali dei child widgets sono:
| Name | Type | Flags | Short Description | |
|---|---|---|---|---|
| icon-name | str | None | r/w | Il nome dell’icona del child widget |
| name | str | None | r/w | Il nome del child widget |
| needs-attention | bool | False | r/w | Se il child widget necessita attenzione |
| position | int | 0 | r/w | L’indice del child widget nel parent widget |
| title | str | None | r/w | Il titolo del child widget |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.Stack, i principali
metodi sono:
new()
Crea un nuovo widget contenitore Gtk.Stack.
>>> import gi
... gi.require_version('Gtk', '3.0')
... from gi.repository import Gtk
...
>>> stack = Gtk.Stack.new()
add_named(child, name)
Aggiunge una child-page allo stack. Il child è identificato dal nome.
Parametri:
child: il child (Gtk.Widget) da aggiungere allo stack;
name: il nome che identifica il child aggiunto allo stack;
add_titled(child, name, title)
Aggiunge una child-page allo stack. Il child è identificato dal nome.
Il titolo title sarà utilizzato dal Gtk.StackSwitcher (trattato più avanti)
per rappresentare il child nella tab bar.
Parametri:
child: il child (Gtk.Widget) da aggiungere allo stack;
name: il nome che identifica il child aggiunto allo stack;
title: il title da utilizzare per il child;
>>> label_1 = Gtk.Label("First page label")
>>> stack.add_titled(child=label_1, name="label_1", title="First page label")
get_child_by_name(name)
Ritorna il child widget che ha il nome passato come argomento, altrimenti None
se non ci sono children con quel nome.
Parametri:
name: il nome del child widget che vogliamo recuperare dallo stack;
>>> stack.get_child_by_name("label_1")
<Gtk.Label object at 0x0000000004f47400 (GtkLabel at 0x0000000004971260)>
get_hhomogeneous()
Ritorna True se lo stack ha un sizing orizzontale omogeneo.
get_homogeneous()
Ritorna True se lo stack ha un sizing omogeneo (sia orizzontale che verticale).
get_interpolate_size()
Ritorna True se lo stack esegue l’interpolazione tra le dimensioni dei children,
quando avviene lo switch tra le pagine.
get_transition_duration()
Ritorna la durata della transizione espressa in millisecondi.
get_transition_running()
Ritorna True se nello stack attualmente sta avvenendo una transizione
get_transition_type()
Ritorna il tipo di animazione (Gtk.StackTransitionType) che sarà usata nella transizione tra pagine.
get_vhomogeneous()
Ritorna True se lo stack ha un sizing verticale omogeneo.
get_visible_child()
Ritorna il child visibile corrente nello stack, o None, se non ci sono children visibili.
get_visible_child_name()
Ritorna il nome del child visibile corrente nello stack, o None se non ci sono children visibili.
set_hhomogeneous(hhomogeneous)
Setta se il Gtk.Stack debba avere un sizing orizzontale omogeneo o no. Se settiamo a True,
lo stack richiederà la stessa larghezza per tutti i suoi child widgets, altrimenti lo stack potrà
cambiare larghezza quando un child widget differente diventerà visibile.
Parametri:
hhomogeneous: il boolean che settato a True rende lo stack omogeneo orizzontalmente;
set_homogeneous(homogeneous)
Setta se il Gtk.Stack debba avere un sizing omogeneo (sia verticale che orizzontale) o no.
Se settiamo a True, lo stack richiederà lo stesso spazio per tutti i suoi child
widgets, altrimenti lo stack potrà cambiare dimensioni quando un child widget differente diventerà
visibile.
Parametri:
homogeneous: il boolean che settato a True rende
lo stack omogeneo (sia orizzontalmente che verticalmente);
set_interpolate_size(interpolate_size)
Setta se lo stack interpolerà le sue dimensioni quando cambia il child visibile.
Se la property di Gtk.Stack “:interpolate-size”=True, lo stack stesso interpolerà le proprie
dimensioni, tra quelle attuali e quelle che prenderà dopo la modifica del child visibile,
in accordo con la durata della transizione.
Parametri:
interpolate_size: Il boolean che settato a True
esegue l’interpolazione;
set_transition_duration(duration)
Setta la durata della transizione tra le “pagine”.
Parametri:
duration: la durata della transizione in millisecondi;
set_transition_type(transition)
Setta il tipo di animazione che sarà usata per la transizione tra pagine, nello stack.
Sono disponibili diversi tipi di animazioni a scorrimento e sfumate.
Parametri:
transition: l’oggetto Gtk.StackTransitionType
corrispondente all’animazione desiderata.
set_vhomogeneous(vhomogeneous)
Setta se il Gtk.Stack debba avere un sizing verticale omogeneo o no. Se settiamo a True,
lo stack richiederà la stessa altezza per tutti i suoi child widgets, altrimenti lo stack potrà
cambiare altezza quando un child widget differente diventerà visibile.
Parametri:
vhomogeneous: il boolean che settato a True rende lo stack omogeneo verticalmente;
set_visible_child(child)
Rende un widget il child visibile dello stack.
Se il widget è diverso dal child visibile corrente, avverrà la transizione in accordo con il
transition type corrente. Nota: il child widget deve essere esso stesso visibile
(Gtk.Widget.show()) per poter diventare il child visibile dello stack!
Parametri:
child: il child widget che vogliamo rendere visibile;
set_visible_child_full(name, transition)
Rende il widget con il nome passato come argomento, il child visibile dello stack e decide quale
transizione utilizzare.
Nota: il child widget deve essere esso stesso visibile (Gtk.Widget.show()) per
poter diventare il child visibile dello stack!
Parametri:
name: il nome del child widget che vogliamo rendere visibile;
transition: l’oggetto Gtk.StackTransitionType corrispondente all’animazione desiderata.
set_visible_child_name(name)
Rende il widget con il nome passato come argomento, il child visibile dello stack.
Se il widget è diverso dal child visibile corrente, avverrà la transizione in accordo con il
transition type corrente.
Nota: il child widget deve essere esso stesso visibile (Gtk.Widget.show()) per
poter diventare il child visibile dello stack!
Parametri:
name: il nome del child widget da rendere visibile;
StackSwitcher
Il widget Gtk.StackSwitcher agisce come controller dei widget Gtk.Stack.
In pratica visualizza una riga di bottoni per spostarsi tra le pagine associate allo stack widget.
I contenuti dei bottoni derivano dalle properties dei child del Gtk.Stack; la visibilità dei
bottoni nel widget Gtk.StackSwitcher è controllata dalla visibilità del child, nel Gtk.Stack.
E’ possibile associare multipli widget Gtk.StackSwitcher con lo stesso Gtk.Stack.
Le properties principali del widget StackSwitcher sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| icon-size | int | r/w/en | Symbolic size to use for named icon |
| stack | Gtk.Stack | r/w/c | Stack |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.StackSwitcher,
i principali metodi sono:
new()
Crea un nuovo widget Gtk.StackSwitcher.
get_stack()
Ritorna il widget stack, settato con il metodo Gtk.StackSwitcher.set_stack().
set_stack(stack)
Setta il widget stack che sarà controllato dal widget StackSwitcher.
Parametri:
stack: il widget Gtk.Stack da controllare o None;
Di seguito un codice di esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
class GWindow(Gtk.Window):
def __init__(self):
super().__init__(title="Stack Demo")
self.set_border_width(10)
stack = Gtk.Stack.new()
stack.set_transition_type(Gtk.StackTransitionType.SLIDE_LEFT_RIGHT)
stack.set_transition_duration(1000)
checkbutton = Gtk.CheckButton(label="First page checkbutton")
stack.add_titled(child=checkbutton, name="check", title="Check Button")
label = Gtk.Label(label="Second page label")
stack.add_titled(child=label, name="label", title="Label")
stack_switcher = Gtk.StackSwitcher.new()
stack_switcher.set_stack(stack)
# layout
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
vbox.pack_start(stack_switcher, True, True, 0)
vbox.pack_start(stack, True, True, 0)
self.add(vbox)
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 Stack
Gtk3 StackSwitcher
PyGObject: Gtk.Spinner
torna all’indice degli appunti
Spinner
Il widget Gtk.Spinner è un widget provvisto di uno spinner animato e viene utilizzato come
alternativa alla progressbar classica, quando dobbiamo segnalare che l’applicazione sta eseguendo
delle operazioni. Non c’è molto da dire sull’animazione, se non che non è di tipo progressivo
(come la progressbar), che si attiva con il metodo start() e si interrompe con
il metodo stop().
Per creare un Spinner si utilizza il costruttore Gtk.Spinner(**kwargs).
L’unica proprietà è “active” ed è un boolean che indica se il widget è attivo o meno.
Metodi
Di seguito i metodi utilizzabili con il widget Gtk.Spinner:
new()
Metodo costruttore che crea un nuovo oggetto Gtk.Spinner.
start()
Avvia l’animazione dello spinner.
stop()
ferma l’animazione dello spinner.
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="Spinner")
self.set_default_size(300, 200)
self.set_border_width(3)
button = Gtk.ToggleButton(label="Start")
self.spinner = Gtk.Spinner()
# layout
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=5)
vbox.pack_start(button, True, True, 0)
vbox.pack_start(self.spinner, True, True, 0)
self.add(vbox)
# bindings
button.connect("toggled", self.on_button_toggled)
def on_button_toggled(self, button):
if button.get_active():
self.spinner.start()
button.set_label("Stop")
else:
self.spinner.stop()
button.set_label("Start")
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.SpinButton
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:
PyGObject: Gtk.ScrolledWindow
torna all’indice degli appunti
ScrolledWindow
Il Gtk.ScrolledWindow è un contenitore che accetta un singolo child widget, lo rende “scrollable”
(scorrevole) usando, sia le scrollbars interne, sia con adjustments
associati dall’esterno e, opzionalmente, disegnando un frame attorno al child.
I Widgets con supporto nativo allo scrolling, cioè quelle classi che implementano l’interfaccia
Gtk.Scrollable, vengono aggiunti direttamente. Invece, per quei tipi di widgets
che non implementano tale interfaccia, si utilizza la classe Gtk.Viewport,
che funge da adattatore, fornendo la scrollabilità mancante.
Derivando Gtk.ScrolledWindow da Gtk.Container permette l’utilizzo del metodo
add() che intelligentemente tiene conto che un widget sia un oggetto
Gtk.Scrollable o meno. In caso negativo, Gtk.ScrolledWindow lascia gestire il
child alla classe Gtk.Viewport, che fornisce il child dell’interfaccia mancante.
Se non si specifica esplicitamente che la policy della Gtk.ScrolledWindow sia di tipo
Gtk.PolicyType.NEVER, o Gtk.PolicyType.EXTERNAL, allora la
Gtk.ScrolledWindow, aggiungerà i widget Gtk.Scrollbar attorno al child automaticamente.
La posizione di scroll del child, e se siano applicabili le scrollbars, viene deciso attraverso le
properties “:hadjustment” e “:vadjustment”.
Qualora il comportamento della Gtk.ScrolledWindow non fosse quello desiderato, è sempre possibile
settare il proprio scrolling ricorrendo ai widget Gtk.Scrollbar.
Le properties principali sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| hadjustment | Gtk.Adjustment | r/w/c | Il Gtk.Adjustment relativo alla posizione orizzontale |
| hscrollbar-policy | Gtk.PolicyType | r/w/en | la policy che regola quando visualizzare la scrollbar orizzontale |
| kinetic-scrolling | bool | r/w/en | la modalità di Kinetic scrolling |
| max-content-height | int | r/w/en | La massima altezza che la scrolled window allocherà per il proprio contenuto |
| max-content-width | int | r/w/en | La massima larghezza che la scrolled window allocherà per il proprio contenuto |
| min-content-height | int | r/w/en | La minima altezza che la scrolled window allocherà per il proprio contenuto |
| min-content-width | int | r/w/en | La minima larghezza che la scrolled window allocherà per il proprio contenuto |
| overlay-scrolling | bool | r/w/en | Settato a True fa comparire le scrollbar solo con il mouse. False, sempre presenti |
| propagate-natural-height | bool | r/w/en | Calcola o meno la naturale altezza del child e la propaga alla scrolled window |
| propagate-natural-width | bool | r/w/en | Calcola o meno la naturale larghezza del child e la propaga alla scrolled window |
| shadow-type | Gtk.ShadowType | r/w/en | Lo stile dell’angolo attorno ai contenuti |
| vadjustment | Gtk.Adjustment | r/w/c | Il Gtk.Adjustment relativo alla posizione verticale |
| vscrollbar-policy | Gtk.PolicyType | r/w/en | la policy che regola quando visualizzare la scrollbar verticale |
| window-placement | Gtk.CornerType | r/w/en | Dove sono posizionati i contenuti, rispetto alle scrollbars |
Metodi
Oltre ai soliti getter e setter relativi alle properties dell’oggetto Gtk.ScrolledWindow,
principali metodi sono:
new(hadjustment, vadjustment)
Crea una nuova scrolled window. I due argomenti sono gli adjustments
della scrolled window e saranno condivisi tra le scrollbars e il child widget in modo da
sincronizzare le scrollbars con il child stesso.
Di solito si passa None per gli adjustments, in modo che la scrolled window
li crei per noi.
Parametri:
hadjustment: l’adjustment (Gtk.Adjustment) orizzontale, o None;
vadjustment: l’adjustment (Gtk.Adjustment) verticale, o None;
get_capture_button_press()
Ritorna True se il click button viene catturato durante il kinetic scrolling.
get_hadjustment()
Ritorna l’adjustment (Gtk.Adjustment) della scrollbar orizzontale, usato per connetterla alla
funzionalità di scroll orizzontale del child widget.
get_hscrollbar()
Ritorna la scrollbar orizzontale della scrolled window.
get_kinetic_scrolling()
Ritorna True se è stato impostato il kinetic scrolling.
get_max_content_height()
Ritorna il valore della massima altezza dedicata dalla scrolled window, ai contenuti.
Se non è stato impostato alcun limite, il metodo ritorna -1.
get_max_content_width()
Ritorna il valore della massima larghezza dedicata dalla scrolled window, ai contenuti.
Se non è stato impostato alcun limite, il metodo ritorna -1.
get_min_content_height()
Ritorna il valore della minima altezza dedicata dalla scrolled window, ai contenuti.
Se non è stato impostato alcun limite, il metodo ritorna -1.
get_min_content_width()
Ritorna il valore della minima larghezza dedicata dalla scrolled window, ai contenuti.
Se non è stato impostato alcun limite, il metodo ritorna -1.
get_overlay_scrolling()
Ritorna True se l’overlay scrolling è abilitato per la scrolled window.
L’overlay scrolling visualizza la scrollbar solo se il puntatore mouse è sopra di essa.
Per averla sempre presente settare la property “overlay-scrolling” a False.
get_placement()
Ritorna il valore dell’enum Gtk.CornerType relativo al posizionamento dei contenuti,
rispetto alle scrollbars.
vedere Gtk.ScrolledWindow.set_placement() per il settaggio.
get_policy()
Ritorna una tupla con i due valori di policy Gtk.PolicyType, settati per le scrollbars
orizzontale e verticale. Vedere Gtk.ScrolledWindow.set_policy() per il settaggio.
get_propagate_natural_height()
Ritorna True se la naturale altezza richiesta dal child, viene propagata sulla
scrolled window.
get_propagate_natural_width()
Ritorna True se la naturale larghezza richiesta dal child, viene propagata sulla
scrolled window.
get_shadow_type()
Ritorna l’enum Gtk.ShadowType settato per la scrolled window, ovvero il tipo di
outline della window.
Vedere Gtk.ScrolledWindow.set_shadow_type(), per il settaggio.
get_vadjustment()
Ritorna l’adjustment (Gtk.Adjustment) della scrollbar verticale, usato per connetterla alla
funzionalità di scroll verticale del child.
get_vscrollbar()
Ritorna la scrollbar verticale della scrolled window.
set_capture_button_press(capture_button_press)
Modifica il comportamento della scrolled window rispetto all’evento iniziale che possibilmente dà
inizio al kinetic scrolling.
Quando capture_button_press viene settato a True, l’evento viene
catturato dalla scrolled window, e quindi ripetuto in seguito se è destinato al child widget.
Questo settaggio ha effetto solo se il kinetic scrolling è abilitato.
Parametri:
capture_button_press: il boolean che settato a True
permette alla scrolled window di catturare i click button;
set_hadjustment(hadjustment)
Setta l’adjustment della scrollbar orizzontale.
Parametri:
hadjustment: l’adjustment da usare o None per
crearne uno nuovo;
set_kinetic_scrolling(kinetic_scrolling)
Abilita/Disabilita il kinetic scrolling. Il kinetic scrolling si applica solo ai dispositivi con
source Gdk.InputSource.TOUCHSCREEN.
Parametri:
kinetic_scrolling: il boolean che abilita/disabilita il kinetic
scrolling;
set_max_content_height(height)
Setta la massima altezza che la scrolled window dovrebbe lasciare visibile.
Non settare tale valore ad uno inferiore al valore della property “min-content-height”.
Parametri:
height: massima altezza (int) dei contenuti visibili;
set_max_content_width(width)
Setta la massima larghezza che la scrolled window dovrebbe lasciare visibile.
Non settare tale valore ad uno inferiore al valore della property “min-content-width”.
Parametri:
width: massima larghezza (int) dei contenuti visibili;
set_min_content_height(height)
Setta la minima altezza che la scrolled window dovrebbe lasciare visibile.
Non settare tale valore ad uno superiore al valore della property “max-content-height”.
Parametri:
height: minima altezza (int) dei contenuti visibili;
set_min_content_width(width)
Setta la minima larghezza che la scrolled window dovrebbe lasciare visibile.
Non settare tale valore ad uno superiore al valore della property “max-content-width”.
Parametri:
height: minima larghezza (int) dei contenuti visibili;
set_overlay_scrolling(overlay_scrolling)
Abilita/Disabilita overlay scrolling per la scrolled window, cioè visualizza la scrollbar solo se
il puntatore mouse è sopra di essa.
Parametri:
overlay_scrolling: il boolean che attiva/disattiva l’overlay
scrolling;
set_placement(window_placement)
Setta il posizionamento dei contenuti (child) rispetto alle scrollbars.
Il valore di default è l’enum Gtk.CornerType.TOP_LEFT, che significa che il child è nell’angolo
in alto a sinistra, con le scrollbars sotto di esso e a destra.
Gli altri valori settabili sono Gtk.CornerType.TOP_RIGHT, Gtk.CornerType.BOTTOM_LEFT e
Gtk.CornerType.BOTTOM_RIGHT.
Parametri:
window_placement: l’enum (Gtk.CornerType) che definisce la
posizione del child rispetto alle scrollbars.
set_policy(hscrollbar_policy, vscrollbar_policy)
Setta le policy di visibilità delle scrollbars orizzontale e verticale.
L’enum che decide quando la scrollbar debba apparire, può assumere i seguenti valori:
Gtk.PolicyType.ALWAYS: la scrollbar è sempre presente;
Gtk.PolicyType.NEVER: la scrollbar non è mai presente;
Gtk.PolicyType.AUTOMATIC: la scrollbar è presente solo se necessario;
Parametri:
hscrollbar_policy: l’enum (Gtk.PolicyType) della policy per la
scrollbar orizzontale;
vscrollbar_policy: l’enum (Gtk.PolicyType) della policy per la
scrollbar verticale;
set_propagate_natural_height(propagate)
Settato a True, calcola l’altezza naturale del child e la propaga attraverso la
scrolled window.
Parametri:
propagate: il boolean che attiva/disattiva la propagazione
dell’altezza del child alla scrolled window;
set_propagate_natural_width(propagate)
Settato a True, calcola la larghezza naturale del child e la propaga attraverso
la scrolled window.
Parametri:
propagate: il boolean che attiva/disattiva la propagazione
della larghezza del child alla scrolled window;
set_shadow_type(type)
Modifica il tipo di shadow attorno al child della scrolled window.
Il valori impostabili, dell’enum Gtk.ShadowType sono:
NONE (0): nessun outline
IN (1): outline smussato verso l’interno;
OUT (2): outline smussato verso l’esterno;
ETCHED_IN (3): outline con aspetto sunken 3d (scavato);
ETCHED_OUT (4): outline con aspetto raised 3d (sporgente);
Parametri:
type: l’enum (Gtk.ShadowType) che disegna il tipo di shadow
attorno al child della scrolled window;
set_vadjustment(vadjustment)
Setta l’adjustment della scrollbar verticale.
Parametri:
vadjustment: l’adjustment da usare o None per
crearne uno nuovo;
unset_placement()
Resetta il placement del child rispetto alle scrollbars. Se non è settato nessun placement per la
scrolled window, di default sarà Gtk.CornerType.TOP_LEFT.
Vedere Gtk.ScrolledWindow.set_placement() e Gtk.ScrolledWindow.get_placement().
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(250, 100)
header = Gtk.HeaderBar(title="ScrolledWindow example")
header.set_subtitle("Serie A")
header.props.show_close_button = True
self.set_titlebar(header)
listbox = Gtk.ListBox()
listbox.set_selection_mode(Gtk.SelectionMode.NONE)
listbox = Gtk.ListBox()
teams = ("Inter", "Juventus", "Lazio", "Atalanta", "Roma", "Verona",
"Bologna", "Cagliari", "Parma", "Milan", "Napoli", "Sassuolo",
"Torino", "Fiorentina", "Udinese", "Sampdoria", "Lecce",
"Genoa", "Brescia", "Spal")
for team in teams:
listbox.add(Gtk.Label(label=team))
scrolled = Gtk.ScrolledWindow()
scrolled.set_policy(hscrollbar_policy=Gtk.PolicyType.NEVER,
vscrollbar_policy=Gtk.PolicyType.AUTOMATIC)
scrolled.add(listbox)
scrolled.set_property("max-content-height", 5)
scrolled.set_property("overlay-scrolling", True)
self.add(scrolled)
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.RadioButton
torna all’indice degli appunti
RadioButton
Il widget Gtk.RadioButton eredita da Gtk.ToggleButton, ma ha la particolarità di lavorare in gruppo.
In un gruppo di più RadioButtons, solo un RadioButton può essere selezionato, deselezionando di
conseguenza gli altri. Viene generalmente collegato ad una callback che viene invocata quando lo
stesso widget viene premuto e viene di fatto emesso il segnale “toggled”.
Per creare un RadioButton si utilizza il costruttore Gtk.RadioButton(*args, **kwargs),
dove gli argomenti più significativi sono “”label” e “image”.
label: è una stringa di testo visualizzata nel RadioButton
image: un oggetto Gtk.Image che rappresenta l’immagine sul RadioButton.
>>> rbutton = Gtk.RadioButton() >>> rbutton <Gtk.RadioButton object at 0xb4b9de3c (GtkRadioButton at 0x952b110)>
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):
>>> rbutton.get_property("label")
>>> rbutton.set_property("label", "Button 1")
>>> rbutton.get_property("label")
'Button 1'
oppure con i metodi getter e setter specifici get_*property_name*() e
set_*property_name*(value):
>>> rbutton.set_label("RadioButton 1")
>>> rbutton.get_label()
'RadioButton 1'
La property principale, oltre a quelle ereditate dai vari widget, come ad esempio Gtk.ToggleButton
e Gtk.Button, sono:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| group | Gtk.RadioButton | w | il gruppo di radio button a cui appartiene questo widget |
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).
Il segnale che fondamentalmente interessa il radiobutton è “toggled” e viene emesso quando un
radiobutton, che precedentemente non era selezionato, viene cliccato (clicked()).
Per conoscere lo stato di un radiobutton, si utilizza il metodo get_active()
>>> def on_button_toggled(button):
... if button.get_active():
... state = "on"
... else:
... state = "off"
... print("{} was turned {}".format(button.get_label(), state))
...
>>> button1 = Gtk.RadioButton.new_with_label_from_widget(None, "Button 1")
>>> button2 = Gtk.RadioButton.new_with_label_from_widget(button1, "Button 2")
>>> button1.connect("toggled", on_button_toggled)
60
>>> button2.connect("toggled", on_button_toggled)
61
>>> button1.toggled()
Button 1 was turned on
>>> button1.get_active()
True
>>> button2.get_active()
False
>>> button2.clicked()
Button 1 was turned off
Button 2 was turned on
>>> button1.clicked()
Button 2 was turned off
Button 1 was turned on
Image
Per inserire un’immagine all’interno del widget, creiamo prima un oggetto Gtk.Image e lo settiamo
nel widget che lo conterrà. Per recuperarla, si userà il getter specifico get_image()
>>> image = Gtk.Image.new_from_file("OK24.png")
>>> button1.set_image(image)
>>> button1.get_image() == image
True
Metodi
Per creare un RadioButton, esistono due metodi “scorciatoia”, new_from_widget(radio_group_member)
e new_with_label_from_widget(radio_group_member, label):
“radio_group_member”: ovviamente è il widget già presente nel gruppo del quale vogliamo che il radiobutton faccia parte;
“label”: è il testo del radiobutton;
Ovviamente il primo elemento del gruppo, non avrà widget di riferimento, quindi il l’argomento “radio_group_member” sarà None.
>>> button1 = Gtk.RadioButton.new_with_label_from_widget(radio_group_member=None, label="Button 1") >>> button2 = Gtk.RadioButton.new_from_widget(radio_group_member=button1) >>> button1.get_group() == button2.get_group() True
Di seguito i metodi utilizzabili con il widget Gtk.RadioButton:
new(group)
Metodo costruttore che crea un nuovo Gtk.RadioButton.
Parametri:
group: un gruppo di radiobutton esistenti ([Gtk.RadioButton, ]),
o None, se stiamo crando un nuovo gruppo;
new_from_widget(radio_group_member)
Metodo costruttore che crea un nuovo Gtk.RadioButton, aggiungendolo allo stesso gruppo di
radio_group_member, che è un Gtk.RadioButton esistente.
Parametri:
radio_group_member: un Gtk.RadioButton esistente;
new_with_label(group, label)
Metodo costruttore che crea un nuovo Gtk.RadioButton con una label di testo associata.
Parametri:
group: un gruppo di radiobutton esistenti ([Gtk.RadioButton, ]),
o None, se stiamo crando un nuovo gruppo;
label: il testo visualizzato a fianco del radiobutton
new_with_label_from_widget(radio_group_member, label)
Metodo costruttore che crea un nuovo Gtk.RadioButton con una label di testo aggiungendolo allo
stesso gruppo a cui appartiene radio_group_member.
Parametri:
radio_group_member: un Gtk.RadioButton esistente;
label: il testo visualizzato a fianco del radiobutton;
new_with_mnemonic(group, label)
Metodo costruttore che crea un nuovo Gtk.RadioButton contenente una label con mnemonic,
aggiungendolo al gruppo specificato. La Label sarà creata usando Gtk.Label.new_with_mnemonic(),
in modo tale che la sottolineatura nella label, indichi il “mnemonic” del radiobutton.
Parametri:
group: un gruppo di radiobutton esistenti ([Gtk.RadioButton, ]),
o None, se stiamo crando un nuovo gruppo;
label: il testo visualizzato a fianco del radiobutton, comprensivo
di sottolineature identificanti gli “mnemonic” del radiobutton;
new_with_mnemonic_from_widget(radio_group_member, label)
Metodo costruttore come il precedente, ma il primo parametro non sarà un gruppo, ma un
Gtk.RadioButton, dal quale attingere il gruppo. Passando None, verrà creato un nuovo gruppo.
Parametri:
radio_group_member: un Gtk.RadioButton esistente;
label: il testo visualizzato a fianco del radiobutton, comprensivo
di sottolineature identificanti gli “mnemonic” del radiobutton;
get_group()
Ritorna il gruppo assegnato al RadioButton, ovvero una lista di radiobuttons dello stesso gruppo:
>>> button1.get_group() [<Gtk.RadioButton object at 0xb4b44fa4 (GtkRadioButton at 0x9ba8220)>, <Gtk.RadioButton object at 0xb72407d4 (GtkRadioButton at 0x9ba8100)>] >>> button1.get_group() == button2.get_group() True
join_group(group_source)
Unisce un Gtk.RadioButton al gruppo di un altro Gtk.RadioButton.
Parametri:
group_source: un oggetto Gtk.RadioButton al cui gruppo vogliamo unire
il radiobutton corrente. Passando None, il radiobutton corrente viene rimosso dall’eventuale
gruppo di appartenenza.
>>> button3 = Gtk.RadioButton.new()
>>> button3.set_label("Button 3")
>>> button3.get_group()
[<Gtk.RadioButton object at 0xb355c284 (GtkRadioButton at 0x9ba8340)>]
>>> button3.join_group(button1)
>>> for b in button3.get_group():
... print(b.get_label())
...
Button 3
Button 2
Button 1
set_group(group)
Setta il gruppo del Gtk.RadioButton. Attenzione che questo non modificherà automaticamente il
layout della nostra interfaccia, quindi per mostrare questa modifica, sarà necessario riadattare
l’interfaccia stessa.
Parametri:
group: un gruppo di radiobutton esistente, o None.
toggled()
emette un segnale di tipo “toggled”.
clicked()
emette un segnale di tipo “clicked”.
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, controller=None):
self.controller = controller
super().__init__(title="RadioButton Demo")
self.set_border_width(10) # sets space around the inner widget (hbox)
hbox = Gtk.Box(spacing=6)
self.add(hbox)
image = Gtk.Image.new_from_file("OK24.png")
button1 = Gtk.RadioButton.new_with_label_from_widget(None, "Button 1")
button1.set_image(image)
button2 = Gtk.RadioButton.new_from_widget(button1)
button2.set_label("Button 2")
button3 = Gtk.RadioButton.new_with_label_from_widget(button1,
"Button 3")
# Bindings
button1.connect("toggled", self.on_button_toggled)
button2.connect("toggled", self.on_button_toggled)
button3.connect("toggled", self.on_button_toggled)
# Layout
hbox.pack_start(button1, False, False, 0)
hbox.pack_start(button2, False, False, 0)
hbox.pack_start(button3, False, False, 0)
def on_button_toggled(self, button):
if button.get_active():
state = "on"
else:
state = "off"
print("{} was turned {}".format(button.get_label(), state))
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
PyGObject: Gtk.ProgressBar
torna all’indice degli appunti
ProgressBar
Il widget Gtk.ProgressBar è un widget utilizzato per visualizzare il progresso di un’operazione
di lunga durata. La progressbar può essere utilizzata in due modi, percentage
per visualizzare lo stato di avanzamento progressivo dell’operazione e activity,
per visualizzare un cursore rimbalzante.
Quando dobbiamo visualizzare lo stato di un’operazione dall’esito certo, ad esempio il download di
un file di grandezza nota, possiamo utilizzare la progressbar in percentage mode.
Questo richiede il periodico richiamo del metodo Gtk.ProgressBar.set_fraction(),
per aggiornare lo stato della progressbar.
Se invece non conosciamo l’ammontare del carico di lavoro, possiamo utilizzare una progressbar
in activity mode, il chè richiede la chiamata periodica al metodo
Gtk.ProgressBar.pulse(), che mostra un cursore che fa avanti e indietro indefinitivamente.
Per creare un ProgressBar si utilizza il costruttore Gtk.ProgressBar(**kwargs).
Le properties della progressbar sono le seguenti:
| Name | Type | Flags | Short Description |
|---|---|---|---|
| ellipsize | Pango.EllipsizeMode | r/w/en | l’oggetto Pango.EllipsizeMode che indica dove applicare l’ellipse (“…”) sulla stringa |
| fraction | float | r/w/en | la porzione completata della progressbar |
| inverted | bool | r/w/en | un boolean che settato a True, inverte la direzione della progress bar (da destra verso sinistra) |
| pulse-step | float | r/w/en | la porzione di progressbar da utilizzare come blocco in activity-mode (avanti e indietro) |
| show-text | bool | r/w/en | un boolean che settato a True permette di mostrare un testo sulla progressbar |
| text | str | r/w | la stringa di testo da visualizzare sulla progressbar |
E’ possibile settare le properties del widget 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, GLib, Gdk
>>> progressbar = Gtk.ProgressBar()
>>> progressbar.set_property("text", "progress 0%")
>>> progressbar.get_property("text")
'progress 0%'
oppure con i metodi getter e setter specifici get_*property_name*() e
set_*property_name*(value):
>>> progressbar.get_inverted() False >>> progressbar.set_inverted(True) >>> progressbar.get_inverted() True
Metodi
Di seguito i metodi utilizzabili con il widget Gtk.ProgressBar:
new()
Metodo costruttore che crea un nuovo oggetto Gtk.ProgressBar.
get_ellipsize()
Ritorna l’oggetto Pango.EllipsizeMode con la posizione dell’ellipse (“…”)
utilizzata sulla stringa.
get_fraction()
Ritorna una frazione da 0.0 a 1.0 indicante la quantità di lavoro completato.
get_inverted()
Ritorna True se la progressbar è invertita, ovvero si riempie da destra verso sinistra.
get_pulse_step()
Ritorna la frazione utilizzata per il blocco in movimento nella activity mode.
get_show_text()
Ritorna True se il testo viene visualizzato nella progressbar.
get_text()
Ritorna il testo visualizzato nella progressbar, se presente, altrimenti ritorna None.
pulse()
Indica che un progresso indefinito è stato fatto, ma non è dato sapere quanto.
La chiamata a questo metodo causa l’entrata dell progressbar nell’ activity mode
(con un blocco che rimbalza avanti e indietro).
Ogni chiamata al metodo Gtk.ProgressBar.pulse() causa un piccolo spostamento del blocco e
questo piccolo spostamento viene settato con il metodo Gtk.ProgressBar.set_pulse_step().
set_ellipsize(mode)
Setta la posizione dell’ellipse da applicare al testo, quando non c’è abbastanza spazio per
visualizzare tutta la stringa.
Parametri:
mode: è un Enum Pango.EllipsizeMode
che definisce dove posizionare l’ellipse, 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;
set_fraction(fraction)
Definisce il riempimento della progress bar, indicando cioè la frazione di lavoro completato
rispetto al totale previsto.
Parametri:
fraction: è il float che indica quanto lavoro è stato completato
e va da 0.0 (vuota) a 1.0 (piena) inclusi.
set_inverted(inverted)
Inverte il senso di riempimento della progressbar, partendo da destra e riempendosi verso sinistra.
Parametri:
inverted: è il boolean che settato a True, inverte la progressbar;
set_pulse_step(fraction)
Setta la frazione di progressbar da utilizzare come blocco in movimento in activity mode.
Parametri:
fraction: il float che indica che frazione di progressbar utilizzare per il blocco in movimento. Va da 0.0 a 1.0;
set_show_text(show_text)
Setta se mostrare o meno il testo nella progressbar.
Parametri:
show_text: è il boolean che settato a True mostra il testo nella
progressbar;
set_text(text)
Setta il testo da visualizzare nelle progressbar.
Se text=None e la property di Gtk.ProgressBar “show-text”=True, verrà visualizzato al posto del
testo, il valore corrente della property “fraction”.
Parametri:
text: il testo da visualizzare nella progressbar o None;
Di seguito un codice d’esempio:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, GLib
class GWindow(Gtk.Window):
def __init__(self):
Gtk.Window.__init__(self, title="ProgressBar example")
self.value = 0
self.set_default_size(400, 100)
self.set_border_width(10)
self.progressbar = Gtk.ProgressBar()
self.progressbar.set_text("progress {}%".format(self.value))
self.progressbar.set_show_text(True)
self.button = Gtk.ToggleButton(label="Start")
# bindings
self.button.connect("toggled", self.on_toggle)
# layout
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
vbox.pack_start(self.button, True, True, 0)
vbox.pack_start(self.progressbar, True, True, 0)
self.add(vbox)
def on_toggle(self, button):
GLib.timeout_add(50, self.on_timeout, 1.0)
def on_timeout(self, new_value):
if self.button.get_active():
self.button.set_label("Stop")
self.value = self.progressbar.get_fraction() + new_value/100
self.progressbar.set_text("progress {}%".format(
int(self.value*100)))
if self.value > 1:
self.value = 0
self.progressbar.set_fraction(self.value)
return True # chiamo di nuovo la callback on_timeout
else:
self.button.set_label("Start")
return False # fermo la chiamata alla callback
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
In questo codice vediamo questa riga di codice particolare
GLib.timeout_add(50, self.on_timeout, 1.0)
La funzione di GLib timeout_add(time, callback, *args), permette di invocare una
callback dopo un determinato intervallo di tempo.
Questa callback viene richiamata fino a che non viene ritornato False.
Parametri:
time: è l’intervallo di tempo in millisecondi;
callback: è la funzione da chiamare;
*args: sono gli argomenti facoltativi da passare alla callback;
Qui sono reperibili le GLib functions.
Aspetto
Se volessimo modificare l’aspetto del widget, sarà possibile farlo ricorrendo a CSS.
Qui entrano in gioco 3 oggetti:
Gdk.Screen
Gtk.CssProvider
Gtk.StyleContext
L’oggetto Gdk.Screen viene utilizzato per specificare su quale Screen la top-level
window deve essere visualizzata.
CssProvider è un oggetto che implementa l’interfaccia Gtk.StyleProvider
e permette il parse di una stringa CSS-like, utilizzabile per personalizzare i widget.
Gtk.StyleContext memorizza le informazioni riguardanti la personalizzazione dei
widget e si occupa in tal senso, di chiedere le informazioni necessarie al Gtk.StyleProvider
collegato ad esso. L’iter è il seguente:
– si crea un’istanza di Gdk.Screen con il classmethod get_default(),
che ritorna lo screen di default per il display di default;
– si crea un’istanza di Gtk.CssProvider ed una di Gtk.StyleContext;
– Chiamiamo il metodo Gtk.StyleContext.add_provider_for_screen(screen, provider, priority),
con il quale associamo un global style-provider allo screen e decidendone la priorità.
Infine diciamo al provider di caricare la stringa CSS da parsare:
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, GLib, Gdk
class GWindow(Gtk.Window):
def __init__(self):
Gtk.Window.__init__(self, title="ProgressBar example")
self.value = 0
self.set_default_size(400, 100)
self.set_border_width(10)
self.progressbar = Gtk.ProgressBar()
self.progressbar.set_text("progress {}%".format(self.value))
self.progressbar.set_show_text(True)
css = b"""
trough {
min-height: 20px;
border: none;
}
text {
color: grey;
font: 12px Verdana;
}
progress {
border: none;
background-color: grey;
min-height: 20px;
}
"""
screen = Gdk.Screen.get_default()
provider = Gtk.CssProvider()
style_context = Gtk.StyleContext()
style_context.add_provider_for_screen(
screen, provider, Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION
)
provider.load_from_data(css)
self.button = Gtk.ToggleButton(label="Start")
# bindings
self.button.connect("toggled", self.on_toggle)
# layout
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
vbox.pack_start(self.button, True, True, 0)
vbox.pack_start(self.progressbar, True, True, 0)
self.add(vbox)
def on_toggle(self, button):
GLib.timeout_add(50, self.on_timeout, 1.0)
def on_timeout(self, new_value):
if self.button.get_active():
self.button.set_label("Stop")
self.value = self.progressbar.get_fraction() + new_value/100
self.progressbar.set_text("progress {}%".format(
int(self.value*100)))
if self.value > 1:
self.value = 0
self.progressbar.set_fraction(self.value)
return True # chiamo di nuovo la callback on_timeout
else:
self.button.set_label("Start")
return False # fermo la chiamata alla callback
if __name__ == "__main__":
win = GWindow()
win.connect("destroy", Gtk.main_quit)
win.show_all()
Gtk.main()
link di riferimento:
Linux counters
Visitatori
bancaldo™ 
Commenti recenti