gtk2/docs/reference/gtk/getting_started.xml

<?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>This chapter is contains some tutorial information to get you
  started with GTK+ programming. It assumes that you have GTK+, its
  dependencies and a C compiler installed and ready to use. If you
  need to build GTK+ itself first, refer to the
  <link linkend="gtk-compiling">Compiling the GTK+ libraries</link>
  section in this reference.</para>

  <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></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>