[gtk+] Update hello-world.c to GtkApplication, document

[Bastian Ilsø Hougaard <bastianilso src gnome org>]

commit 52f5a78c6daeaf0eec9b014d9cfefb6d844a4f6a
Author: Bastian Ilsø <bastianilso src gnome org>
Date:   Tue Feb 10 16:55:30 2015 +0100

    Update hello-world.c to GtkApplication, document

 docs/reference/gtk/getting_started.xml |   43 +++++++++++++-
 examples/hello-world.c                 |  104 +++++++-------------------------
 2 files changed, 65 insertions(+), 82 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml
index b6d6abe..1fefc79 100644
--- a/docs/reference/gtk/getting_started.xml
+++ b/docs/reference/gtk/getting_started.xml
@@ -100,7 +100,7 @@
     application. Inside the activate() function we want to construct
     our GTK window, so that a window is shown when the application
     is launched. The call to gtk_application_window_new() will
-    createa a new #GtkWindow and store it inside the
+    create a new #GtkWindow and store it inside the
     <varname>window</varname> pointer. The window will have a frame,
     a title bar, and window controls depending on the platform.</para>
 
@@ -165,6 +165,47 @@
     </para>
   </section>
 
+  <para>As seen above, example-1.c builds further upon example-0.c by adding a
+  button to our window, with the label "Hello World". Two new GtkWidget pointers
+  are declared to accomplish this, <varname>button</varname> and
+  <varname>button_box</varname>. The button_box variable is created to store a
+  #GtkButtonBox which is GTK+'s way of controlling the size and layout of buttons.
+  The #GtkButtonBox is created and assigned to gtk_button_box_new() which takes a
+  #GtkOrientation enum as parameter. The buttons which this box will contain can
+  either be stored horizontally or vertically but this does not matter in this
+  particular case as we are dealing with only one button. After initializing
+  button_box with horizontal orientation, the code adds the button_box widget to the
+  window widget using gtk_container_add().</para>
+
+  <para>Next the <varname>button</varname> variable is initialized in similar manner.
+  gtk_button_new_with_label() is called which returns a GtkButton to be stored inside
+  <varname>button</varname>. Afterwards <varname>button</varname> is added to
+  our <varname>button_box</varname>.
+  Using g_signal_connect the button is connected to a function in our app called
+  print_hello(), so that when the button is clicked, GTK will call this function.
+  As the print_hello() function does not use any data as input, NULL is passed
+  to it. print_hello() calls g_print() with the string "Hello World"
+  which will print Hello World in a terminal if the GTK application was started
+  from one.</para>
+
+  <para>After connecting print_hello(), another signal is connected to the "clicked" state
+  of the button using g_signal_connect_swapped(). This functions is similar to
+  a g_signal_connect() with the difference lying in how the callback function is
+  treated. g_signal_connect_swapped() allow you to specify what the callback
+  function should take as parameter by letting you pass it as data. In this case
+  the function being called back is gtk_widget_destroy() and the <varname>window</varname>
+  pointer is passed to it. This has the effect that when the button is clicked,
+  the whole GTK window is destroyed. In contrast if a normal g_signal_connect() were used
+  to connect the "clicked" signal with gtk_widget_destroy(), then the <varname>button</varname>
+  itself would have been destroyed, not the window.
+  More information about creating buttons can be found
+  <ulink url="https://wiki.gnome.org/HowDoI/Buttons";>here</ulink>.
+  </para>
+
+  <para>The rest of the code in example-1.c is identical to example-0.c. Next
+  section will elaborate further on how to add several GtkWidgets to your GTK
+  application.</para>
+
   <section>
     <title>Packing</title>
 
diff --git a/examples/hello-world.c b/examples/hello-world.c
index 204b46e..843b9b2 100644
--- a/examples/hello-world.c
+++ b/examples/hello-world.c
@@ -1,8 +1,5 @@
 #include <gtk/gtk.h>
 
-/* This is a callback function. The data arguments are ignored
- * in this example. More on callbacks below.
- */
 static void
 print_hello (GtkWidget *widget,
              gpointer   data)
@@ -10,95 +7,40 @@ print_hello (GtkWidget *widget,
   g_print ("Hello World\n");
 }
 
-static gboolean
-on_delete_event (GtkWidget *widget,
-                 GdkEvent  *event,
-                 gpointer   data)
-{
-  /* If you return FALSE in the "delete_event" signal handler,
-   * GTK will emit the "destroy" signal. Returning TRUE means
-   * you don't want the window to be destroyed.
-   *
-   * This is useful for popping up 'are you sure you want to quit?'
-   * type dialogs.
-   */
-
-  g_print ("delete event occurred\n");
-
-  return TRUE;
-}
-
-int
-main (int   argc,
-      char *argv[])
+static void
+activate (GtkApplication *app,
+          gpointer        user_data)
 {
-  /* GtkWidget is the storage type for widgets */
   GtkWidget *window;
   GtkWidget *button;
+  GtkWidget *button_box;
 
-  /* This is called in all GTK applications. Arguments are parsed
-   * from the command line and are returned to the application.
-   */
-  gtk_init (&argc, &argv);
-
-  /* create a new window, and set its title */
-  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
-  gtk_window_set_title (GTK_WINDOW (window), "Hello");
+  window = gtk_application_window_new (app);
+  gtk_window_set_title (GTK_WINDOW (window), "Window");
+  gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
 
-  /* When the window emits the "delete-event" signal (which is emitted
-   * by GTK+ in response to an event coming from the window manager,
-   * usually as a result of clicking the "close" window control), we
-   * ask it to call the on_delete_event() function as defined above.
-   *
-   * The data passed to the callback function is NULL and is ignored
-   * in the callback function.
-   */
-  g_signal_connect (window, "delete-event", G_CALLBACK (on_delete_event), NULL);
+  button_box = gtk_button_box_new (GTK_ORIENTATION_HORIZONTAL);
+  gtk_container_add (GTK_CONTAINER (window), button_box);
 
-  /* Here we connect the "destroy" event to the gtk_main_quit() function.
-   *
-   * This signal is emitted when we call gtk_widget_destroy() on the window,
-   * or if we return FALSE in the "delete_event" callback.
-   */
-  g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);
-
-  /* Sets the border width of the window. */
-  gtk_container_set_border_width (GTK_CONTAINER (window), 10);
-
-  /* Creates a new button with the label "Hello World". */
   button = gtk_button_new_with_label ("Hello World");
-
-  /* When the button receives the "clicked" signal, it will call the
-   * function print_hello() passing it NULL as its argument.
-   *
-   * The print_hello() function is defined above.
-   */
   g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
-
-  /* The g_signal_connect_swapped() function will connect the "clicked" signal
-   * of the button to the gtk_widget_destroy() function; instead of calling it
-   * using the button as its argument, it will swap it with the user data
-   * argument. This will cause the window to be destroyed by calling
-   * gtk_widget_destroy() on the window.
-   */
   g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_widget_destroy), window);
+  gtk_container_add (GTK_CONTAINER (button_box), button);
 
-  /* This packs the button into the window. A GtkWindow inherits from GtkBin,
-   * which is a special container that can only have one child
-   */
-  gtk_container_add (GTK_CONTAINER (window), button);
-
-  /* The final step is to display this newly created widget... */
-  gtk_widget_show (button);
+  gtk_widget_show_all (window);
+}
 
-  /* ... and the window */
-  gtk_widget_show (window);
+int
+main (int    argc,
+      char **argv)
+{
+  GtkApplication *app;
+  int status;
 
-  /* All GTK applications must have a gtk_main(). Control ends here
-   * and waits for an event to occur (like a key press or a mouse event),
-   * until gtk_main_quit() is called.
-   */
-  gtk_main ();
+  app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE);
+  g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+  status = g_application_run (G_APPLICATION (app), argc, argv);
+  g_object_unref (app);
 
-  return 0;
+  return status;
 }