Pileus Git - ~andy/gtk/blob - docs/reference/gtk/getting_started.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <chapter id="gtk-getting-started" xmlns:xi="http://www.w3.org/2003/XInclude">
   6   <title>Getting Started with GTK+</title>
   7
   8   <para>This chapter is contains some tutorial information to get you
   9   started with GTK+ programming. It assumes that you have GTK+, its
  10   dependencies and a C compiler installed and ready to use. If you
  11   need to build GTK+ itself first, refer to the
  12   <link linkend="gtk-compiling">Compiling the GTK+ libraries</link>
  13   section in this reference.</para>
  14
  15   <section>
  16     <title>Basics</title>
  17
  18     <para>To begin our introduction to GTK, we'll start with the simplest
  19     program possible. This program will create an empty 200x200 pixel
  20     window:</para>
  21
  22     <para>
  23       <inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
  24     </para>
  25
  26     <informalexample><programlisting>
  27       <xi:include href="../../../../examples/window-default.c" parse="text">
  28         <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  29       </xi:include>
  30     </programlisting></informalexample>
  31
  32     <para>You can compile the program above with GCC using:</para>
  33
  34     <para><literallayout>
  35       <literal>gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0`</literal>
  36     </literallayout></para>
  37
  38     <note><para>For more information on how to compile a GTK+ application, please
  39     refer to the <link linkend="gtk-compiling">Compiling GTK+ Applications</link>
  40     section in this reference.</para></note>
  41
  42     <para>All GTK+ applications will, of course, include
  43     <filename>gtk/gtk.h</filename>, which declares functions, types and
  44     macros required by GTK+ applications.</para>
  45
  46     <warning><para>Even if GTK+ installs multiple header files, only the
  47     top-level <filename>gtk/gtk.h</filename> header can be directly included
  48     by third party code. The compiler will abort with an error if any other
  49     header is directly included.</para></warning>
  50
  51     <para>We then proceed into the <function>main</function>() function of the
  52     application, and we declare a <varname>window</varname> variable as a pointer
  53     of type #GtkWidget.</para>
  54
  55     <para>The following line will call gtk_init(), which
  56     is the initialization function for GTK+; this function will set up GTK+,
  57     the type system, the connection to the windowing environment, etc. The
  58     gtk_init() takes as arguments the pointers to the command line arguments
  59     counter and string array; this allows GTK+ to parse specific command line
  60     arguments that control the behavior of GTK+ itself. The parsed arguments
  61     will be removed from the array, leaving the unrecognized ones for your
  62     application to parse.</para>
  63
  64     <note><para>For more information on which command line arguments GTK+
  65     recognizes, please refer to the <link linkend="gtk-running">Running GTK+
  66     Applications</link> section in this reference.</para></note>
  67
  68     <para>The call to gtk_window_new() will create a new #GtkWindow and store
  69     it inside the <varname>window</varname> variable. The type of the window
  70     is %GTK_WINDOW_TOPLEVEL, which means that the #GtkWindow will be managed
  71     by the windowing system: it will have a frame, a title bar and window
  72     controls, depending on the platform.</para>
  73
  74     <para>In order to terminate the application when the #GtkWindow is
  75     destroyed, we connect the #GtkWidget::destroy signal to the gtk_main_quit()
  76     function. This function will terminate the GTK+ main loop started by calling
  77     gtk_main() later. The #GtkWidget::destroy signal is emitted when a widget is
  78     destroyed, either by explicitly calling gtk_widget_destroy() or when the
  79     widget is unparented. Top-level #GtkWindow<!-- -->s are also destroyed when
  80     the Close window control button is clicked.</para>
  81
  82     <para>#GtkWidget<!-- -->s are hidden by default. By calling gtk_widget_show()
  83     on a #GtkWidget we are asking GTK+ to set the visibility attribute so that it
  84     can be displayed. All this work is done after the main loop has been
  85     started.</para>
  86
  87     <para>The last line of interest is the call to gtk_main(). This function will
  88     start the GTK+ main loop and will block the control flow of the
  89     main() until the gtk_main_quit() function is called.</para>
  90
  91     <para>While the program is running, GTK+ is receiving
  92     <firstterm>events</firstterm>. These are typically input events caused by
  93     the user interacting with your program, but also things like messages from
  94     the window manager or other applications. GTK+ processes these and as a
  95     result, <firstterm>signals</firstterm> may be emitted on your widgets.
  96     Connecting handlers for these signals is how you normally make your
  97     program do something in response to user input.</para>
  98
  99     <para>The following example is slightly more complex, and tries to
 100     showcase some of the capabilities of GTK+.</para>
 101
 102     <para>In the long tradition of programming languages and libraries,
 103     it is called <emphasis>Hello, World</emphasis>.</para>
 104
 105     <para>
 106       <inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
 107     </para>
 108
 109     <example id="gtk-getting-started-hello-world">
 110       <title>Hello World in GTK+</title>
 111       <programlisting>
 112         <xi:include href="../../../../examples/hello-world.c" parse="text">
 113           <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
 114         </xi:include>
 115       </programlisting>
 116     </example>
 117   </section>
 118
 119   <section>
 120     <title>Packing</title>
 121
 122     <para>When creating an application, you'll want to put more than one widget
 123     inside a window. Our first helloworld example only used one widget so we
 124     could simply use a gtk_container_add() call to "pack" the widget into the
 125     window. But when you want to put more than one widget into a window, it
 126     it becomes important to control how each widget is positioned and sized.
 127     This is where packing comes in.</para>
 128
 129     <para>GTK+ comes with a large variety of <firstterm>layout containers</firstterm>
 130     whose purpose it is to control the layout of the child widgets that are
 131     added to them. See <xref linkend="LayoutContainers"/> for an overview.</para>
 132
 133     <para>The following example shows how the GtkGrid container lets you
 134     arrange several buttons:</para>
 135
 136     <para>
 137       <inlinegraphic fileref="grid-packing.png" format="PNG"></inlinegraphic>
 138     </para>
 139
 140     <example id="gtk-getting-started-grid-packing">
 141       <title>Packing buttons</title>
 142       <programlisting>
 143         <xi:include href="../../../../examples/grid-packing.c" parse="text">
 144           <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
 145         </xi:include>
 146       </programlisting>
 147     </example>
 148   </section>
 149
 150 </chapter>