getting_started.xml 44 KB
Newer Older
1 2 3 4 5 6 7
<?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>

8 9 10 11 12 13 14
  <para>GTK+ is a <ulink url="http://en.wikipedia.org/wiki/Widget_toolkit">
  widget toolkit</ulink>. Each user interface created by 
  GTK+ consists of widgets. This is implemented in C using 
  <link linkend="gobject">GObject</link>, an object-oriented framework for C.
  Widgets are organized in a hierachy. The window widget is the main container.
  The user interface is then built by adding buttons, drop-down menus, input 
  fields, and other widgets to the window.
15
  If you are creating complex user interfaces it is recommended to
16 17 18 19 20 21 22
  use #GtkBuilder and its GTK-specific markup description language, instead of
  assembling the interface manually. You can also use a visual user interface
  editor, like <ulink url="https://glade.gnome.org/">Glade</ulink>.</para>
  
  <para>GTK+ is event-driven. The toolkit listens for events such as
  a click on a button, and passes the event to your application.</para>

23
  <para>This chapter contains some tutorial information to get you
24 25 26 27 28 29
  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>

Matthias Clasen's avatar
Matthias Clasen committed
30
  <section>
31 32
    <title>Basics</title>

33 34
    <para>To begin our introduction to GTK, we'll start with a simple
    signal-based Gtk application. This program will create an empty 200 × 200 pixel
35
    window.</para>
36

37 38 39 40 41 42 43
    <informalfigure>
      <mediaobject>
        <imageobject>
          <imagedata fileref="window-default.png" format="PNG"/>
        </imageobject>
      </mediaobject>
    </informalfigure>
44

45
    <informalexample>
46
      <para>Create a new file with the following content named <filename>example-0.c.</filename></para>
47
      <programlisting><xi:include href="../../../../examples/window-default.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
48
    </informalexample>
49

50 51 52 53 54 55
    <para>
      You can compile the program above with GCC using:
      <literallayout>
        <literal>gcc `pkg-config --cflags gtk+-3.0` -o example-0 example-0.c `pkg-config --libs gtk+-3.0`</literal>
      </literallayout>
    </para>
56 57 58 59 60 61 62 63 64 65 66 67 68 69

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

70 71 72 73 74 75 76 77 78 79 80 81 82 83
    <para>In a GTK+ application, the purpose of the main() function is to
    create a #GtkApplication object and run it. In this example a
    #GtkApplication pointer named <varname>app</varname> is called and then
    initialized using gtk_application_new().</para>

    <para>When creating a #GtkApplication
    you need to pick an application identifier (a name)
    and input to gtk_application_new() as parameter.
    For this example <varname>org.gtk.example</varname> is used
    but for choosing an identifier for your application see
    <ulink url="https://wiki.gnome.org/HowDoI/ChooseApplicationID">this guide</ulink>.
    Lastly gtk_application_new() takes a GApplicationFlags as input for your 
    application, if your application would have special needs.
    </para>
84

85 86 87 88 89 90 91
    <para>Next the
    <ulink url="https://wiki.gnome.org/HowDoI/GtkApplication">activate signal</ulink>
    is connected to the activate() function above the main() functions.
    The <varname>activate</varname> signal will be sent
    when your application is launched with
    g_application_run() on the line below.
    The gtk_application_run() also takes as arguments the pointers to the command line arguments
92 93 94
    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
95 96
    application to parse.
    </para>
97

98 99 100 101 102
    <para>Within g_application_run the activate() signal is sent and
    we then proceed into the <function>activate</function>() function of the
    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
103
    create a new #GtkWindow and store it inside the
104 105
    <varname>window</varname> pointer. The window will have a frame,
    a title bar, and window controls depending on the platform.</para>
106

107
    <para>A window title is set using gtk_window_set_title(). This function
108
    takes a GtkWindow* pointer and a string as input. As our
109 110
    <varname>window</varname> pointer is a GtkWidget pointer, we need to cast it
    to GtkWindow*.
111
    But instead of casting <varname>window</varname> via
112
    <varname>(GtkWindow*)</varname>, 
113
    <varname>window</varname> can be cast using the macro
114 115 116 117 118 119 120 121
    <varname>GTK_WINDOW()</varname>.
    <varname>GTK_WINDOW()</varname> will check if the 
    pointer is an instance of the GtkWindow class, before casting, and emit a
    warning if the check fails. More information about this convention 
    can be found 
    <ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html">
    here</ulink>.</para>

122 123 124 125 126 127 128 129
    <para>Finally the window size is set using gtk_window_set_default_size and
    the window is then shown by GTK via gtk_widget_show_all().</para>

    <para>When you exit the window, by for example pressing the X,
    the g_application_run() in the main loop returns with a number
    which is saved inside an integer named "status". Afterwards, the
    #GtkApplication object is freed from memory with g_object_unref().
    Finally the status integer is returned and the GTK application exits.</para>
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

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

145 146 147 148 149 150 151
    <informalfigure>
      <mediaobject>
        <imageobject>
          <imagedata fileref="hello-world.png" format="PNG"/>
        </imageobject>
      </mediaobject>
    </informalfigure>
152 153 154

    <example id="gtk-getting-started-hello-world">
      <title>Hello World in GTK+</title>
155 156
      <para>Create a new file with the following content named example-1.c.</para>
      <programlisting><xi:include href="../../../../examples/hello-world.c" parse="text">
157
          <xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
158
    </example>
159 160 161 162 163 164 165

    <para>
      You can compile the program above with GCC using:
      <literallayout>
        <literal>gcc `pkg-config --cflags gtk+-3.0` -o example-1 example-1.c `pkg-config --libs gtk+-3.0`</literal>
      </literallayout>
    </para>
Matthias Clasen's avatar
Matthias Clasen committed
166
  </section>
167

168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
  <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>

Matthias Clasen's avatar
Matthias Clasen committed
209
  <section>
210 211 212
    <title>Packing</title>

    <para>When creating an application, you'll want to put more than one widget
213
    inside a window.
214
    When you want to put more than one widget into a window,
215 216 217 218 219 220 221 222 223 224
    it becomes important to control how each widget is positioned and sized.
    This is where packing comes in.</para>

    <para>GTK+ comes with a large variety of <firstterm>layout containers</firstterm>
    whose purpose it is to control the layout of the child widgets that are
    added to them. See <xref linkend="LayoutContainers"/> for an overview.</para>

    <para>The following example shows how the GtkGrid container lets you
    arrange several buttons:</para>

225 226 227 228 229 230 231
    <informalfigure>
      <mediaobject>
        <imageobject>
          <imagedata fileref="grid-packing.png" format="PNG"/>
        </imageobject>
      </mediaobject>
    </informalfigure>
232 233 234

    <example id="gtk-getting-started-grid-packing">
      <title>Packing buttons</title>
235
      <para>Create a new file with the following content named example-2.c.</para>
236
      <programlisting><xi:include href="../../../../examples/grid-packing.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
237
    </example>
238 239 240 241 242 243
    <para>
      You can compile the program above with GCC using:
      <literallayout>
        <literal>gcc `pkg-config --cflags gtk+-3.0` -o example-2 example-2.c `pkg-config --libs gtk+-3.0`</literal>
      </literallayout>
    </para>
Matthias Clasen's avatar
Matthias Clasen committed
244
  </section>
245

Matthias Clasen's avatar
Matthias Clasen committed
246 247
  <section>
    <title>Building user interfaces</title>
248

249
    <para>When construcing a more complicated user interface, with dozens
250 251 252 253 254 255 256 257 258
    or hundreds of widgets, doing all the setup work in C code is
    cumbersome, and making changes becomes next to impossible.</para>

    <para>Thankfully, GTK+ supports the separation of user interface
    layout from your business logic, by using UI descriptions in an
    XML format that can be parsed by the #GtkBuilder class.</para>

    <example>
      <title>Packing buttons with GtkBuilder</title>
259
      <para>Create a new file with the following content named example-3.c.</para>
260
      <programlisting><xi:include href="../../../../examples/builder.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
261
      <para>Create a new file with the following content named builder.ui.</para>
262
      <programlisting><xi:include href="../../../../examples/builder.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
263
    </example>
264 265 266
    <para>
      You can compile the program above with GCC using:
      <literallayout>
267
        <literal>gcc `pkg-config --cflags gtk+-3.0` -o example-3 example-3.c `pkg-config --libs gtk+-3.0`</literal>
268 269
      </literallayout>
    </para>
270 271 272 273 274 275 276 277

    <para>Note that GtkBuilder can also be used to construct objects
    that are not widgets, such as tree models, adjustments, etc.
    That is the reason the method we use here is called
    gtk_builder_get_object() and returns a GObject* instead of a
    GtkWidget*.</para>

    <para>Normally, you would pass a full path to
Florian Müllner's avatar
Florian Müllner committed
278
    gtk_builder_add_from_file() to make the execution of your program
279 280 281 282 283 284 285 286 287 288 289 290 291
    independent of the current directory. A common location to install
    UI descriptions and similar data is
    <filename>/usr/share/<replaceable>appname</replaceable></filename>.
    </para>

    <para>It is also possible to embed the UI description in the source
    code as a string and use gtk_builder_add_from_string() to load it.
    But keeping the UI description in a separate file has several
    advantages: It is then possible to make minor adjustments to the UI
    without recompiling your program, and, more importantly, graphical
    UI editors such as <ulink url="http://glade.gnome.org">glade</ulink>
    can load the file and allow you to create and modify your UI by
    point-and-click.</para>
Matthias Clasen's avatar
Matthias Clasen committed
292 293 294 295 296
  </section>

  <section>
    <title>Building applications</title>

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
    <para>An application consists of a number of files:
    <variablelist>
      <varlistentry>
        <term>The binary</term>
        <listitem>This gets installed in <filename>/usr/bin</filename>.</listitem>
      </varlistentry>
      <varlistentry>
        <term>A desktop file</term>
        <listitem>The desktop file provides important information about the application to the desktop shell, such as its name, icon, D-Bus name, commandline to launch it, etc. It is installed in <filename>/usr/share/applications</filename>.</listitem>
      </varlistentry>
      <varlistentry>
        <term>An icon</term>
        <listitem>The icon gets installed in <filename>/usr/share/icons/hicolor/48x48/apps</filename>, where it will be found regardless of the current theme.</listitem>
      </varlistentry>
      <varlistentry>
        <term>A settings schema</term>
        <listitem>If the application uses GSettings, it will install its schema
          in <filename>/usr/share/glib-2.0/schemas</filename>, so that tools
          like dconf-editor can find it.</listitem>
      </varlistentry>
      <varlistentry>
        <term>Other resources</term>
        <listitem>Other files, such as GtkBuilder ui files, are best loaded from
          resources stored in the application binary itself. This eliminates the
          need for most of the files that would traditionally be installed in
          an application-specific location in <filename>/usr/share</filename>.</listitem>
      </varlistentry>
    </variablelist>
    </para>

Matthias Clasen's avatar
Matthias Clasen committed
327 328 329 330 331 332 333
    <para>GTK+ includes application support that is built on top of
    #GApplication. In this tutorial we'll build a simple application by
    starting from scratch, adding more and more pieces over time. Along
    the way, we'll learn about #GtkApplication, templates, resources,
    application menus, settings, #GtkHeaderBar, #GtkStack, #GtkSearchBar,
    #GtkListBox, and more.</para>

Matthias Clasen's avatar
Matthias Clasen committed
334
    <para>The full, buildable sources for these examples can be found
Matthias Clasen's avatar
Matthias Clasen committed
335
    in the examples/ directory of the GTK+ source distribution, or
336 337 338 339
    <ulink url="https://git.gnome.org/browse/gtk+/tree/examples">online</ulink> in the GTK+ git repository.
    You can build each example separately by using make with the <filename>Makefile.example</filename>
    file. For more information, see the <filename>README</filename> included in the
    examples directory.</para>
Matthias Clasen's avatar
Matthias Clasen committed
340 341 342 343 344 345 346 347 348

    <section>
      <title>A trivial application</title>

      <para>When using #GtkApplication, the main() function can be very
      simple. We just call g_application_run() and give it an instance
      of our application class.</para>

      <informalexample>
349
        <programlisting><xi:include href="../../../../examples/application1/main.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
350 351 352 353 354 355 356 357
      </informalexample>

      <para>All the application logic is in the application class, which
      is a subclass of #GtkApplication. Our example does not yet have any
      interesting functionality. All it does is open a window when it is
      activated without arguments, and open the files it is given, if it
      is started with arguments.</para>

358 359 360 361 362 363
      <para>To handle these two cases, we override the activate() vfunc,
      which gets called when the application is launched without commandline
      arguments, and the open() vfunc, which gets called when the application
      is launched with commandline arguments.</para>

      <para>To learn more about GApplication entry points, consult the
364
      GIO <ulink url="https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description">documentation</ulink>.</para>
365

Matthias Clasen's avatar
Matthias Clasen committed
366
      <informalexample>
367
        <programlisting><xi:include href="../../../../examples/application1/exampleapp.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
368 369 370 371 372 373 374 375
      </informalexample>

      <para>Another important class that is part of the application support
      in GTK+ is #GtkApplicationWindow. It is typically subclassed as well.
      Our subclass does not do anything yet, so we will just get an empty
      window.</para>

      <informalexample>
376
        <programlisting><xi:include href="../../../../examples/application1/exampleappwin.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
377 378
      </informalexample>

379 380 381 382 383 384 385 386 387 388 389 390
      <para>As part of the initial setup of our application, we also
      create an icon and a desktop file.</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="exampleapp.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>

      <informalexample>
391
        <programlisting><xi:include href="../../../../examples/application1/exampleapp.desktop" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
392 393 394 395 396
      </informalexample>

      <para>Note that <replaceable>@<!-- -->bindir@</replaceable> needs to be replaced
      with the actual path to the binary before this desktop file can be used.</para>

Matthias Clasen's avatar
Matthias Clasen committed
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
      <para>Here is what we've achieved so far:</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app1.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>

      <para>This does not look very impressive yet, but our application
      is already presenting itself on the session bus, it has single-instance
      semantics, and it accepts files as commandline arguments.</para>
    </section>

    <section>
      <title>Populating the window</title>

      <para>In this step, we use a #GtkBuilder template to associate a
      #GtkBuilder ui file with our application window class.</para>
      <para>Our simple ui file puts a #GtkHeaderBar on top of a #GtkStack
      widget. The header bar contains a #GtkStackSwitcher, which is a
      standalone widget to show a row of 'tabs' for the pages of a #GtkStack.
      </para>

      <informalexample>
423
        <programlisting><xi:include href="../../../../examples/application2/window.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440
      </informalexample>

      <para>To make use of this file in our application, we revisit
      our #GtkApplicationWindow subclass, and call
      gtk_widget_class_set_template_from_resource() from the class init
      function to set the ui file as template for this class. We also
      add a call to gtk_widget_init_template() in the instance init
      function to instantiate the template for each instance of our
      class.</para>

      <informalexample>
        <programlisting><![CDATA[
 ...

static void
example_app_window_init (ExampleAppWindow *win)
{
441
  gtk_widget_init_template (GTK_WIDGET (win));
Matthias Clasen's avatar
Matthias Clasen committed
442 443 444 445 446
}

static void
example_app_window_class_init (ExampleAppWindowClass *class)
{
447 448
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
                                               "/org/gtk/exampleapp/window.ui");
Matthias Clasen's avatar
Matthias Clasen committed
449 450 451 452
}

 ...
        ]]></programlisting>
453
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application2/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
454 455
      </informalexample>

456
      <para>You may have noticed that we used the <literal>_from_resource(<!-- -->)</literal> variant
Matthias Clasen's avatar
Matthias Clasen committed
457 458 459 460 461 462
      of the function that sets a template. Now we need to use GLib's resource
      functionality to include the ui file in the binary. This is commonly
      done by listing all resources in a .gresource.xml file, such as this:
      </para>

      <informalexample>
463
        <programlisting><xi:include href="../../../../examples/application2/exampleapp.gresource.xml" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
      </informalexample>

      <para>This file has to be converted into a C source file that will be
      compiled and linked into the application together with the other source
      files. To do so, we use the glib-compile-resources utility:</para>

      <screen>
      glib-compile-resources exampleapp.gresource.xml --target=resources.c --generate-source
      </screen>

      <para>Our application now looks like this:</para>

      <informalfigure>
       <mediaobject>
        <imageobject>
          <imagedata fileref="getting-started-app2.png" format="PNG"/>
        </imageobject>
      </mediaobject>
      </informalfigure>
    </section>

    <section>
      <title>Opening files</title>

      <para>In this step, we make our application show the content of
      all the files that it is given on the commandline.</para>

      <para>To this end, we add a private struct to our application
      window subclass and keep a reference to the #GtkStack there.
493 494 495 496
      The gtk_widget_class_bind_template_child_private() function
      arranges things so that after instantiating the template, the
      @stack member of the private struct will point to the widget of
      the same name from the template.</para>
Matthias Clasen's avatar
Matthias Clasen committed
497 498 499 500 501

      <informalexample>
        <programlisting><![CDATA[
...

502 503 504
struct _ExampleAppWindowPrivate
{
  GtkWidget *stack;
Matthias Clasen's avatar
Matthias Clasen committed
505 506 507 508 509 510 511 512 513
};

G_DEFINE_TYPE_WITH_PRIVATE(ExampleAppWindow, example_app_window, GTK_TYPE_APPLICATION_WINDOW);

...

static void
example_app_window_class_init (ExampleAppWindowClass *class)
{
514 515
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
                                               "/org/gtk/exampleapp/window.ui");
516
  gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (class), ExampleAppWindow, stack);
Matthias Clasen's avatar
Matthias Clasen committed
517 518 519 520
}

...
        ]]></programlisting>
521
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application3/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
522 523 524 525 526 527 528 529 530 531 532 533 534 535
      </informalexample>

      <para>Now we revisit the example_app_window_open() function that
      is called for each commandline argument, and construct a GtkTextView
      that we then add as a page to the stack:</para>

      <informalexample>
        <programlisting><![CDATA[
...

void
example_app_window_open (ExampleAppWindow *win,
                         GFile            *file)
{
536 537 538 539 540 541 542 543 544 545 546 547 548 549
  ExampleAppWindowPrivate *priv;
  gchar *basename;
  GtkWidget *scrolled, *view;
  gchar *contents;
  gsize length;

  priv = example_app_window_get_instance_private (win);
  basename = g_file_get_basename (file);

  scrolled = gtk_scrolled_window_new (NULL, NULL);
  gtk_widget_show (scrolled);
  gtk_widget_set_hexpand (scrolled, TRUE);
  gtk_widget_set_vexpand (scrolled, TRUE);
  view = gtk_text_view_new ();
550 551
  gtk_text_view_set_editable (GTK_TEXT_VIEW (view), FALSE);
  gtk_text_view_set_cursor_visible (GTK_TEXT_VIEW (view), FALSE);
552 553 554 555 556 557 558 559 560 561 562 563 564 565
  gtk_widget_show (view);
  gtk_container_add (GTK_CONTAINER (scrolled), view);
  gtk_stack_add_titled (GTK_STACK (priv->stack), scrolled, basename, basename);

  if (g_file_load_contents (file, NULL, &contents, &length, NULL, NULL))
    {
      GtkTextBuffer *buffer;

      buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
      gtk_text_buffer_set_text (buffer, contents, length);
      g_free (contents);
    }

  g_free (basename);
Matthias Clasen's avatar
Matthias Clasen committed
566 567 568 569
}

...
        ]]></programlisting>
570
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application3/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
571 572 573 574 575
      </informalexample>

      <para>Note that we did not have to touch the stack switcher
      at all. It gets all its information from the stack that it
      belongs to. Here, we are passing the label to show for each
576
      file as the last argument to the gtk_stack_add_titled()
Matthias Clasen's avatar
Matthias Clasen committed
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600
      function.</para>

      <para>Our application is beginning to take shape:</para>

      <informalfigure>
       <mediaobject>
        <imageobject>
          <imagedata fileref="getting-started-app3.png" format="PNG"/>
        </imageobject>
      </mediaobject>
      </informalfigure>
    </section>

    <section>
      <title>An application menu</title>

      <para>An application menu is shown by GNOME shell at the top of the
      screen. It is meant to collect infrequently used actions that affect
      the whole application.</para>

      <para>Just like the window template, we specify our application menu
      in a ui file, and add it as a resource to our binary.</para>

      <informalexample>
601
        <programlisting><xi:include href="../../../../examples/application4/app-menu.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630
      </informalexample>

      <para>To associate the app menu with the application, we have to call
      gtk_application_set_app_menu(). Since app menus work by activating
      #GActions, we also have to add a suitable set of actions to our
      application.</para>

      <para>Both of these tasks are best done in the startup() vfunc,
      which is guaranteed to be called once for each primary application
      instance:</para>
      <informalexample>
        <programlisting>
...

static void
preferences_activated (GSimpleAction *action,
                       GVariant      *parameter,
                       gpointer       app)
{
}

static void
quit_activated (GSimpleAction *action,
                GVariant      *parameter,
                gpointer       app)
{
  g_application_quit (G_APPLICATION (app));
}

631 632 633 634
static GActionEntry app_entries[] =
{
  { "preferences", preferences_activated, NULL, NULL, NULL },
  { "quit", quit_activated, NULL, NULL, NULL }
Matthias Clasen's avatar
Matthias Clasen committed
635 636 637 638 639
};

static void
example_app_startup (GApplication *app)
{
640 641
  GtkBuilder *builder;
  GMenuModel *app_menu;
642
  const gchar *quit_accels[2] = { "&lt;Ctrl&gt;Q", NULL };
Matthias Clasen's avatar
Matthias Clasen committed
643

644
  G_APPLICATION_CLASS (example_app_parent_class)->startup (app);
Matthias Clasen's avatar
Matthias Clasen committed
645

646 647 648
  g_action_map_add_action_entries (G_ACTION_MAP (app),
                                   app_entries, G_N_ELEMENTS (app_entries),
                                   app);
649 650 651
  gtk_application_set_accels_for_action (GTK_APPLICATION (app),
                                         "app.quit",
                                         quit_accels);
Matthias Clasen's avatar
Matthias Clasen committed
652

653 654 655 656
  builder = gtk_builder_new_from_resource ("/org/gtk/exampleapp/app-menu.ui");
  app_menu = G_MENU_MODEL (gtk_builder_get_object (builder, "appmenu"));
  gtk_application_set_app_menu (GTK_APPLICATION (app), app_menu);
  g_object_unref (builder);
Matthias Clasen's avatar
Matthias Clasen committed
657 658 659 660 661
}

static void
example_app_class_init (ExampleAppClass *class)
{
662 663
  G_APPLICATION_CLASS (class)->startup = example_app_startup;
  ...
Matthias Clasen's avatar
Matthias Clasen committed
664 665 666 667
}

...
        </programlisting>
668
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application4/exampleapp.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
669 670 671 672 673
      </informalexample>

      <para>Our preferences menu item does not do anything yet,
      but the Quit menu item is fully functional. Note that it
      can also be activated by the usual Ctrl-Q shortcut. The
674
      shortcut was added with gtk_application_set_accels_for_action().
Matthias Clasen's avatar
Matthias Clasen committed
675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699
      </para>

      <para>The application menu looks like this:</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app4.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>

    <section>
      <title>A preference dialog</title>

      <para>A typical application will have a some preferences that
      should be remembered from one run to the next. Even for our
      simple example application, we may want to change the font
      that is used for the content.</para>

      <para>We are going to use GSettings to store our preferences.
      GSettings requires a schema that describes our settings:</para>

      <informalexample>
700
        <programlisting><xi:include href="../../../../examples/application5/org.gtk.exampleapp.gschema.xml" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720
      </informalexample>

      <para>Before we can make use of this schema in our application,
      we need to compile it into the binary form that GSettings
      expects. GIO provides <ulink url="https://developer.gnome.org/gio/2.36/ch31s06.html">macros</ulink>
      to do this in autotools-based projects.</para>

      <para>Next, we need to connect our settings to the widgets
      that they are supposed to control. One convenient way to do
      this is to use GSettings bind functionality to bind settings
      keys to object properties, as we do here for the transition
      setting.</para>

      <informalexample>
        <programlisting><![CDATA[
...

static void
example_app_window_init (ExampleAppWindow *win)
{
721
  ExampleAppWindowPrivate *priv;
Matthias Clasen's avatar
Matthias Clasen committed
722

723 724 725
  priv = example_app_window_get_instance_private (win);
  gtk_widget_init_template (GTK_WIDGET (win));
  priv->settings = g_settings_new ("org.gtk.exampleapp");
Matthias Clasen's avatar
Matthias Clasen committed
726

727 728 729
  g_settings_bind (priv->settings, "transition",
                   priv->stack, "transition-type",
                   G_SETTINGS_BIND_DEFAULT);
Matthias Clasen's avatar
Matthias Clasen committed
730 731 732 733
}

...
        ]]></programlisting>
734
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application5/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751
      </informalexample>

      <para>The code to connect the font setting is a little more involved,
      since there is no simple object property that it corresponds to, so
      we are not going to go into that here.</para>

      <para>At this point, the application will already react if you
      change one of the settings, e.g. using the gsettings commandline
      tool. Of course, we expect the application to provide a preference
      dialog for these. So lets do that now. Our preference dialog will
      be a subclass of GtkDialog, and we'll use the same techniques that
      we've already seen: templates, private structs, settings
      bindings.</para>

      <para>Lets start with the template.</para>

      <informalexample>
752
        <programlisting><xi:include href="../../../../examples/application6/prefs.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
753 754 755 756 757
      </informalexample>

      <para>Next comes the dialog subclass.</para>

      <informalexample>
758
        <programlisting><xi:include href="../../../../examples/application6/exampleappprefs.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
759 760
      </informalexample>

761
      <para>Now we revisit the <literal>preferences_activated(<!-- -->)</literal> function in our
Matthias Clasen's avatar
Matthias Clasen committed
762 763 764 765 766 767 768 769 770 771 772
      application class, and make it open a new preference dialog.</para>

      <informalexample>
        <programlisting><![CDATA[
...

static void
preferences_activated (GSimpleAction *action,
                       GVariant      *parameter,
                       gpointer       app)
{
773 774
  ExampleAppPrefs *prefs;
  GtkWindow *win;
Matthias Clasen's avatar
Matthias Clasen committed
775

776 777 778
  win = gtk_application_get_active_window (GTK_APPLICATION (app));
  prefs = example_app_prefs_new (EXAMPLE_APP_WINDOW (win));
  gtk_window_present (GTK_WINDOW (prefs));
Matthias Clasen's avatar
Matthias Clasen committed
779 780 781 782
}

...
        ]]></programlisting>
783
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application6/exampleapp.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809
      </informalexample>

      <para>After all this work, our application can now show
      a preference dialog like this:</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app6.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>

    <section>
      <title>Adding a search bar</title>

      <para>We continue to flesh out the functionality of our application.
      For now, we add search. GTK+ supports this with #GtkSearchEntry and
      #GtkSearchBar. The search bar is a widget that can slide in from the
      top to present a search entry.</para>

      <para>We add a toggle button to the header bar, which can be used
      to slide out the search bar below the header bar.</para>

      <informalexample>
810
        <programlisting><xi:include href="../../../../examples/application7/window.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825
      </informalexample>

      <para>Implementing the search needs quite a few code changes that
      we are not going to completely go over here. The central piece of
      the search implementation is a signal handler that listens for
      text changes in the search entry.</para>

      <informalexample>
        <programlisting><![CDATA[
...

static void
search_text_changed (GtkEntry         *entry,
                     ExampleAppWindow *win)
{
826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
  ExampleAppWindowPrivate *priv;
  const gchar *text;
  GtkWidget *tab;
  GtkWidget *view;
  GtkTextBuffer *buffer;
  GtkTextIter start, match_start, match_end;

  text = gtk_entry_get_text (entry);

  if (text[0] == '\0')
    return;

  priv = example_app_window_get_instance_private (win);

  tab = gtk_stack_get_visible_child (GTK_STACK (priv->stack));
  view = gtk_bin_get_child (GTK_BIN (tab));
  buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));

  /* Very simple-minded search implementation */
  gtk_text_buffer_get_start_iter (buffer, &start);
  if (gtk_text_iter_forward_search (&start, text, GTK_TEXT_SEARCH_CASE_INSENSITIVE,
                                    &match_start, &match_end, NULL))
    {
      gtk_text_buffer_select_range (buffer, &match_start, &match_end);
      gtk_text_view_scroll_to_iter (GTK_TEXT_VIEW (view), &match_start,
                                    0.0, FALSE, 0.0, 0.0);
    }
Matthias Clasen's avatar
Matthias Clasen committed
853 854 855 856 857 858 859 860
}

static void
example_app_window_init (ExampleAppWindow *win)
{

...

861
  gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (class), search_text_changed);
Matthias Clasen's avatar
Matthias Clasen committed
862 863 864 865 866 867 868

...

}

...
        ]]></programlisting>
869
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application7/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885
      </informalexample>

      <para>With the search bar, our application now looks like this:</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app7.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>

    <section>
      <title>Adding a side bar</title>

Matthias Clasen's avatar
Matthias Clasen committed
886 887
      <para>As another piece of functionality, we are adding a sidebar,
      which demonstrates #GtkMenuButton, #GtkRevealer and #GtkListBox.</para>
Matthias Clasen's avatar
Matthias Clasen committed
888 889

      <informalexample>
890
        <programlisting><xi:include href="../../../../examples/application8/window.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
891 892 893 894 895 896 897 898 899 900
      </informalexample>

      <para>The code to populate the sidebar with buttons for the words
      found in each file is a little too involved to go into here. But we'll
      look at the code to add the gears menu.</para>

      <para>As expected by now, the gears menu is specified in a GtkBuilder
      ui file.</para>

      <informalexample>
901
        <programlisting><xi:include href="../../../../examples/application8/gears-menu.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
Matthias Clasen's avatar
Matthias Clasen committed
902 903
      </informalexample>

904 905
      <para>To connect the menuitem to the show-words setting, we use
      a #GAction corresponding to the given #GSettings key.</para>
Matthias Clasen's avatar
Matthias Clasen committed
906 907 908 909 910 911 912 913 914 915 916

      <informalexample>
        <programlisting><![CDATA[
...

static void
example_app_window_init (ExampleAppWindow *win)
{

...

917 918 919 920
  builder = gtk_builder_new_from_resource ("/org/gtk/exampleapp/gears-menu.ui");
  menu = G_MENU_MODEL (gtk_builder_get_object (builder, "menu"));
  gtk_menu_button_set_menu_model (GTK_MENU_BUTTON (priv->gears), menu);
  g_object_unref (builder);
Matthias Clasen's avatar
Matthias Clasen committed
921

922 923 924
  action = g_settings_create_action (priv->settings, "show-words");
  g_action_map_add_action (G_ACTION_MAP (win), action);
  g_object_unref (action);
Matthias Clasen's avatar
Matthias Clasen committed
925 926 927 928
}

...
        ]]></programlisting>
929
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application8/exampleappwin.c">full source</ulink>)</para>
Matthias Clasen's avatar
Matthias Clasen committed
930 931 932
      </informalexample>

      <para>What our application looks like now:</para>
933

Matthias Clasen's avatar
Matthias Clasen committed
934 935 936 937 938 939 940 941
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app8.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>
942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959
    <section>
      <title>Properties</title>

      <para>Widgets and other objects have many useful properties.</para>

      <para>Here we show some ways to use them in new and flexible ways,
      by wrapping them in actions with #GPropertyAction or by binding them
      with #GBinding.</para>

      <para>To set this up, we add two labels to the header bar in our
      window template, named @lines_label and @lines, and bind them to
      struct members in the private struct, as we've seen a couple of times
      by now.</para>

      <para>We add a new "Lines" menu item to the gears menu, which
      triggers the show-lines action:</para>

      <informalexample>
960
        <programlisting><xi:include href="../../../../examples/application9/gears-menu.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991
      </informalexample>

      <para>To make this menu item do something, we create a property
      action for the visible property of the @lines label, and add it to the
      actions of the window. The effect of this is that the visibility
      of the label gets toggled every time the action is activated.</para>

      <para>Since we want both labels to appear and disappear together,
      we bind the visible property of the @lines_label widget to the
      same property of the @lines widget.</para>

      <informalexample>
        <programlisting>
...

static void
example_app_window_init (ExampleAppWindow *win)
{
  ...

  action = (GAction*) g_property_action_new ("show-lines", priv->lines, "visible");
  g_action_map_add_action (G_ACTION_MAP (win), action);
  g_object_unref (action);

  g_object_bind_property (priv->lines, "visible",
                          priv->lines_label, "visible",
                          G_BINDING_DEFAULT);
}

...
        </programlisting>
992
        <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application9/exampleappwin.c">full source</ulink>)</para>
993 994 995 996
      </informalexample>

      <para>We also need a function that counts the lines of the currently
      active tab, and updates the @lines label. See the
997
      <ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-22/examples/application9/exampleappwin.c">full source</ulink>
998 999
      if you are interested in the details.</para>

1000
      <para>This brings our example application to this appearance:</para>
1001 1002 1003 1004 1005 1006 1007 1008 1009

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app9.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>
1010 1011 1012 1013 1014 1015 1016 1017 1018 1019
    <section>
      <title>Header bar</title>

      <para>Our application already uses a GtkHeaderBar, but so far it
      still gets a 'normal' window titlebar on top of that. This is a
      bit redundant, and we will now tell GTK+ to use the header bar
      as replacement for the titlebar. To do so, we move it around to
      be a direct child of the window, and set its type to be titlebar.</para>

      <informalexample>
1020
        <programlisting><xi:include href="../../../../examples/application10/window.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
1021 1022
      </informalexample>

1023 1024
      <para>A small extra bonus of using a header bar is that we get
      a fallback application menu for free. Here is how the
1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036
      application now looks, if this fallback is used.</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata fileref="getting-started-app10.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </informalfigure>

      <para>If we set up the window icon for our window, the menu button
      will use that instead of the generic placeholder icon you see
Yosef Or Boczko's avatar
Yosef Or Boczko committed
1037
      here.</para>
1038
    </section>
Matthias Clasen's avatar
Matthias Clasen committed
1039
  </section>
1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053

  <section>
    <title>Custom Drawing</title>

    <para>Many widgets, like buttons, do all their drawing themselves. You
    just tell them the label you want to see, and they figure out what font
    to use, draw the button outline and focus rectangle, etc. Sometimes, it
    is necessary to do some custom drawing. In that case, a #GtkDrawingArea
    might be the right widget to use. It offers a canvas on which you can
    draw by connecting to the #GtkWidget::draw signal.
    </para>

    <para>The contents of a widget often need to be partially or fully redrawn,
    e.g. when another window is moved and uncovers part of the widget, or
1054
    when the window containing it is resized. It is also possible to explicitly
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074
    cause part or all of the widget to be redrawn, by calling
    gtk_widget_queue_draw() or its variants. GTK+ takes care of most of the
    details by providing a ready-to-use cairo context to the ::draw signal
    handler.</para>

    <para>The following example shows a ::draw signal handler. It is a bit
    more complicated than the previous examples, since it also demonstrates
    input event handling by means of ::button-press and ::motion-notify
    handlers.</para>

    <informalfigure>
      <mediaobject>
        <imageobject>
          <imagedata fileref="drawing.png" format="PNG"/>
        </imageobject>
      </mediaobject>
    </informalfigure>

    <example id="gtk-getting-started-drawing">
      <title>Drawing in response to input</title>
1075
      <para>Create a new file with the following content named example-4.c.</para>
1076
      <programlisting><xi:include href="../../../../examples/drawing.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
1077 1078 1079 1080
    </example>
    <para>
      You can compile the program above with GCC using:
      <literallayout>
1081
        <literal>gcc `pkg-config --cflags gtk+-3.0` -o example-4 example-4.c `pkg-config --libs gtk+-3.0`</literal>
1082 1083 1084 1085
      </literallayout>
    </para>
  </section>

1086
</chapter>