GNOME.org
 

[gnome-devel-docs] tutorials <javascript>: Added Gtk.Switch example, screenshot, and Mallard page

commit b2b7b346b8e2550c46f1074c234738fae96c17dd
Author: Taryn Fox <jewelfox fursona net>
Date:   Mon Jun 18 02:43:38 2012 -0400

    tutorials <javascript>: Added Gtk.Switch example, screenshot, and Mallard page

 platform-demos/C/media/switchanimals.png |  Bin 0 -> 400231 bytes
 platform-demos/C/samples/switch.js       |  180 ++++++++++++++++++++
 platform-demos/C/switch.js.page          |  274 ++++++++++++++++++++++++++++++
 3 files changed, 454 insertions(+), 0 deletions(-)
---
diff --git a/platform-demos/C/media/switchanimals.png b/platform-demos/C/media/switchanimals.png
new file mode 100644
index 0000000..486a278
Binary files /dev/null and b/platform-demos/C/media/switchanimals.png differ
diff --git a/platform-demos/C/samples/switch.js b/platform-demos/C/samples/switch.js
new file mode 100644
index 0000000..c54f806
--- /dev/null
+++ b/platform-demos/C/samples/switch.js
@@ -0,0 +1,180 @@
+#!/usr/bin/gjs
+
+const Gio = imports.gi.Gio;
+const Gtk = imports.gi.Gtk;
+const Lang = imports.lang;
+
+const SwitchExample = new Lang.Class({
+    Name: 'Switch Example',
+
+    // Create the application itself
+    _init: function() {
+        this.application = new Gtk.Application({
+            application_id: 'org.example.jsswitch',
+            flags: Gio.ApplicationFlags.FLAGS_NONE
+        });
+
+    // 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 window when active
+    _onActivate: function() {
+        this._window.present();
+    },
+
+    // Callback function for 'startup' signal creates the menu and builds the UI
+    _onStartup: function() {
+        this._initMenus();
+        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,
+            border_width: 20,
+            title: "Animal Creator"});
+
+        // Create the image widget and set its default picture
+        this._image = new Gtk.Image ({file: "redfox.png"});
+
+        // Create a label for the first switch
+        this._flyLabel = new Gtk.Label ({
+            label: "Make it fly",
+            margin_right: 30});
+
+        // Create the first switch and set its default position
+        this._flySwitch = new Gtk.Switch ({active: false});
+        this._flySwitch.connect ('notify::active', Lang.bind (this, this._switchFlip));
+
+        // Create a label for the second switch
+        this._birdLabel = new Gtk.Label ({
+            label: "Make it a bird",
+            margin_right: 30});
+
+        // Create the second switch
+        this._birdSwitch = new Gtk.Switch ({active: false});
+        this._birdSwitch.connect ('notify::active', Lang.bind (this, this._switchFlip));
+
+        // Create a grid for the labels and switches beneath the picture
+        this._UIGrid = new Gtk.Grid ({
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+            margin_top: 20});
+
+        // Attach the labels and switches to that grid
+        this._UIGrid.attach (this._flyLabel, 0, 0, 1, 1);
+        this._UIGrid.attach (this._flySwitch, 1, 0, 1, 1);
+        this._UIGrid.attach (this._birdLabel, 0, 1, 1, 1);
+        this._UIGrid.attach (this._birdSwitch, 1, 1, 1, 1);
+
+        // Create a master grid to put both the UI and the picture into
+        this._mainGrid = new Gtk.Grid ({
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER });
+
+        // Attach the picture and the UI grid to the master grid
+        this._mainGrid.attach (this._image, 0, 0, 1, 1);
+        this._mainGrid.attach (this._UIGrid, 0, 1, 1, 1);
+
+        // Add the master grid to the window
+        this._window.add (this._mainGrid);
+
+        // Show the window and all child widgets
+        this._window.show_all();
+    },
+
+
+
+    _switchFlip: function() {
+
+        // Change the picture depending on which switches are flipped
+        if (this._flySwitch.get_active()) {
+
+            if (this._birdSwitch.get_active()) this._image.set_from_file ("muteswan.png");
+
+            else this._image.set_from_file ("fruitbat.png");
+        }
+
+        else {
+
+            if (this._birdSwitch.get_active()) this._image.set_from_file ("gentoopenguin.png");
+
+            else this._image.set_from_file ("redfox.png");
+
+        }
+
+    },
+
+
+
+    _initMenus: function() {
+
+        // Build the application's menu so we can have an "About" button
+        let menu = new Gio.Menu();
+        menu.append("About", 'app.about');
+        menu.append("Quit",'app.quit');
+        this.application.set_app_menu(menu);
+
+        // Bind the "About" button to the _showAbout() function
+        let aboutAction = new Gio.SimpleAction ({ name: 'about' });
+        aboutAction.connect('activate', Lang.bind(this,
+            function() {
+                this._showAbout();
+            }));
+        this.application.add_action(aboutAction);
+
+        // Bind the "Quit" button to the function that closes the window
+        let quitAction = new Gio.SimpleAction ({ name: 'quit' });
+        quitAction.connect('activate', Lang.bind(this,
+            function() {
+                this._window.destroy();
+            }));
+        this.application.add_action(quitAction);
+    },
+
+
+
+    _showAbout: function () {
+
+        // String arrays of the names of the people involved in the project
+        var artists = ['Rob Lee http://en.wikipedia.org/wiki/File:Fuzzy_Freddy.jpg', 'Ken Funakoshi http://en.wikipedia.org/wiki/File:Pygoscelis_papua_-Nagasaki_Penguin_Aquarium_-swimming_underwater-8a.jpg', 'Shek Graham http://www.flickr.com/photos/shekgraham/127431519/in/photostream/', 'Mindaugas Urbonas http://commons.wikimedia.org/wiki/File:Mute_Swan-Mindaugas_Urbonas.jpg'];
+        var authors = ["GNOME Documentation Team"];
+        var documenters = ["GNOME Documentation Team"];
+
+        // Create the About dialog
+        let aboutDialog = new Gtk.AboutDialog({
+            title: "AboutDialog Example",
+            program_name: "Animal Creator",
+            copyright: "Copyright \xa9 2012 GNOME Documentation Team\n\nRed fox photo licensed CC-By by Rob Lee\nGentoo penguin photo licensed CC-By-SA by Ken Funakoshi\nFruit bat photo licensed CC-By by Shek Graham\nMute swan photo licensed CC-By-SA by Mindaugas Urbonas\nLinks to the originals are available under Credits.\n\nHave you hugged a penguin today?",
+            artists: artists,
+            authors: authors,
+            documenters: documenters,
+            website: "http://developer.gnome.org";,
+            website_label: "GNOME Developer Website" });
+
+        // Attach the About dialog to the window
+        aboutDialog.modal = true;
+        aboutDialog.transient_for = this._window;
+
+        // Show the About dialog
+        aboutDialog.show();
+
+        // Connect the Close button to the destroy signal for the dialog
+        aboutDialog.connect('response', function() {
+            aboutDialog.destroy();
+        });
+    }
+
+});
+
+// Run the application
+let app = new SwitchExample ();
+app.application.run (ARGV);
diff --git a/platform-demos/C/switch.js.page b/platform-demos/C/switch.js.page
new file mode 100644
index 0000000..884c1fb
--- /dev/null
+++ b/platform-demos/C/switch.js.page
@@ -0,0 +1,274 @@
+<?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="switch.js">
+  <info>
+    <link type="guide" xref="beginner.js#buttons"/>
+    <revision version="0.1" date="2012-06-18" status="draft"/>
+
+    <credit type="author copyright">
+      <name>Taryn Fox</name>
+      <email>jewelfox fursona net</email>
+      <years>2012</years>
+    </credit>
+
+    <desc>A sliding switch that can be flipped on and off</desc>
+  </info>
+
+  <title>Switch</title>
+  <media type="image" mime="image/png" src="media/switchanimals.png"/>
+  <p>A Switch has two positions, on and off. This example shows how you can use multiple switches together to control which <link xref="image.js">Image</link> is shown in the window.</p>
+  <note><p>The window will contain a "broken image" icon instead of a picture if picture files named <file>redfox.png</file>, <file>muteswan.png</file>, <file>fruitbat.png</file>, and <file>gentoopenguin.png</file> aren't in the same directory. You can change the code and the pictures around as you like, but the Creative Commons-licensed photos used in this example were taken from the following sources and cropped to 640x425:</p>
+    <list>
+        <item><p><link href="http://en.wikipedia.org/wiki/File:Fuzzy_Freddy.jpg";>Red fox photo</link> by Rob Lee, licensed <link href="http://creativecommons.org/licenses/by/2.0/deed.en";>CC-By</link></p></item>
+        <item><p><link href="http://en.wikipedia.org/wiki/File:Pygoscelis_papua_-Nagasaki_Penguin_Aquarium_-swimming_underwater-8a.jpg";>Gentoo penguin photo</link> by Ken Funakoshi, licensed <link href="http://creativecommons.org/licenses/by-sa/2.0/deed.en";>CC-By-SA</link></p></item>
+        <item><p><link href="http://www.flickr.com/photos/shekgraham/127431519/in/photostream/";>Fruit bat photo</link> by Shek Graham, licensed <link href="http://creativecommons.org/licenses/by/2.0/deed.en";>CC-By</link></p></item>
+        <item><p><link href="http://commons.wikimedia.org/wiki/File:Mute_Swan-Mindaugas_Urbonas.jpg";>Mute swan photo</link> by Mindaugas Urbonas, licensed <link href="http://creativecommons.org/licenses/by-sa/2.5/deed.en";>CC-By-SA</link></p></item>
+    </list>
+    <p>Photo credits and licensing information are shown in the application's <link xref="aboutdialog.js">AboutDialog.</link> Always remember to credit the original artist when using <link href="http://creativecommons.org";>Creative Commons-licensed works!</link></p></note>
+    <links type="section" />
+
+  <section id="imports">
+    <title>Libraries to import</title>
+    <code mime="text/javascript"><![CDATA[
+#!/usr/bin/gjs
+
+const Gio = imports.gi.Gio;
+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 SwitchExample = new Lang.Class({
+    Name: 'Switch Example',
+
+    // Create the application itself
+    _init: function() {
+        this.application = new Gtk.Application({
+            application_id: 'org.example.jsswitch',
+            flags: Gio.ApplicationFlags.FLAGS_NONE
+        });
+
+    // 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 window when active
+    _onActivate: function() {
+        this._window.present();
+    },
+
+    // Callback function for 'startup' signal creates the menu and builds the UI
+    _onStartup: function() {
+        this._initMenus();
+        this._buildUI ();
+    },
+]]></code>
+    <p>All the code for this sample goes in the SwitchExample 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>
+    <note><p>Before we call _buildUI to create the window and the widgets inside it, we need to call _initMenus, which tells GNOME to create the menu. We can put the actual code for _initMenus after the code for _buildUI, since it doesn't matter what order we put them in so long as _initMenus is called first in _onStartup.</p></note>
+    <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,
+            border_width: 20,
+            title: "Animal Creator"});
+]]></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="button">
+    <title>Creating the switches</title>
+    <code mime="text/javascript"><![CDATA[
+        // Create the image widget and set its default picture
+        this._image = new Gtk.Image ({file: "redfox.png"});
+]]></code>
+
+    <p>We first create the <link xref="image.js">Image</link> that the switches will control. Remember that a file named <file>redfox.png</file> needs to be in the same directory as this application.</p>
+
+    <code mime="text/javascript"><![CDATA[
+        // Create a label for the first switch
+        this._flyLabel = new Gtk.Label ({
+            label: "Make it fly",
+            margin_right: 30});
+
+        // Create the first switch and set its default position
+        this._flySwitch = new Gtk.Switch ({active: false});
+        this._flySwitch.connect ('notify::active', Lang.bind (this, this._switchFlip));
+
+        // Create a label for the second switch
+        this._birdLabel = new Gtk.Label ({
+            label: "Make it a bird",
+            margin_right: 30});
+
+        // Create the second switch
+        this._birdSwitch = new Gtk.Switch ({active: false});
+        this._birdSwitch.connect ('notify::active', Lang.bind (this, this._switchFlip));
+]]></code>
+
+    <p>We use a <link xref="label.js">Label</link> to mark each Switch, and give them a bit of a margin on the right so that they aren't crammed right next to the Switches. After that we create the Switches, and set them to be switched off by default.</p>
+    <p>The signal a switch sends out when it's flipped on or off is called notify::active. After we create each switch, we connect its notify::active signal to a function called _switchFlip. If you have multiple switches that each do something different, you might want to connect them to different functions, but here they're both used for the same thing: To control what picture's displayed by _image.</p>
+
+    <code mime="text/javascript"><![CDATA[
+        // Create a grid for the labels and switches beneath the picture
+        this._UIGrid = new Gtk.Grid ({
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+            margin_top: 20});
+
+        // Attach the labels and switches to that grid
+        this._UIGrid.attach (this._flyLabel, 0, 0, 1, 1);
+        this._UIGrid.attach (this._flySwitch, 1, 0, 1, 1);
+        this._UIGrid.attach (this._birdLabel, 0, 1, 1, 1);
+        this._UIGrid.attach (this._birdSwitch, 1, 1, 1, 1);
+
+        // Create a master grid to put both the UI and the picture into
+        this._mainGrid = new Gtk.Grid ({
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER });
+
+        // Attach the picture and the UI grid to the master grid
+        this._mainGrid.attach (this._image, 0, 0, 1, 1);
+        this._mainGrid.attach (this._UIGrid, 0, 1, 1, 1);
+]]></code>
+    <p>We create a <link xref="grid.js">Grid</link> for the Labels and Switches first, so that we can organize them in a 2x2 layout with a margin between it and the Image. Then we put that Grid into a larger 2x1 Grid that has the Image on top, and the Grid with the Labels and Switches on the bottom.</p>
+    <code mime="text/javascript"><![CDATA[
+        // Add the master grid to the window
+        this._window.add (this._mainGrid);
+
+        // Show the window and all child widgets
+        this._window.show_all();
+    },
+]]></code>
+    <p>Finally, we add the larger Grid to the window, then tell the window to show itself and all the widgets inside of it.</p>
+    </section>
+
+    <section id="switch-handler">
+    <title>Function which handles the switches being flipped</title>
+
+    <code mime="text/javascript"><![CDATA[
+    _switchFlip: function() {
+
+        // Change the picture depending on which switches are flipped
+        if (this._flySwitch.get_active()) {
+
+            if (this._birdSwitch.get_active()) this._image.set_from_file ("muteswan.png");
+
+            else this._image.set_from_file ("fruitbat.png");
+        }
+
+        else {
+
+            if (this._birdSwitch.get_active()) this._image.set_from_file ("gentoopenguin.png");
+
+            else this._image.set_from_file ("redfox.png");
+
+        }
+
+    },
+]]></code>
+    <p>Each time a Switch is flipped, this function checks to see which of the two Switches are active afterwards, using the Switches' built-in get_active() function. It then changes the Image accordingly. You can change the filenames around as you like, so long as you have pictures to go with them.</p>
+</section>
+
+<section id="about">
+    <title>Creating the AboutDialog</title>
+    <code mime="text/javascript"><![CDATA[
+    _initMenus: function() {
+
+        // Build the application's menu so we can have an "About" button
+        let menu = new Gio.Menu();
+        menu.append("About", 'app.about');
+        menu.append("Quit",'app.quit');
+        this.application.set_app_menu(menu);
+
+        // Bind the "About" button to the _showAbout() function
+        let aboutAction = new Gio.SimpleAction ({ name: 'about' });
+        aboutAction.connect('activate', Lang.bind(this,
+            function() {
+                this._showAbout();
+            }));
+        this.application.add_action(aboutAction);
+
+        // Bind the "Quit" button to the function that closes the window
+        let quitAction = new Gio.SimpleAction ({ name: 'quit' });
+        quitAction.connect('activate', Lang.bind(this,
+            function() {
+                this._window.destroy();
+            }));
+        this.application.add_action(quitAction);
+    },
+]]></code>
+    <p>The first step is building the <link xref="gmenu.js">GMenu</link> that the "About" button goes into. This is the menu that appears when you click the application's name in the upper-left corner of the screen, next to the Activities menu. Our menu only has two options in it: About, and Quit.</p>
+
+    <code mime="text/javascript"><![CDATA[
+    _showAbout: function () {
+
+        // String arrays of the names of the people involved in the project
+        var artists = ['Rob Lee http://en.wikipedia.org/wiki/File:Fuzzy_Freddy.jpg', 'Ken Funakoshi http://en.wikipedia.org/wiki/File:Pygoscelis_papua_-Nagasaki_Penguin_Aquarium_-swimming_underwater-8a.jpg', 'Shek Graham http://www.flickr.com/photos/shekgraham/127431519/in/photostream/', 'Mindaugas Urbonas http://commons.wikimedia.org/wiki/File:Mute_Swan-Mindaugas_Urbonas.jpg'];
+        var authors = ["GNOME Documentation Team"];
+        var documenters = ["GNOME Documentation Team"];
+
+        // Create the About dialog
+        let aboutDialog = new Gtk.AboutDialog({
+            title: "AboutDialog Example",
+            program_name: "Animal Creator",
+            copyright: "Copyright \xa9 2012 GNOME Documentation Team\n\nRed fox photo licensed CC-By by Rob Lee\nGentoo penguin photo licensed CC-By-SA by Ken Funakoshi\nFruit bat photo licensed CC-By by Shek Graham\nMute swan photo licensed CC-By-SA by Mindaugas Urbonas\nLinks to the originals are available under Credits.\n\nHave you hugged a penguin today?",
+            artists: artists,
+            authors: authors,
+            documenters: documenters,
+            website: "http://developer.gnome.org";,
+            website_label: "GNOME Developer Website" });
+
+        // Attach the About dialog to the window
+        aboutDialog.modal = true;
+        aboutDialog.transient_for = this._window;
+
+        // Show the About dialog
+        aboutDialog.show();
+
+        // Connect the Close button to the destroy signal for the dialog
+        aboutDialog.connect('response', function() {
+            aboutDialog.destroy();
+        });
+    }
+
+});
+]]></code>
+    <p>An <link xref="aboutdialog.js">AboutDialog</link> has a lot of different things you can set, to credit everyone who worked on the application and leave a note to whomever reads it. In this case, the copyright section contains our note and credits the original photographers, while the artists section shows you a list of the photographers with links to the original photos when you click the Credits button. The web URLs put after their names in the array turn their names into clickable links in the Credits section.</p>
+
+    <code mime="text/javascript"><![CDATA[
+// Run the application
+let app = new SwitchExample ();
+app.application.run (ARGV);
+]]></code>
+    <p>Finally, we create a new instance of the finished SwitchExample 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/switch.js" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="in-depth">
+    <title>In-depth documentation</title>
+<list>
+  <item><p><link href="http://developer.gnome.org/gio/unstable/GMenu.html";>GMenu</link></p></item>
+  <item><p><link href="http://developer.gnome.org/gio/stable/GSimpleAction.html";>GSimpleAction</link></p></item>
+  <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.Grid.html";>Gtk.Grid</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Image.html";>Gtk.Image</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Label.html";>Gtk.Label</link></p></item>
+  <item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Switch.html";>Gtk.Switch</link></p></item>
+</list>
+  </section>
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]