GNOME.org
 

[gtk+] docs: Move the introduction of the tutorial in the reference

commit f085c8b27225baecbca270feb822efc94d1f120b
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Fri Oct 15 11:04:27 2010 -0400

    docs: Move the introduction of the tutorial in the reference
    
    The tutorial should just go away, but some of its contents can be moved
    to the API reference as chapters.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=632059

 docs/reference/gtk/Makefile.am         |    8 ++-
 docs/reference/gtk/getting_started.xml |   96 +++++++++++++++++++++++++++++
 docs/reference/gtk/gtk-docs.sgml       |    1 +
 examples/hello-world.c                 |  103 ++++++++++++++++++++++++++++++++
 examples/window-default.c              |   20 ++++++
 5 files changed, 225 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 4f71a8f..0140db6 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -132,16 +132,18 @@ content_files =					\
 	gtk-query-immodules-3.0.xml		\
 	gtk-update-icon-cache-3.0.xml		\
 	gtk-builder-convert-3.0.xml		\
-	visual_index.xml
+	visual_index.xml			\
+	getting_started.xml
 
 expand_content_files = 				\
 	drawing-model.xml			\
+	getting_started.xml			\
 	glossary.xml				\
 	migrating-2to3.xml			\
 	migrating-checklist.sgml		\
-	tree_widget.sgml			\
+	question_index.sgml			\
 	text_widget.sgml			\
-	question_index.sgml
+	tree_widget.sgml
 
 # Images to copy into HTML directory
 HTML_IMAGES = \
diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml
new file mode 100644
index 0000000..8ce21b9
--- /dev/null
+++ b/docs/reference/gtk/getting_started.xml
@@ -0,0 +1,96 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<chapter id="gtk-getting-started" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <title>Getting Started with GTK+</title>
+
+  <para>To begin our introduction to GTK, we'll start with the simplest
+  program possible. This program will create a 200x200 pixel window:</para>
+
+  <para>
+    <inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
+  </para>
+
+  <informalexample><programlisting>
+    <xi:include href="../../../../examples/window-default.c" parse="text">
+      <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+    </xi:include>
+  </programlisting></informalexample>
+
+  <para>You can compile the program above with GCC using:</para>
+
+  <para><literallayout>
+    <literal>gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0`</literal>
+  </literallayout></para>
+
+  <note><para>For more information on how to compile a GTK+ application, please
+  refer to the <link linkend="gtk-compiling">Compiling GTK+ Applications</link>
+  section in this reference.</para></note>
+
+  <para>All GTK+ applications will, of course, include
+  <filename>gtk/gtk.h</filename>, which declares functions, types and
+  macros required by GTK+ applications.</para>
+
+  <warning><para>Even if GTK+ installs multiple header files, only the
+  top-level <filename>gtk/gtk.h</filename> header can be directly included
+  by third party code. The compiler will abort with an error if any other
+  header will be included.</para></warning>
+
+  <para>We then proceed into the <function>main</function>() function of the
+  application, and we declare a <varname>window</varname> variable as a pointer
+  of type #GtkWidget.</para>
+
+  <para>The following line will call gtk_init(), which
+  is the initialization function for GTK+; this function will set up GTK+,
+  the type system, the connection to the windowing environment, etc. The
+  gtk_init() takes as arguments the pointers to the command line arguments
+  counter and string array; this allows GTK+ to parse specific command line
+  arguments that control the behavior of GTK+ itself. The parsed arguments
+  will be removed from the array, leaving the unrecognized ones for your
+  application to parse.</para>
+
+  <note><para>For more information on which command line arguments GTK+
+  recognizes, please refer to the <link linkend="gtk-running">Running GTK+
+  Applications</link> section in this reference.</para></note>
+
+  <para>The call to gtk_window_new() will create a new #GtkWindow and store
+  it inside the <varname>window</varname> variable. The type of the window
+  is %GTK_WINDOW_TOPLEVEL, which means that the #GtkWindow will be managed
+  by the windowing system: it will have a frame, a title bar and window
+  controls, depending on the platform.</para>
+
+  <para>In order to terminate the application when the #GtkWindow is
+  destroyed, we connect the #GtkWidget::destroy signal to the gtk_main_quit()
+  function. This function will terminate the GTK+ main loop started by calling
+  gtk_main() later. The #GtkWidget::destroy signal is emitted when a widget is
+  destroyed, either by explicitly calling gtk_widget_destroy() or when the
+  widget is unparented. Top-level #GtkWindow<!-- -->s are also destroyed when
+  the Close window control button is clicked.</para>
+
+  <para>#GtkWidget<!-- -->s are hidden by default. By calling gtk_widget_show()
+  on a #GtkWidget we are asking GTK+ to set the visibility attribute so that it
+  can be displayed. All this work is done after the main loop has been
+  started.</para>
+
+  <para>The last line of interest is the call to gtk_main(). This function will
+  start the GTK+ main loop and will block the control flow of the
+  <function>main</function>() until the gtk_main_quit() function is
+  called.</para>
+
+  <para>The following example is slightly more complex, and tries to
+  showcase some of the capabilities of GTK+.</para>
+
+  <para>In the long tradition of programming languages and libraries,
+  it is called <emphasis>Hello, World</emphasis>.</para>
+
+  <example id="gtk-getting-started-hello-world">
+    <title>Hello World in GTK+</title>
+    <programlisting>
+      <xi:include href="../../../examples/hello-world.c" parse="text">
+        <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+      </xi:include>
+    </programlisting>
+  </example>
+
+</chapter>
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index f5497d9..d089e86 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -115,6 +115,7 @@ that is, GUI components such as GtkButton or GtkTextView.
     <xi:include href="building.sgml" />
     <xi:include href="compiling.sgml" />
     <xi:include href="running.sgml" />
+    <xi:include href="xml/getting_started.xml"/>
     <xi:include href="x11.sgml" />
     <xi:include href="windows.sgml" />
     <xi:include href="osx.sgml" />
diff --git a/examples/hello-world.c b/examples/hello-world.c
new file mode 100644
index 0000000..50c792f
--- /dev/null
+++ b/examples/hello-world.c
@@ -0,0 +1,103 @@
+#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)
+{
+  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[])
+{
+  /* GtkWidget is the storage type for widgets */
+  GtkWidget *window;
+  GtkWidget *button;
+
+  /* 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");
+
+  /* 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);
+
+  /* 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);
+
+  /* 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);
+
+  /* ... and the window */
+  gtk_widget_show (window);
+
+  /* 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 ();
+
+  return 0;
+}
diff --git a/examples/window-default.c b/examples/window-default.c
new file mode 100644
index 0000000..79888de
--- /dev/null
+++ b/examples/window-default.c
@@ -0,0 +1,20 @@
+#include <gtk/gtk.h>
+
+int
+main (int   argc,
+      char *argv[])
+{
+  GtkWidget *window;
+
+  gtk_init (&argc, &argv);
+
+  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+
+  g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);
+
+  gtk_widget_show (window);
+
+  gtk_main ();
+
+  return 0;
+}
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]