bancaldo™

torna all’indice 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 degli appunti
Gtk3 Toolbar
Gnome Stock icons