GNOME.org
 

[gnome-devel-docs] tutorials <javascript>: Wrote detailed MessageDialog tutorial and fixed code indents

commit ebd26188b2c19aa29280cadc013ed7abc067a0ca
Author: Taryn Fox <jewelfox fursona net>
Date:   Mon Jun 25 02:48:08 2012 -0400

    tutorials <javascript>: Wrote detailed MessageDialog tutorial and fixed code indents

 platform-demos/C/messagedialog.js.page    |  171 ++++++++++++++++++++++++++++-
 platform-demos/C/samples/messagedialog.js |   93 +++++++++-------
 2 files changed, 221 insertions(+), 43 deletions(-)
---
diff --git a/platform-demos/C/messagedialog.js.page b/platform-demos/C/messagedialog.js.page
index 497ee22..2bb1281 100644
--- a/platform-demos/C/messagedialog.js.page
+++ b/platform-demos/C/messagedialog.js.page
@@ -5,7 +5,10 @@
       id="messagedialog.js">
   <info>
     <link type="guide" xref="beginner.js#windows"/>
-    <revision version="0.1" date="2012-05-28" status="draft"/>
+    <link type="seealso" xref="GtkApplicationWindow.js" />
+    <link type="seealso" xref="gmenu.js" />
+    <link type="seealso" xref="label.js" />
+    <revision version="0.2" date="2012-06-25" status="draft"/>
 
     <credit type="author copyright">
       <name>Taryn Fox</name>
@@ -13,14 +16,175 @@
       <years>2012</years>
     </credit>
 
-    <desc>A modal message window</desc>
+    <desc>A popup message attached to a window</desc>
   </info>
 
   <title>MessageDialog</title>
   <media type="image" mime="image/png" src="media/messagedialog.png"/>
-  <p>A modal message dialog. This one can cause the world to explode.</p>
+  <p>A MessageDialog is a modal message dialog, which means a popup that you have to respond to before you get back to what you were doing in the window that it's attached to. This one can cause the world to explode (or at least it says that it can). To make the popup appear when you run this sample, click on "Message" inside of its application menu -- that's the menu that appears when you click on an application's name in the upper-left screen corner, next to Activities.</p>
+  <note><p>The difference between a MessageDialog and a <link xref="dialog.js">Dialog</link> is that a Dialog can contain whatever widgets and content you want to put in it, whereas a MessageDialog is just a convenient way to make popups appear with a basic message and buttons.</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 MessageDialogExample = new Lang.Class ({
+    Name: 'MessageDialog Example',
+
+    // Create the application itself
+    _init: function () {
+        this.application = new Gtk.Application ({
+            application_id: 'org.example.jsmessagedialog',
+            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 windows when active
+    _onActivate: function () {
+        this._window.present ();
+    },
+
+    // Callback function for 'startup' signal initializes menus and builds the UI
+    _onStartup: function () {
+        this._initMenus();
+        this._buildUI ();
+    },
+]]></code>
+    <p>All the code for this sample goes in the MessageDialogExample 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,
+            title: "Gtk.MessageDialog Example",
+            default_height: 200,
+            default_width: 400 });
+]]></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>
+
+    <code mime="text/javascript"><![CDATA[
+        // Create a silly warning message and add it to the window
+        this.warningLabel = new Gtk.Label ({
+            label: "This application goes boom! (Not really.)"});
+        this._window.add (this.warningLabel);
+]]></code>
+    <p>For this example, all that we have in the window the popup comes out of is a silly warning <link xref="label.js">Label.</link></p>
+  </section>
+
+  <section id="menu">
+    <title>Creating the application's menu</title>
+    <code mime="text/javascript"><![CDATA[
+    // Build the application menu, including the button that calls the dialog
+    _initMenus: function() {
+        let menu = new Gio.Menu();
+        menu.append("Message",'app.message');
+        menu.append("Quit",'app.quit');
+        this.application.set_app_menu(menu);
+
+        // This pops up a MessageDialog when "Message" is clicked in the menu
+        let messageAction = new Gio.SimpleAction ({ name: 'message' });
+        messageAction.connect('activate', Lang.bind(this,
+            function() {
+                this._showMessageDialog();
+            }));
+        this.application.add_action(messageAction);
+
+        // This closes the window when "Quit" is clicked in the menu
+        let quitAction = new Gio.SimpleAction ({ name: 'quit' });
+        quitAction.connect('activate', Lang.bind(this,
+            function() {
+                this._window.destroy();
+            }));
+        this.application.add_action(quitAction);
+    },
+]]></code>
+    <p>Here, we build the <link xref="gmenu.js">GMenu</link> where we'll be putting the "Message" button which triggers the popup MessageDialog. The GMenu 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: Message, and Quit.</p>
+  </section>
+
+  <section id="messagedialog">
+    <title>Creating the MessageDialog</title>
+    <code mime="text/javascript"><![CDATA[
+    _showMessageDialog: function () {
+
+        // Create a modal MessageDialog whose parent is the window
+        this._messageDialog = new Gtk.MessageDialog ({
+            transient_for: this._window,
+            modal: true,
+            buttons: Gtk.ButtonsType.OK_CANCEL,
+            message_type: Gtk.MessageType.WARNING,
+            text: "This action will cause the universe to stop existing." });
+
+        this._messageDialog.connect ('response', Lang.bind(this, this._response_cb));
+        this._messageDialog.show();
+    },
+]]></code>
+    <p>To make our MessageDialog a popup attached to the main window, we set its modal property to true and set it to be "transient_for" _window. After that, we can set what kind of buttons it has and what kind of message it is (which determines what icon appears next to the message), and write out the text inside it, before connecting its "response" signal to the callback function which handles it.</p>
+    <note><p>Here are some resources for making your own MessageDialogs:</p>
+      <list>
+        <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkMessageDialog.html#GtkButtonsType";>List of button types</link></p></item>
+        <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkMessageDialog.html#GtkMessageType";>List of message types</link></p></item>
+      </list>
+    </note>
+
+    <code mime="text/javascript"><![CDATA[
+    // Callback function (aka signal handler) for the response signal
+    _response_cb: function (messagedialog, response_id) {
+
+        // A simple switch that changes the main window's label
+        switch (response_id) {
+            case Gtk.ResponseType.OK:
+                this.warningLabel.set_label ("*BOOM*\n");
+                break;
+            case Gtk.ResponseType.CANCEL:
+                this.warningLabel.set_label ("Good choice!\n");
+                break;
+            case Gtk.ResponseType.DELETE_EVENT:
+                this.warningLabel.set_label ("Dialog closed or cancelled.\n");
+                break;
+        }
+
+        this._messageDialog.destroy();
+
+    }
+
+});
+]]></code>
+    <p>This function takes two parameters, the MessageDialog and its response_id, both of which are automatically supplied (you don't have to manually pass them to it for it to work). Here we use a simple switch to change the "warning label"'s text, depending on which option you select. The DELETE_EVENT occurs if you press Escape to cancel the MessageDialog, instead of clicking OK or Cancel. Whatever you select, the popup is destroyed afterwards.</p>
+
+    <code mime="text/javascript"><![CDATA[
+// Run the application
+let app = new MessageDialogExample ();
+app.application.run (ARGV);
+]]></code>
+    <p>Finally, we create a new instance of the finished MessageDialogExample 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/messagedialog.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>
@@ -31,4 +195,5 @@
   <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html";>Gtk.ApplicationWindow</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>
 </list>
+  </section>
 </page>
diff --git a/platform-demos/C/samples/messagedialog.js b/platform-demos/C/samples/messagedialog.js
index a7ad7de..8dc202c 100644
--- a/platform-demos/C/samples/messagedialog.js
+++ b/platform-demos/C/samples/messagedialog.js
@@ -1,23 +1,21 @@
 #!/usr/bin/gjs
 
 const Gio = imports.gi.Gio;
-const GLib = imports.gi.GLib;
 const Gtk = imports.gi.Gtk;
 const Lang = imports.lang;
 
-const MessageExample = new Lang.Class ({
-    Name: 'Message Example',
+const MessageDialogExample = new Lang.Class ({
+    Name: 'MessageDialog Example',
 
     // Create the application itself
-        _init: function () {
-            this.application = new Gtk.Application ({
-                application_id: 'org.example.jsmessagedialog',
-                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));
+    _init: function () {
+        this.application = new Gtk.Application ({
+            application_id: 'org.example.jsmessagedialog',
+            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 windows when active
@@ -31,6 +29,30 @@ const MessageExample = new Lang.Class ({
         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: "Gtk.MessageDialog Example",
+            default_height: 200,
+            default_width: 400 });
+
+        // Create a silly warning message and add it to the window
+        this.warningLabel = new Gtk.Label ({
+            label: "This application goes boom! (Not really.)"});
+        this._window.add (this.warningLabel);
+
+        // Show the window and all child widgets
+        this._window.show_all();
+    },
+
+
+
     // Build the application menu, including the button that calls the dialog
     _initMenus: function() {
         let menu = new Gio.Menu();
@@ -38,7 +60,7 @@ const MessageExample = new Lang.Class ({
         menu.append("Quit",'app.quit');
         this.application.set_app_menu(menu);
 
-        // This pops up a MessageDialog when the menu item is clicked
+        // This pops up a MessageDialog when "Message" is clicked in the menu
         let messageAction = new Gio.SimpleAction ({ name: 'message' });
         messageAction.connect('activate', Lang.bind(this,
             function() {
@@ -46,44 +68,33 @@ const MessageExample = new Lang.Class ({
             }));
         this.application.add_action(messageAction);
 
+        // This closes the window when "Quit" is clicked in the menu
         let quitAction = new Gio.SimpleAction ({ name: 'quit' });
         quitAction.connect('activate', Lang.bind(this,
-        function() {
-            this._window.destroy();
-        }));
+            function() {
+                this._window.destroy();
+            }));
         this.application.add_action(quitAction);
     },
 
-    // Build the application's UI, including the MessageDialog
-    _buildUI: function () {
-
-        // Create the application window and a "warning message"
-            this._window = new Gtk.ApplicationWindow  ({ application: this.application,
-                                                              window_position: Gtk.WindowPosition.CENTER,
-                                                              title: "Gtk.MessageDialog Example",
-                                                              default_height: 200,
-                                                              default_width: 400 });
 
-        this.warningLabel = new Gtk.Label ({label: "This application goes boom! (Not really.)"});
-        this._window.add (this.warningLabel);
-
-                // Show the window and all child widgets
-                this._window.show_all();
-    },
 
     _showMessageDialog: function () {
 
         // Create a modal MessageDialog whose parent is the window
-        this._messageDialog = new Gtk.MessageDialog ({ transient_for: this._window,
-                                   modal: true,
-                                          buttons: Gtk.ButtonsType.OK_CANCEL,
-                                          message_type: Gtk.MessageType.WARNING,
-                                          text: "This action will cause the universe to stop existing." });
-
-        this._messageDialog.connect ("response", Lang.bind(this, this._response_cb));
+        this._messageDialog = new Gtk.MessageDialog ({
+            transient_for: this._window,
+            modal: true,
+            buttons: Gtk.ButtonsType.OK_CANCEL,
+            message_type: Gtk.MessageType.WARNING,
+            text: "This action will cause the universe to stop existing." });
+
+        this._messageDialog.connect ('response', Lang.bind(this, this._response_cb));
         this._messageDialog.show();
     },
 
+
+
     // Callback function (aka signal handler) for the response signal
     _response_cb: function (messagedialog, response_id) {
 
@@ -99,11 +110,13 @@ const MessageExample = new Lang.Class ({
                 this.warningLabel.set_label ("Dialog closed or cancelled.\n");
                 break;
         }
-            this._messageDialog.destroy();
+
+        this._messageDialog.destroy();
+
     }
 
 });
 
 // Run the application
-let app = new MessageExample ();
+let app = new MessageDialogExample ();
 app.application.run (ARGV);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]