GNOME.org
 

[gnome-devel-docs] tutorials <javascript>: Added Gtk.ComboBox code sample and Mallard page

commit ed9e3b4ef9a039edf0be6190fcfb2debf9ca0267
Author: Taryn Fox <jewelfox fursona net>
Date:   Tue Jul 10 07:42:39 2012 -0400

    tutorials <javascript>: Added Gtk.ComboBox code sample and Mallard page

 platform-demos/C/combobox.js.page    |  243 ++++++++++++++++++++++++++++++++++
 platform-demos/C/samples/combobox.js |  134 +++++++++++++++++++
 2 files changed, 377 insertions(+), 0 deletions(-)
---
diff --git a/platform-demos/C/combobox.js.page b/platform-demos/C/combobox.js.page
new file mode 100644
index 0000000..0997c59
--- /dev/null
+++ b/platform-demos/C/combobox.js.page
@@ -0,0 +1,243 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:xi="http://www.w3.org/2001/XInclude";
+      type="guide" style="task"
+      id="combobox.js">
+  <info>
+    <link type="guide" xref="beginner.js#menu-combo-toolbar"/>
+    <link type="seealso" xref="GtkApplicationWindow.js" />
+    <link type="seealso" xref="comboboxtext.js" />
+    <link type="seealso" xref="messagedialog.js" />
+    <link type="seealso" xref="treeview.js" />
+    <revision version="0.1" date="2012-07-09" status="draft"/>
+
+    <credit type="author copyright">
+      <name>Taryn Fox</name>
+      <email>jewelfox fursona net</email>
+      <years>2012</years>
+    </credit>
+
+    <desc>A customizable drop-down menu</desc>
+  </info>
+
+  <title>ComboBox</title>
+  <media type="image" mime="image/png" src="media/combobox_multicolumn.png"/>
+  <p>A ComboBox is an extremely customizable drop-down menu. It holds the equivalent of a <link xref="treeview.js">TreeView</link> widget that appears when you click on it, complete with a ListStore (basically a spreadsheet) that says what's in the rows and columns. In this example, our ListStore has the name of each option in one column, and the name of a stock icon in the other, which the ComboBox then turns into an icon for each option.</p>
+  <p>You select a whole horizontal row at a time, so the icons aren't treated as separate options. They and the text beside them make up each option you can click on.</p>
+  <note><p>Working with a ListStore can be time-consuming. If you just want a simple text-only drop-down menu, take a look at the <link xref="comboboxtext.js">ComboBoxText.</link> It doesn't take as much time to set up, and is easier to work with.</p></note>
+    <links type="section" />
+
+  <section id="imports">
+    <title>Libraries to import</title>
+    <code mime="text/javascript"><![CDATA[
+#!/usr/bin/gjs
+
+const GObject = imports.gi.GObject;
+const Gtk = imports.gi.Gtk;
+const Lang = imports.lang;
+]]></code>
+    <p>These are the libraries we need to import for this application to run. Remember that the line which tells GNOME that we're using Gjs always needs to go at the start.</p>
+  </section>
+
+  <section id="applicationwindow">
+    <title>Creating the application window</title>
+    <code mime="text/javascript"><![CDATA[
+const ComboBoxExample = new Lang.Class ({
+    Name: 'ComboBox Example',
+
+    // Create the application itself
+    _init: function () {
+        this.application = new Gtk.Application ({
+            application_id: 'org.example.jscombobox'});
+
+        // Connect 'activate' and 'startup' signals to the callback functions
+        this.application.connect('activate', Lang.bind(this, this._onActivate));
+        this.application.connect('startup', Lang.bind(this, this._onStartup));
+    },
+
+    // Callback function for 'activate' signal presents windows when active
+    _onActivate: function () {
+        this._window.present ();
+    },
+
+    // Callback function for 'startup' signal builds the UI
+    _onStartup: function () {
+        this._buildUI ();
+    },
+]]></code>
+    <p>All the code for this sample goes in the ComboBoxExample class. The above code creates a <link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html";>Gtk.Application</link> for our widgets and window to go in.</p>
+    <code mime="text/javascript"><![CDATA[
+    // Build the application's UI
+    _buildUI: function () {
+
+        // Create the application window
+        this._window = new Gtk.ApplicationWindow  ({
+            application: this.application,
+            window_position: Gtk.WindowPosition.CENTER,
+            title: "Welcome to GNOME",
+            default_width: 200,
+            border_width: 10 });
+]]></code>
+    <p>The _buildUI function is where we put all the code to create the application's user interface. The first step is creating a new <link xref="GtkApplicationWindow.js">Gtk.ApplicationWindow</link> to put all our widgets into.</p>
+  </section>
+
+  <section id="liststore">
+    <title>Creating the ListStore</title>
+    <code mime="text/javascript"><![CDATA[
+        // Create the liststore to put our options in
+        this._listStore = new Gtk.ListStore();
+        this._listStore.set_column_types ([
+            GObject.TYPE_STRING,
+            GObject.TYPE_STRING,]);
+]]></code>
+    <p>This ListStore works like the one used in the <link xref="treeview.js">TreeView</link> example. We're giving it two columns, both strings, because one of them will contain the names of <link href="http://developer.gnome.org/gtk/2.24/gtk-Stock-Items.html#GTK-STOCK-ABOUT:CAPS";>stock Gtk icons.</link></p>
+    <p>If we'd wanted to use our own icons that weren't already built in to GNOME, we'd have needed to use the <file>gtk.gdk.Pixbuf</file> type instead. Here are a few other types you can use:</p>
+    <list>
+      <item><p><file>GObject.TYPE_BOOLEAN</file> -- True or false</p></item>
+      <item><p><file>GObject.TYPE_FLOAT</file> -- A floating point number (one with a decimal point)</p></item>
+      <item><p><file>GObject.TYPE_STRING</file> -- A string of letters and numbers</p></item>
+    </list>
+    <note><p>You need to put the line <file>const GObject = imports.gi.GObject;</file> at the start of your application's code, like we did in this example, if you want to be able to use GObject types.</p></note>
+
+    <code mime="text/javascript"><![CDATA[
+        // This array holds our list of options and their icons
+        let options = [{ name: "Select", icon: null },
+            { name: "New", icon: Gtk.STOCK_NEW },
+            { name: "Open", icon: Gtk.STOCK_OPEN },
+            { name: "Save", icon: Gtk.STOCK_SAVE }];
+
+        // Put the options in the liststore
+        for (let i = 0; i < options.length; i++ ) {
+            let option = options[i]
+            this._listStore.set (this._listStore.append(), [0, 1],
+                [option.name, option.icon]);
+        }
+]]></code>
+    <p>Here we create an array of the text options and their corresponding icons, then put them into the ListStore the same way we would for a <link xref="treeview.js">TreeView's</link> ListStore. "Select" isn't really an option so much as an invitation to click on our ComboBox, so it doesn't need an icon.</p>
+  </section>
+
+  <section id="combobox">
+    <title>Creating the ComboBox</title>
+    <code mime="text/javascript"><![CDATA[
+        // Create the combobox
+        this._comboBox = new Gtk.ComboBox({
+            model: this._listStore});
+]]></code>
+    <p>Each ComboBox has an underlying "model" it takes all its options from. You can use a TreeStore if you want to have a ComboBox with branching options. In this case, we're just using the ListStore we already created.</p>
+    <code mime="text/javascript"><![CDATA[
+        // Create some cellrenderers for the items in each column
+        let rendererPixbuf = new Gtk.CellRendererPixbuf();
+        let rendererText = new Gtk.CellRendererText();
+
+        // Pack the renderers into the combobox in the order we want to see
+        this._comboBox.pack_start (rendererPixbuf, false);
+        this._comboBox.pack_start (rendererText, false);
+
+        // Set the renderers to use the information from our liststore
+        this._comboBox.add_attribute (rendererText, "text", 0);
+        this._comboBox.add_attribute (rendererPixbuf, "stock_id", 1);
+]]></code>
+    <p>This part, again, works much like creating CellRenderers and packing them into the columns of a <link xref="treeview.js">TreeView.</link> The biggest difference is that we don't need to create the ComboBox's columns as separate objects. We just pack the CellRenderers into it in the order we want them to show up, then tell them to pull information from the ListStore (and what type of information we want them to expect).</p>
+    <p>We use a CellRendererText to show the text, and a CellRendererPixbuf to show the icons. We can store the names of the icons' stock types as strings, but when we display them we need a CellRenderer that's designed for pictures.</p>
+    <note><p>Just like with a TreeView, the "model" (in this case a ListStore) and the "view" (in this case our ComboBox) are separate. Because of that, we can do things like have the columns in one order in the ListStore, and then pack the CellRenderers that correspond to those columns into the ComboBox in a different order. We can even create a TreeView or other widget that shows the information in the ListStore in a different way, without it affecting our ComboBox.</p></note>
+
+    <code mime="text/javascript"><![CDATA[
+        // Set the first row in the combobox to be active on startup
+        this._comboBox.set_active (0);
+
+        // Connect the combobox's 'changed' signal to our callback function
+        this._comboBox.connect ('changed', Lang.bind (this, this._onComboChanged));
+]]></code>
+    <p>We want the "Select" text to be the part people see at first, that gets them to click on the ComboBox. So we set it to be the active entry. We also connect the ComboBox's <file>changed</file> signal to a callback function, so that any time someone clicks on a new option something happens. In this case, we're just going to show a popup with a little haiku.</p>
+
+    <code mime="text/javascript"><![CDATA[
+        // Add the combobox to the window
+        this._window.add (this._comboBox);
+
+        // Show the window and all child widgets
+        this._window.show_all();
+    },
+]]></code>
+    <p>Finally, we add the ComboBox to the window, and tell the window to show itself and everything inside it.</p>
+  </section>
+
+  <section id="function">
+    <title>Function which handles your selection</title>
+    <code mime="text/javascript"><![CDATA[
+    _selected: function () {
+
+        // The silly pseudohaiku that we'll use for our messagedialog
+        let haiku = ["",
+            "You ask for the new\nwith no thought for the aged\nlike fallen leaves trod.",
+            "Like a simple clam\nrevealing a lustrous pearl\nit opens for you.",
+            "A moment in time\na memory on the breeze\nthese things can't be saved."];
+]]></code>
+    <p>We're going to create a pop-up <link xref="messagedialog.js">MessageDialog,</link> which shows you a silly haiku based on which distro you select. First, we create the array of haiku to use. Since the first string in our ComboBox is just the "Select" message, we make the first string in our array blank.</p>
+
+    <code mime="text/javascript"><![CDATA[
+        // Which combobox item is active?
+        let activeItem = this._comboBox.get_active();
+
+        // No messagedialog if you choose "Select"
+        if (activeItem != 0) {
+            this._popUp = new Gtk.MessageDialog ({
+                transient_for: this._window,
+                modal: true,
+                buttons: Gtk.ButtonsType.OK,
+                message_type: Gtk.MessageType.INFO,
+                text: haiku[activeItem]});
+
+            // Connect the OK button to a handler function
+            this._popUp.connect ('response', Lang.bind (this, this._onDialogResponse));
+
+            // Show the messagedialog
+            this._popUp.show();
+        }
+
+    },
+]]></code>
+    <p>Before showing a MessageDialog, we first test to make sure you didn't choose the "Select" message. After that, we set its text to be the haiku in the array that corresponds to the active entry in our ComboBoxText. We do that using the <file>get_active</file> method, which returns the number ID of your selection.</p>
+    <note><p>Other methods you can use include <file>get_active_id,</file> which returns the text ID assigned by <file>append,</file> and <file>get_active_text,</file> which returns the full text of the string you selected.</p></note>
+    <p>After we create the MessageDialog, we connect its response signal to the _onDialogResponse function, then tell it to show itself.</p>
+
+    <code mime="text/javascript"><![CDATA[
+    _onDialogResponse: function () {
+
+        this._popUp.destroy ();
+
+    }
+
+});
+]]></code>
+    <p>Since the only button the MessageDialog has is an OK button, we don't need to test its response_id to see which button was clicked. All we do here is destroy the popup.</p>
+
+    <code mime="text/javascript"><![CDATA[
+// Run the application
+let app = new ComboBoxExample ();
+app.application.run (ARGV);
+]]></code>
+    <p>Finally, we create a new instance of the finished ComboBoxExample class, and set the application running.</p>
+  </section>
+
+  <section id="complete">
+    <title>Complete code sample</title>
+<code mime="text/javascript" style="numbered"><xi:include href="samples/combobox.js" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="in-depth">
+    <title>In-depth documentation</title>
+<p>
+  In this sample we used the following:
+</p>
+<list>
+  <item><p><link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html";>Gtk.Application</link></p></item>
+  <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html";>Gtk.ApplicationWindow</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.CellRendererPixbuf.html";>Gtk.CellRendererPixbuf</link></p></item>
+  <item><p><link href="www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.CellRendererText.html">Gtk.CellRendererText</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.ComboBox.html";>Gtk.ComboBox</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.ListStore.html";>Gtk.ListStore</link></p></item>
+  <item><p><link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.MessageDialog.html";>Gtk.MessageDialog</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.TreeIter.html";>Gtk.TreeIter</link></p></item>
+</list>
+  </section>
+</page>
diff --git a/platform-demos/C/samples/combobox.js b/platform-demos/C/samples/combobox.js
new file mode 100644
index 0000000..98e662b
--- /dev/null
+++ b/platform-demos/C/samples/combobox.js
@@ -0,0 +1,134 @@
+#!/usr/bin/gjs
+
+const GObject = imports.gi.GObject;
+const Gtk = imports.gi.Gtk;
+const Lang = imports.lang;
+
+const ComboBoxExample = new Lang.Class ({
+    Name: 'ComboBox Example',
+
+    // Create the application itself
+    _init: function () {
+        this.application = new Gtk.Application ({
+            application_id: 'org.example.jscombobox'});
+
+        // Connect 'activate' and 'startup' signals to the callback functions
+        this.application.connect('activate', Lang.bind(this, this._onActivate));
+        this.application.connect('startup', Lang.bind(this, this._onStartup));
+    },
+
+    // Callback function for 'activate' signal presents windows when active
+    _onActivate: function () {
+        this._window.present ();
+    },
+
+    // Callback function for 'startup' signal builds the UI
+    _onStartup: function () {
+        this._buildUI ();
+    },
+
+
+
+    // Build the application's UI
+    _buildUI: function () {
+
+        // Create the application window
+        this._window = new Gtk.ApplicationWindow  ({
+            application: this.application,
+            window_position: Gtk.WindowPosition.CENTER,
+            title: "Welcome to GNOME",
+            default_width: 200,
+            border_width: 10 });
+
+        // Create the liststore to put our options in
+        this._listStore = new Gtk.ListStore();
+        this._listStore.set_column_types ([
+            GObject.TYPE_STRING,
+            GObject.TYPE_STRING,]);
+
+        // This array holds our list of options and their icons
+        let options = [{ name: "Select", icon: null },
+            { name: "New", icon: Gtk.STOCK_NEW },
+            { name: "Open", icon: Gtk.STOCK_OPEN },
+            { name: "Save", icon: Gtk.STOCK_SAVE }];
+
+        // Put the options in the liststore
+        for (let i = 0; i < options.length; i++ ) {
+            let option = options[i]
+            this._listStore.set (this._listStore.append(), [0, 1],
+                [option.name, option.icon]);
+        }
+
+        // Create the combobox
+        this._comboBox = new Gtk.ComboBox({
+            model: this._listStore});
+
+        // Create some cellrenderers for the items in each column
+        let rendererPixbuf = new Gtk.CellRendererPixbuf();
+        let rendererText = new Gtk.CellRendererText();
+
+        // Pack the renderers into the combobox in the order we want to see
+        this._comboBox.pack_start (rendererPixbuf, false);
+        this._comboBox.pack_start (rendererText, false);
+
+        // Set the renderers to use the information from our liststore
+        this._comboBox.add_attribute (rendererText, "text", 0);
+        this._comboBox.add_attribute (rendererPixbuf, "stock_id", 1);
+
+        // Set the first row in the combobox to be active on startup
+        this._comboBox.set_active (0);
+
+        // Connect the combobox's 'changed' signal to our callback function
+        this._comboBox.connect ('changed', Lang.bind (this, this._onComboChanged));
+
+        // Add the combobox to the window
+        this._window.add (this._comboBox);
+
+        // Show the window and all child widgets
+        this._window.show_all();
+    },
+
+
+
+    _onComboChanged: function () {
+
+        // The silly pseudohaiku that we'll use for our messagedialog
+        let haiku = ["",
+            "You ask for the new\nwith no thought for the aged\nlike fallen leaves trod.",
+            "Like a simple clam\nrevealing a lustrous pearl\nit opens for you.",
+            "A moment in time\na memory on the breeze\nthese things can't be saved."];
+
+        // Which combobox item is active?
+        let activeItem = this._comboBox.get_active();
+
+        // No messagedialog if you choose "Select"
+        if (activeItem != 0) {
+            this._popUp = new Gtk.MessageDialog ({
+                transient_for: this._window,
+                modal: true,
+                buttons: Gtk.ButtonsType.OK,
+                message_type: Gtk.MessageType.INFO,
+                text: haiku[activeItem]});
+
+            // Connect the OK button to a handler function
+            this._popUp.connect ('response', Lang.bind (this, this._onDialogResponse));
+
+            // Show the messagedialog
+            this._popUp.show();
+        }
+
+    },
+
+
+
+    _onDialogResponse: function () {
+
+        this._popUp.destroy ();
+
+    }
+
+});
+
+// Run the application
+let app = new ComboBoxExample ();
+app.application.run (ARGV);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]