GNOME.org
 

[gtk+] Add a paragraph explaining events and signals

commit ce1244fdd74d736e81cb12653fdc956146d03ffc
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jan 18 21:42:29 2011 -0500

    Add a paragraph explaining events and signals

 docs/reference/gtk/getting_started.xml |  191 +++++++++++++++++---------------
 1 files changed, 101 insertions(+), 90 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml
index 6a021fa..3698aa5 100644
--- a/docs/reference/gtk/getting_started.xml
+++ b/docs/reference/gtk/getting_started.xml
@@ -12,97 +12,108 @@
   <link linkend="gtk-compiling">Compiling the GTK+ libraries</link>
   section in this reference.</para>
 
-  <para>To begin our introduction to GTK, we'll start with the simplest
-  program possible. This program will create an empty 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 is directly 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>
-
-  <para>
-    <inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
-  </para>
-
-  <example id="gtk-getting-started-hello-world">
-    <title>Hello World in GTK+</title>
-    <programlisting>
-      <xi:include href="../../../../examples/hello-world.c" parse="text">
+  <section>
+    <title>Basics</title>
+
+    <para>To begin our introduction to GTK, we'll start with the simplest
+    program possible. This program will create an empty 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>
-  </example>
+    </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 is directly 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
+    main() until the gtk_main_quit() function is called.</para>
+
+    <para>While the program is running, GTK+ is receiving
+    <firstterm>events</firstterm>. These are typically input events caused by
+    the user interacting with your program, but also things like messages from
+    the window manager or other applications. GTK+ processes these and as a
+    result, <firstterm>signals</firstterm> may be emitted on your widgets.
+    Connecting handlers for these signals is how you normally make your
+    program do something in response to user input.</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>
+
+    <para>
+      <inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
+    </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>
+  </section>
 
 </chapter>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]