1<?xml version='1.0' encoding='UTF-8'?> 2<page xmlns="http://projectmallard.org/1.0/" 3 xmlns:its="http://www.w3.org/2005/11/its" 4 xmlns:xi="http://www.w3.org/2001/XInclude" 5 type="guide" style="task" 6 id="menubar.vala"> 7 <info> 8 <title type="text">MenuBar (Vala)</title> 9 <link type="guide" xref="beginner.vala#menu-combo-toolbar"/> 10 <link type="seealso" xref="aboutdialog.vala"/> 11 <link type="seealso" xref="gmenu.vala"/> 12 <revision version="0.1" date="2012-05-25" status="draft"/> 13 14 <credit type="author copyright"> 15 <name>Tiffany Antopolski</name> 16 <email its:translate="no">tiffany.antopolski@gmail.com</email> 17 <years>2012</years> 18 </credit> 19 20 <desc>A widget which holds GtkMenuItem widgets</desc> 21 </info> 22 23 <title>MenuBar</title> 24 <media type="image" mime="image/png" src="media/menubar.png"/> 25 <p>A MenuBar created using XML and GtkBuilder.</p> 26 27 <links type="section"/> 28 29 <section id="xml"> <title>Create a MenuBar using XML</title> 30 <p>To create the menubar using XML:</p> 31 <steps> 32 <item><p>Create <file>menubar.ui</file> using your favorite text editor.</p></item> 33 <item><p>Enter the following line at the top of the file:</p> 34 <code mime="application/xml"><![CDATA[ 35<?xml version="1.0"? encoding="UTF-8"?>]]></code> 36 </item> 37 <item><p>We want to create the interface which will contain our menubar and its submenus. Our menubar will contain <gui>File</gui>, <gui>Edit</gui>, <gui>Choices</gui> and <gui>Help</gui> submenus. We add the following XML code to the file:</p> 38 <code mime="application/xml"><xi:include href="samples/menubar_basis.ui" parse="text"><xi:fallback/></xi:include></code> 39 </item> 40 <item><p>Now we will create the .vala file and use GtkBuilder to import the <file>menubar.ui</file> we just created.</p></item> 41 </steps> 42 </section> 43 <section id="basis"> <title>Add the MenuBar to the window using GtkBuilder</title> 44<code mime="text/x-csharp"><xi:include href="samples/menubar_basis.vala" parse="text"><xi:fallback/></xi:include></code> 45<p> 46Now, compile the vala file, and run it. The application should look like the picture at the top of this page.</p> 47</section> 48 49 50 51<section id="xml2"> <title>Add items to the menus</title> 52<p>We start off by adding 2 menuitems to the <gui>File</gui> menu: <gui>New</gui> and <gui>Quit</gui>. We do this by adding a <code>section</code> to the the <code>File</code> submenu with these items. The <file>menubar.ui</file> should look like this (lines 6 to 13 inclusive comprise the newly added section):</p> 53 <code mime="application/xml" style="numbered"><![CDATA[ 54<?xml version="1.0" encoding="UTF-8"?> 55<interface> 56 <menu id="menubar"> 57 <submenu> 58 <attribute name="label">File</attribute> 59 <section> 60 <item> 61 <attribute name="label">New</attribute> 62 </item> 63 <item> 64 <attribute name ="label">Quit</attribute> 65 </item> 66 </section> 67 </submenu> 68 <submenu> 69 <attribute name="label">Edit</attribute> 70 </submenu> 71 <submenu> 72 <attribute name="label">Choices</attribute> 73 </submenu> 74 <submenu> 75 <attribute name="label">Help</attribute> 76 </submenu> 77 </menu> 78</interface>]]></code> 79 80<p>Following this pattern, you can now add a <code>Copy</code> and a <code>Paste</code> item to the <code>Edit</code> submenu, and an <code>About</code> item to the <code>Help</code> submenu. We will hold off on adding items to the <link xref="menubar.vala#choices">Choices submenu</link> until further in the tutorial.</p> 81 82<note style="tip"><p> 83 You do not need to recompile the vala program if you only made changes to the UI file. Just run your previously compiled application, and the UI changes will be reflected. 84</p></note> 85</section> 86 87<section id="actions"><title>Setup actions</title> 88<p>This is a three step process.</p> 89<steps> 90 <item><p>First we create the ActionEntry array in the MyApplication class. 91 An ActionEntry consists of: </p> 92 <list> 93 <item><p>the "action name" (mandatory)</p></item> 94 <item><p>the callback function to connect to the "activate" signal of the action (if applicable)</p></item> 95 <item><p>the type of the parameter that must be passed to the activate function for the action (if applicable)</p></item> 96 <item><p>the initial state for this action (if applicable)</p></item> 97 <item><p>the callback to connect to "change-state" signal (if applicable)</p></item> 98 </list> 99 <code mime="text/x-csharp"> 100const ActionEntry[] actions = { 101 { "new", new_cb }, // {"action name", callback_function} 102 { "quit", quit_cb } 103};</code> 104 105 </item> 106 <item><p>Second, we create the callback functions the actions are connected to.</p> 107 <code mime="text/x-csharp"> 108void new_cb (SimpleAction action, Variant? parameter) { 109 print ("You clicked \"New\"\n"); 110 //new MyWindow (this).show (); 111} 112 113void quit_cb (SimpleAction action, Variant? parameter) { 114 print ("You clicked \"Quit\"\n"); 115 this.quit (); 116}</code> 117 </item> 118 <item><p>And lastly, we connect the menu items to the actions in the XML file by adding the "action" attribute:</p> 119 <code mime="application/xml"><![CDATA[ 120<item> 121 <attribute name="label">New</attribute> 122 <attribute name="action">app.new</attribute> 123</item> 124<item> 125 <attribute name="label">Quit</attribute> 126 <attribute name="action">app.quit</attribute> 127</item>]]></code> 128 </item> 129</steps> 130</section> 131 132 133<section id="choices"><title>Choices submenu and items with state</title> 134 <media type="image" mime="image/png" src="media/menubar_choices.png"/> 135 <p>Lines 30 to 80 inclusive of the <link xref="menubar.vala#xml-code" /> demonstrate 136 the XML code used to create the UI for <gui>Choices</gui> menu.</p> 137</section> 138 139<section id="win-app"><title>Actions: Application or Window?</title> 140 <p>Above, we created the "new" and "open" actions as part of the MyApplication class. 141 Actions which control the application itself, such as "quit" should be created similarly.</p> 142 143 <p>Some actions, such as "copy" and "paste" deal with the window, not the application. 144 Window actions should be created as part of the window class.</p> 145 146 <p> 147 The complete example files contain both application actions and 148 window applications. The window actions are the ones usually included in the <link xref="gmenu.vala">application menu</link> also. It is not good practice to include window actions in the application menu. For demonstration purposes, the complete example files which follow include XML in the UI file which creates the application menu which includes a "New" and "Open" item, and these are hooked up to the same actions as the menubar items of the same name. 149 </p> 150 151 152</section> 153 154 <section id="xml-code"><title>Complete XML UI file for this example</title> 155<code mime="application/xml" style="numbered"><xi:include href="samples/menubar.ui" parse="text"><xi:fallback/></xi:include></code> 156 </section> 157 <section id="vala-code"><title>Complete Vala file for this example</title> 158<code mime="text/x-csharp" style="numbered"><xi:include href="samples/menubar.vala" parse="text"><xi:fallback/></xi:include></code> 159 </section> 160 161 <section id="mnemonics"><title>Mnemonics</title> 162 <p>Labels may contain mnemonics. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by placing an underscore before the mnemonic character. For example "_File" instead of just "File" in the menubar.ui label attribute.</p> 163 <p>The mnemonics are visible when you press the <key>Alt</key> key. Pressing <keyseq><key>Alt</key><key>F</key></keyseq> will open the <gui>File</gui> menu. 164 </p> 165 </section> 166 167 <section id="accelerators"><title>Accelerators</title> 168 <p>Accelerators can be explicitly added in the UI definitions. For example, it is common to be able to quit an application by pressing <keyseq><key>Ctrl</key><key>Q</key></keyseq> or to save a file by pressing <keyseq><key>Ctrl</key><key>S</key></keyseq>. To add an accelerator to the UI definition, you simply need add an "accel" attribute to the item.</p> 169<p><code mime="application/xml"><![CDATA[<attribute name="accel"><Primary>q</attribute>]]></code> will create the <keyseq><key>Ctrl</key><key>Q</key></keyseq> sequence when added to the <code>Quit</code> label item. Here, "Primary" refers to the <key>Ctrl</key> key on a PC or the <key>⌘</key> key on a Mac.</p> 170 171 <code mime="application/xml"><![CDATA[ 172<item> 173 <attribute name="label">_Quit</attribute> 174 <attribute name="action">app.quit</attribute> 175 <attribute name="accel"><Primary>q</attribute> 176</item>]]></code> 177 </section> 178 179 <section id="translatable"><title>Translatable strings</title> 180 <p> 181 Since GNOME applications are being translated into <link href="http://l10n.gnome.org/languages/">many languages</link>, it is important that the strings in your application are translatable. To make a label translatable, simple set <code>translatable="yes"</code>: 182 </p> 183 <p> 184 <code mime="application/xml"><![CDATA[<attribute name="label" translatable="yes">Quit</attribute>]]></code> 185 </p> 186 </section> 187 <section id="documentation"><title>Relevant API documentation</title> 188<p> 189 In this sample we used the following: 190</p> 191<list> 192 <item><p><link href="http://valadoc.org/gio-2.0/GLib.ActionEntry.html">Glib.ActionEntry</link></p></item> 193 <item><p><link href="http://valadoc.org/gio-2.0/Gtk.Builder.html">Gtk.Builder</link></p></item> 194</list> 195</section> 196 197 198<section id="exercises"><title>Exercises</title> 199 <xi:include href="exercises/menubar.vala.exercises"><xi:fallback/></xi:include> 200</section> 201</page> 202
