<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="toolbar_builder.py" xml:lang="ca">

  <info>

    <title type="text">Toolbar created using Glade (Python)</title>

    <link type="guide" xref="beginner.py#menu-combo-toolbar"/>

    <link type="seealso" xref="toolbar.py"/>

    <link type="seealso" xref="grid.py"/>

    <link type="next" xref="menubar.py"/>

    <revision version="0.1" date="2012-07-17" status="draft"/>

    <credit type="author copyright">

      <name>Tiffany Antopolski</name>

      <email its:translate="no">tiffany.antopolski@gmail.com</email>

      <years>2012</years>

    </credit>

    <credit type="author copyright edit">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2012</years>

    </credit>

    <credit type="author copyright">

      <name>Sebastian Pölsterl</name>

      <email its:translate="no">sebp@k-d-w.org</email>

      <years>2011</years>

    </credit>

    <desc>A bar of buttons and other widgets</desc>

  </info>

  <title>Toolbar created using Glade</title>

  <media type="image" mime="image/png" src="media/toolbar.png"/>

  
This example is similar to <link xref="toolbar.py"/>, except we use Glade to create the toolbar in an XML .ui file.

<links type="sections"/>

<section id="glade">

<title>Creating the toolbar with Glade</title>

  To create the toolbar using the <link href="http://glade.gnome.org/">Glade Interface Designer</link>:

  <steps>

    <item>
Open Glade, and save the file as <file>toolbar_builder.ui</file>

          
<media type="image" src="media/glade_ui.png" width="900">

              Screenshot of Glade ui

           </media>

    </item>

    <item>
Under <gui>Containers</gui> on the left hand side, right click on the toolbar icon and select <gui>Add widget as toplevel</gui>.

          
<media type="image" src="media/glade_select_toolbar.png">

           Screenshot of toolbar icon in Glade ui

          </media>

    </item>

    <item>
Under the <gui>General</gui> tab on the bottom right, change the <gui>Name</gui> to <input>toolbar</input> and <gui>Show Arrow</gui> to <gui>No</gui>.

          
<media type="image" src="media/glade_toolbar_general.png">

             Screenshot of General tab

          </media>

    </item>

    <item>
Under the <gui>Common</gui> tab, set <gui>Horizontal Expand</gui> to <gui>Yes</gui>.

         
<media type="image" src="media/glade_toolbar_common.png">

              Screenshot of Common tab

          </media>

     </item>

     <item>
Right click on the toolbar in the top right and select <gui>Edit</gui>.  The <gui>Tool Bar Editor</gui> window will appear.

         
<media type="image" src="media/glade_toolbar_edit.png">

             Screenshot of where to right click to edit toolbar.

          </media>

   </item>

   <item>
We want to add 5 ToolButtons: New, Open, Undo, Fullscreen and Leave Fullscreen.  First, we will add the New ToolButton.

     <steps>

       <item>
Under <gui>Hierarchy</gui> tab, click <gui>Add</gui>.
</item>

       <item>
Change the name of the ToolItem to <input>new_button</input>.
</item>

       <item>
Scroll down and set <gui>Is important</gui> to <gui>Yes</gui>.  This will cause the label of the ToolButton to be shown, when you view the toolbar.
</item>

       <item>
Enter the <gui>action name</gui>: <input>app.new</input>.
</item>

       <item>
Change the <gui>Label</gui> to <input>New</input>.
</item>

       <item>
Select the <gui>New</gui> Stock Id from the drop down menu, or type <input>gtk-new</input>.
</item>

     </steps>

    Repeat the above steps for the remaining ToolButtons, with the following properties:

        
Name

        
Is important

        
Action name

        
Label

        
Stock Id

      
open_button

      
Yes

      
app.open

      
Open

      
gtk-open

      
undo_button

      
Yes

      
win.undo

      
Undo

      
gtk-undo

      
fullscreen_button

      
Yes

      
win.fullscreen

      
Fullscreen

      
gtk-fullscreen

      
leave_fullscreen_button

      
Yes

      
win.fullscreen

      
Leave Fullscreen

      
gtk-leave-fullscreen

          <media type="image" src="media/glade_toolbar_editor.png">

          </media>

    </item>

    <item>
Close the <gui>Tool Bar Editor</gui>.

   </item>

   <item>
When our program will first start, we do not want the <gui>Leave Fullscreen</gui> ToolButton to be visible, since the application will not be in fullscreen mode.  You can set this in the <gui>Common</gui> tab, by clicking the <gui>Visible</gui> property to <gui>No</gui>.  The ToolButton will still appear in the interface designer, but will behave correctly when the file is loaded into your program code. Note that the method show_all() would override this setting - so in the code we have to use show() separately on all the elements.

          
<media type="image" src="media/glade_visible_no.png">

                 Setting the visible property to No

          </media>

   </item>

    <item>
Save your work, and close Glade.

   </item>

   <item>
The XML file created by Glade is shown below. This is the description of the toolbar.  At the time of this writing, the option to add the class Gtk.STYLE_CLASS_PRIMARY_TOOLBAR in the Glade Interface did not exist.  We can manually add this to the XML file.  To do this, add the following XML code at line 9 of <file>toolbar_builder.ui</file>:

  <style>

     <class name="primary-toolbar"/>

  </style>

  ]]>

  
If you do not add this, the program will still work fine.  The resulting toolbar will however look slightly different then the screenshot at the top of this page.

   </item>

</steps>

  <?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">app.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">app.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>

    <child>

      <object class="GtkToolButton" id="undo_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.undo</property>

        <property name="label" translatable="yes">Undo</property>

        <property name="use_underline">True</property>

        <property name="stock_id">gtk-undo</property>

      </object>

      <packing>

        <property name="expand">False</property>

        <property name="homogeneous">True</property>

      </packing>

    </child>

    <child>

      <object class="GtkToolButton" id="fullscreen_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.fullscreen</property>

        <property name="label" translatable="yes">Fullscreen</property>

        <property name="use_underline">True</property>

        <property name="stock_id">gtk-fullscreen</property>

      </object>

      <packing>

        <property name="expand">False</property>

        <property name="homogeneous">True</property>

      </packing>

    </child>

    <child>

      <object class="GtkToolButton" id="leave_fullscreen_button">

        <property name="use_action_appearance">False</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.fullscreen</property>

        <property name="label" translatable="yes">Leave Fullscreen</property>

        <property name="use_underline">True</property>

        <property name="stock_id">gtk-leave-fullscreen</property>

      </object>

      <packing>

        <property name="expand">False</property>

        <property name="homogeneous">True</property>

      </packing>

    </child>

  </object>

</interface>

</section>

<section id="code">

<title>Code used to generate this example</title>

  
We now create the code below, which adds the toolbar from the file we just created.

from gi.repository import Gtk

from gi.repository import Gdk

from gi.repository import Gio

import sys

class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):

        Gtk.Window.__init__(self, title="Toolbar Example", application=app)

        self.set_default_size(400, 200)

        # a grid to attach the toolbar (see below)

        grid = Gtk.Grid()

        self.add(grid)

        # we have to show the grid (and therefore the toolbar) with show(),

        # as show_all() would show also the buttons in the toolbar that we want to

        # be hidden (such as the leave_fullscreen button)

        grid.show()

        # a builder to add the UI designed with Glade to the grid:

        builder = Gtk.Builder()

        # get the file (if it is there)

        try:

            builder.add_from_file("toolbar_builder.ui")

        except:

            print("file not found")

            sys.exit()

        # and attach it to the grid

        grid.attach(builder.get_object("toolbar"), 0, 0, 1, 1)

        # two buttons that will be used later in a method

        self.fullscreen_button = builder.get_object("fullscreen_button")

        self.leave_fullscreen_button = builder.get_object(

            "leave_fullscreen_button")

        # create the actions that control the window, connect their signal to a

        # callback method (see below), add the action to the window:

        # undo

        undo_action = Gio.SimpleAction.new("undo", None)

        undo_action.connect("activate", self.undo_callback)

        self.add_action(undo_action)

        # and fullscreen

        fullscreen_action = Gio.SimpleAction.new("fullscreen", None)

        fullscreen_action.connect("activate", self.fullscreen_callback)

        self.add_action(fullscreen_action)

    # callback for undo

    def undo_callback(self, action, parameter):

        print("You clicked \"Undo\".")

    # callback for fullscreen

    def fullscreen_callback(self, action, parameter):

        # check if the state is the same as Gdk.WindowState.FULLSCREEN, which

        # is a bit flag

        is_fullscreen = self.get_window().get_state(

        ) & Gdk.WindowState.FULLSCREEN != 0

        if is_fullscreen:

            self.unfullscreen()

            self.leave_fullscreen_button.hide()

            self.fullscreen_button.show()

        else:

            self.fullscreen()

            self.fullscreen_button.hide()

            self.leave_fullscreen_button.show()

class MyApplication(Gtk.Application):

    def __init__(self):

        Gtk.Application.__init__(self)

    def do_activate(self):

        win = MyWindow(self)

        # show the window - with show() not show_all() because that would show also

        # the leave_fullscreen button

        win.show()

    def do_startup(self):

        Gtk.Application.do_startup(self)

        # actions that control the application: create, connect their signal to a

        # callback method (see below), add the action to the application

        # new

        new_action = Gio.SimpleAction.new("new", None)

        new_action.connect("activate", self.new_callback)

        app.add_action(new_action)

        # open

        open_action = Gio.SimpleAction.new("open", None)

        open_action.connect("activate", self.open_callback)

        app.add_action(open_action)

    # callback for new

    def new_callback(self, action, parameter):

        print("You clicked \"New\".")

    # callback for open

    def open_callback(self, action, parameter):

        print("You clicked \"Open\".")

app = MyApplication()

exit_status = app.run(sys.argv)

sys.exit(exit_status)

</section>

<section id="methods">

<title>Useful methods for Gtk.Builder</title>

For the useful methods for a Toolbar widget, see <link xref="toolbar.py"/>

Gtk.Builder builds an interface from an XML UI definition.

<list>

<item>
add_from_file(filename) loads and parses the given file and merges it with the current contents of the Gtk.Builder.
</item>

<item>
add_from_string(string) parses the given string and merges it with the current contents of the Gtk.Builder.
</item>

<item>
add_objects_from_file(filename, object_ids) is the same as add_from_file(), but it loads only the objects with the ids given in the object_ids list.
</item>

<item>
add_objects_from_string(string, object_ids)  is the same as add_from_string(), but it loads only the objects with the ids given in the object_ids list.
</item>

<item>
get_object(object_id) retrieves the widget with the id object_id from the loaded objects in the builder.
</item>

<item>
get_objects() returns all loaded objects.
</item>

<item>
connect_signals(handler_object) connects the signals to the methods given in the handler_object. This can be any object which contains keys or attributes that are called like the signal handler names given in the interface description, e.g. a class or a dict. In line 39 the signal "activate" from the action undo_action is connected to the callback function undo_callback() using action.connect(signal, callback function). See <link xref="signals-callbacks.py"/> for a more detailed explanation.

</item>

</list>

</section>

<section id="references">

<title>API References</title>

  In this sample we used the following:

<list>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkGrid.html">GtkGrid</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkBuilder.html">GtkBuilder</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkWidget.html">GtkWidget</link>
</item>

  <item>
<link href="http://developer.gnome.org/gdk3/unstable/gdk3-Event-Structures.html#GdkEventWindowState">Event Structures</link>
</item>

</list>

</section>

</page>