[gtk/doc-chapters-markdown: 19/29] docs: Convert getting_started to markdown
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/doc-chapters-markdown: 19/29] docs: Convert getting_started to markdown
- Date: Mon, 25 May 2020 20:14:00 +0000 (UTC)
commit 2595cd5a935ef805af9499f87897ca297a9e6ad3
Author: Matthias Clasen <mclasen redhat com>
Date: Sun May 24 00:22:31 2020 -0400
docs: Convert getting_started to markdown
As part of the conversion, give up on including
sources files from the examples directory, and
instead include the content directly. All include
mechanisms add complications. They were already
complicated with xml, and markdown is not making
things easier.
We already did that for fragments, and if you
make changes to these example sources, you
probably need to revise the surrounding text
anyway.
docs/reference/gtk/getting_started.md | 1737 +++++++++++++++++++++++++++++
docs/reference/gtk/getting_started.xml.in | 1048 -----------------
docs/reference/gtk/gtk4-docs.xml | 2 +-
docs/reference/gtk/meson.build | 2 +-
4 files changed, 1739 insertions(+), 1050 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.md b/docs/reference/gtk/getting_started.md
new file mode 100644
index 0000000000..757b73faaf
--- /dev/null
+++ b/docs/reference/gtk/getting_started.md
@@ -0,0 +1,1737 @@
+# Getting Started with GTK {#gtk-getting-started}
+
+GTK is a [widget toolkit](http://en.wikipedia.org/wiki/Widget_toolkit).
+Each user interface created by GTK consists of widgets. This is implemented
+in C using [GObject](#gobject), an object-oriented framework for C. Widgets
+are organized in a hierarchy. 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. If you are creating complex user
+interfaces it is recommended to 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 [glade](https://glade.gnome.org/).
+
+GTK is event-driven. The toolkit listens for events such as a click
+on a button, and passes the event to your application.
+
+This chapter 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 [Compiling the GTK libraries](#gtk-compiling) section in this
+reference.
+
+## Basics
+
+To begin our introduction to GTK, we'll start with a very simple
+application. This program will create an empty 200 × 200 pixel
+window.
+
+
+
+Create a new file with the following content named `example-0.c`.
+
+``` {.c source=examples/window-default.c }
+#include <gtk/gtk.h>
+
+static void
+activate (GtkApplication* app,
+ gpointer user_data)
+{
+ GtkWidget *window;
+
+ window = gtk_application_window_new (app);
+ gtk_window_set_title (GTK_WINDOW (window), "Window");
+ gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
+ gtk_widget_show (window);
+}
+
+int
+main (int argc,
+ char **argv)
+{
+ GtkApplication *app;
+ int status;
+
+ app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE);
+ g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+ status = g_application_run (G_APPLICATION (app), argc, argv);
+ g_object_unref (app);
+
+ return status;
+}
+```
+
+You can compile the program above with GCC using:
+
+```
+gcc `pkg-config --cflags gtk4` -o example-0 example-0.c `pkg-config --libs gtk4`
+```
+
+For more information on how to compile a GTK application, please
+refer to the [Compiling GTK Applications](#gtk-compiling)
+section in this reference.
+
+All GTK applications will, of course, include `gtk/gtk.h`, which declares
+functions, types and macros required by GTK applications.
+
+Even if GTK installs multiple header files, only the top-level `gtk/gtk.h`
+header can be directly included by third-party code. The compiler will abort
+with an error if any othe header is directly included.
+
+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 `app` is declared and then initialized using gtk_application_new().
+
+When creating a GtkApplication, you need to pick an application identifier
+(a name) and pass it to gtk_application_new() as parameter. For this example
+`org.gtk.example` is used. For choosing an identifier for your application, see
+[this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID). Lastly,
+gtk_application_new() takes GApplicationFlags as input for your application,
+if your application would have special needs.
+
+Next the [activate signal](https://wiki.gnome.org/HowDoI/GtkApplication) is
+connected to the activate() function above the main() function. The `activate`
+signal will be emitted when your application is launched with g_application_run()
+on the line below. The g_application_run() call also takes as arguments the
+command line arguments (the `argc` count and the `argv` string array).
+Your application can override the command line handling, e.g. to open
+files passed on the commandline.
+
+Within g_application_run() the activate signal is sent and we then proceed
+into the activate() function of the application. This is where we construct
+our GTK window, so that a window is shown when the application is launched.
+The call to gtk_application_window_new() will create a new GtkWindow and
+store it inside the `window` pointer. The window will have a frame, a title
+bar, and window controls depending on the platform.
+
+A window title is set using gtk_window_set_title(). This function takes a
+GtkWindow* pointer and a string as input. As our `window` pointer is a
+GtkWidget pointer, we need to cast it to GtkWindow*. But instead of casting
+`window` via `(GtkWindow*)`, `window` can be cast using the macro
+`GTK_WINDOW()`. `GTK_WINDOW()` 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
+[here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).
+
+Finally the window size is set using gtk_window_set_default_size()
+and the window is then shown by GTK via gtk_widget_show().
+
+When you close the window, by for example pressing the X, the g_application_run()
+call returns with a number which is saved inside an integer variable named
+`status`. Afterwards, the GtkApplication object is freed from memory with
+g_object_unref(). Finally the status integer is returned and the application
+exits.
+
+While the program is running, GTK is receiving _events_. 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, _signals_ 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.
+
+The following example is slightly more complex, and tries to
+showcase some of the capabilities of GTK.
+
+## Hello, World
+
+In the long tradition of programming languages and libraries,
+this example is called *Hello, World*.
+
+
+
+### Hello World in C {#gtk-getting-started-hello-world}
+
+Create a new file with the following content named `example-1.c`.
+
+``` {.c source=examples/hello-world.c }
+#include <gtk/gtk.h>
+
+static void
+print_hello (GtkWidget *widget,
+ gpointer data)
+{
+ g_print ("Hello World\n");
+}
+
+static void
+activate (GtkApplication *app,
+ gpointer user_data)
+{
+ GtkWidget *window;
+ GtkWidget *button;
+ GtkWidget *box;
+
+ window = gtk_application_window_new (app);
+ gtk_window_set_title (GTK_WINDOW (window), "Window");
+ gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
+
+ box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+ gtk_window_set_child (GTK_WINDOW (window), box);
+
+ button = gtk_button_new_with_label ("Hello World");
+ g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
+ g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_window_destroy), window);
+ gtk_box_append (GTK_BOX (box), button);
+
+ gtk_widget_show (window);
+}
+
+int
+main (int argc,
+ char **argv)
+{
+ GtkApplication *app;
+ int status;
+
+ app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE);
+ g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+ status = g_application_run (G_APPLICATION (app), argc, argv);
+ g_object_unref (app);
+
+ return status;
+}
+
+```
+
+You can compile the program above with GCC using:
+
+```
+gcc `pkg-config --cflags gtk4` -o example-1 example-1.c `pkg-config --libs gtk4`
+```
+
+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, `button` and `box`. The box
+variable is created to store a GtkBox, which is GTK's way of controlling
+the size and layout of buttons.
+
+The GtkBox is created with gtk_box_new() which takes a GtkOrientation
+enum as parameter. The buttons which this box will contain can either be layed
+out horizontally or vertically. This does not matter in this particular case,
+as we are dealing with only one button. After initializing box with the newly
+created GtkBox, the code adds the box widget to the window widget using
+gtk_window_set_child().
+
+Next the `button` variable is initialized in similar manner.
+gtk_button_new_with_label() is called which returns a GtkButton to be
+stored in `button`. Afterwards `button` is added to our `box`.
+
+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.
+
+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() allows 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_window_destroy() and the `window` 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_window_destroy(), then the function
+would be called on `button` (which would not go well, since the function expects
+a GtkWindow as argument).
+
+More information about creating buttons can be found
+[here](https://wiki.gnome.org/HowDoI/Buttons).
+
+The rest of the code in `example-1.c` is identical to `example-0.c`. The next
+section will elaborate further on how to add several GtkWidgets to your GTK
+application.
+
+## Packing
+
+When creating an application, you'll want to put more than one widget inside
+a window. When you do so, it becomes important to control how each widget is
+positioned and sized. This is where packing comes in.
+
+GTK comes with a large variety of _layout containers_ whose purpose it
+is to control the layout of the child widgets that are added to them.
+See [Layout containers](#LayoutContainers) for an overview.
+
+The following example shows how the GtkGrid container lets you
+arrange several buttons:
+
+
+
+### Packing buttons {#gtk-getting-started-grid-packing}
+
+Create a new file with the following content named `example-2.c`.
+
+``` {.c source=examples/grid-packing.c }
+#include <gtk/gtk.h>
+
+static void
+print_hello (GtkWidget *widget,
+ gpointer data)
+{
+ g_print ("Hello World\n");
+}
+
+static void
+activate (GtkApplication *app,
+ gpointer user_data)
+{
+ GtkWidget *window;
+ GtkWidget *grid;
+ GtkWidget *button;
+
+ /* create a new window, and set its title */
+ window = gtk_application_window_new (app);
+ gtk_window_set_title (GTK_WINDOW (window), "Window");
+
+ /* Here we construct the container that is going pack our buttons */
+ grid = gtk_grid_new ();
+
+ /* Pack the container in the window */
+ gtk_window_set_child (GTK_WINDOW (window), grid);
+
+ button = gtk_button_new_with_label ("Button 1");
+ g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
+
+ /* Place the first button in the grid cell (0, 0), and make it fill
+ * just 1 cell horizontally and vertically (ie no spanning)
+ */
+ gtk_grid_attach (GTK_GRID (grid), button, 0, 0, 1, 1);
+
+ button = gtk_button_new_with_label ("Button 2");
+ g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
+
+ /* Place the second button in the grid cell (1, 0), and make it fill
+ * just 1 cell horizontally and vertically (ie no spanning)
+ */
+ gtk_grid_attach (GTK_GRID (grid), button, 1, 0, 1, 1);
+
+ button = gtk_button_new_with_label ("Quit");
+ g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_window_destroy), window);
+
+ /* Place the Quit button in the grid cell (0, 1), and make it
+ * span 2 columns.
+ */
+ gtk_grid_attach (GTK_GRID (grid), button, 0, 1, 2, 1);
+
+ gtk_widget_show (window);
+
+}
+
+int
+main (int argc,
+ char **argv)
+{
+ GtkApplication *app;
+ int status;
+
+ app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE);
+ g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+ status = g_application_run (G_APPLICATION (app), argc, argv);
+ g_object_unref (app);
+
+ return status;
+}
+```
+
+You can compile the program above with GCC using:
+
+```
+gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4`
+```
+
+## Custom Drawing
+
+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 ::draw signal.
+
+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
+when the window containing it is resized. It is also possible to explicitly
+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.
+
+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 event controllers.
+
+
+
+### Drawing in response to input {#gtk-getting-started-drawing}
+
+Create a new file with the following content named `example-4.c`.
+
+``` {.c source=examples/drawing.c }
+#include <gtk/gtk.h>
+
+/* Surface to store current scribbles */
+static cairo_surface_t *surface = NULL;
+
+static void
+clear_surface (void)
+{
+ cairo_t *cr;
+
+ cr = cairo_create (surface);
+
+ cairo_set_source_rgb (cr, 1, 1, 1);
+ cairo_paint (cr);
+
+ cairo_destroy (cr);
+}
+
+/* Create a new surface of the appropriate size to store our scribbles */
+static void
+resize_cb (GtkWidget *widget,
+ int width,
+ int height,
+ gpointer data)
+{
+ if (surface)
+ {
+ cairo_surface_destroy (surface);
+ surface = NULL;
+ }
+
+ if (gtk_native_get_surface (gtk_widget_get_native (widget)))
+ {
+ surface = gdk_surface_create_similar_surface (gtk_native_get_surface (gtk_widget_get_native (widget)),
+ CAIRO_CONTENT_COLOR,
+ gtk_widget_get_width (widget),
+ gtk_widget_get_height (widget));
+
+ /* Initialize the surface to white */
+ clear_surface ();
+ }
+}
+
+/* Redraw the screen from the surface. Note that the draw
+ * callback receives a ready-to-be-used cairo_t that is already
+ * clipped to only draw the exposed areas of the widget
+ */
+static void
+draw_cb (GtkDrawingArea *drawing_area,
+ cairo_t *cr,
+ int width,
+ int height,
+ gpointer data)
+{
+ cairo_set_source_surface (cr, surface, 0, 0);
+ cairo_paint (cr);
+}
+
+/* Draw a rectangle on the surface at the given position */
+static void
+draw_brush (GtkWidget *widget,
+ gdouble x,
+ gdouble y)
+{
+ cairo_t *cr;
+
+ /* Paint to the surface, where we store our state */
+ cr = cairo_create (surface);
+
+ cairo_rectangle (cr, x - 3, y - 3, 6, 6);
+ cairo_fill (cr);
+
+ cairo_destroy (cr);
+
+ /* Now invalidate the drawing area. */
+ gtk_widget_queue_draw (widget);
+}
+
+static double start_x;
+static double start_y;
+
+static void
+drag_begin (GtkGestureDrag *gesture,
+ double x,
+ double y,
+ GtkWidget *area)
+{
+ start_x = x;
+ start_y = y;
+
+ draw_brush (area, x, y);
+}
+
+static void
+drag_update (GtkGestureDrag *gesture,
+ double x,
+ double y,
+ GtkWidget *area)
+{
+ draw_brush (area, start_x + x, start_y + y);
+}
+
+static void
+drag_end (GtkGestureDrag *gesture,
+ double x,
+ double y,
+ GtkWidget *area)
+{
+ draw_brush (area, start_x + x, start_y + y);
+}
+
+static void
+pressed (GtkGestureClick *gesture,
+ int n_press,
+ double x,
+ double y,
+ GtkWidget *area)
+{
+ clear_surface ();
+ gtk_widget_queue_draw (area);
+}
+
+static void
+close_window (void)
+{
+ if (surface)
+ cairo_surface_destroy (surface);
+}
+
+static void
+activate (GtkApplication *app,
+ gpointer user_data)
+{
+ GtkWidget *window;
+ GtkWidget *frame;
+ GtkWidget *drawing_area;
+ GtkGesture *drag;
+ GtkGesture *press;
+
+ window = gtk_application_window_new (app);
+ gtk_window_set_title (GTK_WINDOW (window), "Drawing Area");
+
+ g_signal_connect (window, "destroy", G_CALLBACK (close_window), NULL);
+
+ frame = gtk_frame_new (NULL);
+ gtk_window_set_child (GTK_WINDOW (window), frame);
+
+ drawing_area = gtk_drawing_area_new ();
+ /* set a minimum size */
+ gtk_widget_set_size_request (drawing_area, 100, 100);
+
+ gtk_frame_set_child (GTK_FRAME (frame), drawing_area);
+
+ gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (drawing_area), draw_cb, NULL, NULL);
+
+ g_signal_connect_after (drawing_area, "resize", G_CALLBACK (resize_cb), NULL);
+
+ drag = gtk_gesture_drag_new ();
+ gtk_gesture_single_set_button (GTK_GESTURE_SINGLE (drag), GDK_BUTTON_PRIMARY);
+ gtk_widget_add_controller (drawing_area, GTK_EVENT_CONTROLLER (drag));
+ g_signal_connect (drag, "drag-begin", G_CALLBACK (drag_begin), drawing_area);
+ g_signal_connect (drag, "drag-update", G_CALLBACK (drag_update), drawing_area);
+ g_signal_connect (drag, "drag-end", G_CALLBACK (drag_end), drawing_area);
+
+ press = gtk_gesture_click_new ();
+ gtk_gesture_single_set_button (GTK_GESTURE_SINGLE (press), GDK_BUTTON_SECONDARY);
+ gtk_widget_add_controller (drawing_area, GTK_EVENT_CONTROLLER (press));
+
+ g_signal_connect (press, "pressed", G_CALLBACK (pressed), drawing_area);
+
+ gtk_widget_show (window);
+}
+
+int
+main (int argc,
+ char **argv)
+{
+ GtkApplication *app;
+ int status;
+
+ app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE);
+ g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+ status = g_application_run (G_APPLICATION (app), argc, argv);
+ g_object_unref (app);
+
+ return status;
+}
+```
+
+You can compile the program above with GCC using:
+
+```
+gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`
+```
+
+## Building user interfaces
+
+When constructing a more complicated user interface, with dozens
+or hundreds of widgets, doing all the setup work in C code is
+cumbersome, and making changes becomes next to impossible.
+
+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>
+
+### Packing buttons with GtkBuilder
+
+Create a new file with the following content named `example-3.c`.
+
+``` {.c source=examples/builder.c }
+#include <gtk/gtk.h>
+#include <glib/gstdio.h>
+
+static void
+print_hello (GtkWidget *widget,
+ gpointer data)
+{
+ g_print ("Hello World\n");
+}
+
+static void
+quit_cb (GtkWidget *widget, gpointer data)
+{
+ gboolean *done = data;
+
+ *done = TRUE;
+
+ g_main_context_wakeup (NULL);
+}
+
+int
+main (int argc,
+ char *argv[])
+{
+ GtkBuilder *builder;
+ GObject *window;
+ GObject *button;
+ gboolean done = FALSE;
+
+#ifdef GTK_SRCDIR
+ g_chdir (GTK_SRCDIR);
+#endif
+
+ gtk_init ();
+
+ /* Construct a GtkBuilder instance and load our UI description */
+ builder = gtk_builder_new ();
+ gtk_builder_add_from_file (builder, "builder.ui", NULL);
+
+ /* Connect signal handlers to the constructed widgets. */
+ window = gtk_builder_get_object (builder, "window");
+ g_signal_connect (window, "destroy", G_CALLBACK (quit_cb), &done);
+
+ button = gtk_builder_get_object (builder, "button1");
+ g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
+
+ button = gtk_builder_get_object (builder, "button2");
+ g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);
+
+ button = gtk_builder_get_object (builder, "quit");
+ g_signal_connect (button, "clicked", G_CALLBACK (quit_cb), &done);
+
+ gtk_widget_show (GTK_WIDGET (window));
+
+ while (!done)
+ g_main_context_iteration (NULL, TRUE);
+
+ return 0;
+}
+```
+
+Create a new file with the following content named `builder.ui`.
+
+``` {.xml source=examples/builder.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <object id="window" class="GtkWindow">
+ <property name="title">Grid</property>
+ <child>
+ <object id="grid" class="GtkGrid">
+ <child>
+ <object id="button1" class="GtkButton">
+ <property name="label">Button 1</property>
+ <layout>
+ <property name="left-attach">0</property>
+ <property name="top-attach">0</property>
+ </layout>
+ </object>
+ </child>
+ <child>
+ <object id="button2" class="GtkButton">
+ <property name="label">Button 2</property>
+ <layout>
+ <property name="left-attach">1</property>
+ <property name="top-attach">0</property>
+ </layout>
+ </object>
+ </child>
+ <child>
+ <object id="quit" class="GtkButton">
+ <property name="label">Quit</property>
+ <layout>
+ <property name="left-attach">0</property>
+ <property name="top-attach">1</property>
+ <property name="column-span">2</property>
+ </layout>
+ </object>
+ </child>
+ </object>
+ </child>
+ </object>
+</interface>
+```
+
+You can compile the program above with GCC using:
+
+```
+gcc `pkg-config --cflags gtk4` -o example-3 example-3.c `pkg-config --libs gtk4`
+```
+
+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*.
+
+Normally, you would pass a full path to gtk_builder_add_from_file() to
+make the execution of your program independent of the current directory.
+A common location to install UI descriptions and similar data is
+`/usr/share/appname`.
+
+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 [glade](http://glade.gnome.org)
+can load the file and allow you to create and modify your UI by point-and-click.
+
+## Building applications
+
+An application consists of a number of files:
+
+The binary
+ : This gets installed in `/usr/bin`.
+A desktop file
+ : 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 `/usr/share/applications`.
+An icon
+ : The icon gets installed in `/usr/share/icons/hicolor/48x48/apps`, where it
+will be found regardless of the current theme.
+A settings schema
+ : If the application uses GSettings, it will install its schema in
+ `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it.
+Other resources
+ : 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 `/usr/share`.
+
+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.
+
+The full, buildable sources for these examples can be found in the `examples/`
+directory of the GTK source distribution, or
+[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples in the GTK git
+repository. You can build each example separately by using make with the
+`Makefile.example` file. For more information, see the `README` included in the
+examples directory.
+
+### A trivial application
+
+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.
+
+``` {.c source=examples/application1/main.c }
+#include <gtk/gtk.h>
+
+#include "exampleapp.h"
+
+int
+main (int argc, char *argv[])
+{
+ return g_application_run (G_APPLICATION (example_app_new ()), argc, argv);
+}
+```
+
+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.
+
+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.
+
+To learn more about GApplication entry points, consult the GIO
+[documentation](https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description).
+
+``` {.c source=examples/application1/exampleapp.c }
+#include <gtk/gtk.h>
+
+#include "exampleapp.h"
+#include "exampleappwin.h"
+
+struct _ExampleApp
+{
+ GtkApplication parent;
+};
+
+G_DEFINE_TYPE(ExampleApp, example_app, GTK_TYPE_APPLICATION);
+
+static void
+example_app_init (ExampleApp *app)
+{
+}
+
+static void
+example_app_activate (GApplication *app)
+{
+ ExampleAppWindow *win;
+
+ win = example_app_window_new (EXAMPLE_APP (app));
+ gtk_window_present (GTK_WINDOW (win));
+}
+
+static void
+example_app_open (GApplication *app,
+ GFile **files,
+ gint n_files,
+ const gchar *hint)
+{
+ GList *windows;
+ ExampleAppWindow *win;
+ int i;
+
+ windows = gtk_application_get_windows (GTK_APPLICATION (app));
+ if (windows)
+ win = EXAMPLE_APP_WINDOW (windows->data);
+ else
+ win = example_app_window_new (EXAMPLE_APP (app));
+
+ for (i = 0; i < n_files; i++)
+ example_app_window_open (win, files[i]);
+
+ gtk_window_present (GTK_WINDOW (win));
+}
+
+static void
+example_app_class_init (ExampleAppClass *class)
+{
+ G_APPLICATION_CLASS (class)->activate = example_app_activate;
+ G_APPLICATION_CLASS (class)->open = example_app_open;
+}
+
+ExampleApp *
+example_app_new (void)
+{
+ return g_object_new (EXAMPLE_APP_TYPE,
+ "application-id", "org.gtk.exampleapp",
+ "flags", G_APPLICATION_HANDLES_OPEN,
+ NULL);
+}
+```
+
+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.
+
+``` {.c source=examples/application1/examplewin.c }
+#include <gtk/gtk.h>
+
+#include "exampleapp.h"
+#include "exampleappwin.h"
+
+struct _ExampleAppWindow
+{
+ GtkApplicationWindow parent;
+};
+
+G_DEFINE_TYPE(ExampleAppWindow, example_app_window, GTK_TYPE_APPLICATION_WINDOW);
+
+static void
+example_app_window_init (ExampleAppWindow *app)
+{
+}
+
+static void
+example_app_window_class_init (ExampleAppWindowClass *class)
+{
+}
+
+ExampleAppWindow *
+example_app_window_new (ExampleApp *app)
+{
+ return g_object_new (EXAMPLE_APP_WINDOW_TYPE, "application", app, NULL);
+}
+
+void
+example_app_window_open (ExampleAppWindow *win,
+ GFile *file)
+{
+}
+```
+
+As part of the initial setup of our application, we also
+create an icon and a desktop file.
+
+
+
+``` { source=examples/application1/org.gtk.exampleapp.desktop }
+[Desktop Entry]
+Type=Application
+Name=Example
+Icon=exampleapp
+StartupNotify=true
+Exec=@bindir@/exampleapp
+```
+
+Note that `@bindir@` needs to be replaced with the actual path to the binary
+before this desktop file can be used.
+
+Here is what we've achieved so far:
+
+
+
+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.
+
+### Populating the window
+
+In this step, we use a GtkBuilder template to associate a
+GtkBuilder ui file with our application window class.
+
+Our simple ui file gives the window a title, and puts a GtkStack
+widget as the main content.
+
+``` { .xml source=examples/application2/window.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <template class="ExampleAppWindow" parent="GtkApplicationWindow">
+ <property name="title" translatable="yes">Example Application</property>
+ <property name="default-width">600</property>
+ <property name="default-height">400</property>
+ <child>
+ <object class="GtkBox" id="content_box">
+ <property name="orientation">vertical</property>
+ <child>
+ <object class="GtkStack" id="stack"/>
+ </child>
+ </object>
+ </child>
+ </template>
+</interface>
+```
+
+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.
+
+```
+ ...
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+ gtk_widget_init_template (GTK_WIDGET (win));
+}
+
+static void
+example_app_window_class_init (ExampleAppWindowClass *class)
+{
+ gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
+ "/org/gtk/exampleapp/window.ui");
+}
+
+ ...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application2/exampleappwin.c))
+
+You may have noticed that we used the `_from_resource()` variant of the function
+that sets a template. Now we need to use
+[GLib's resource functionality](https://developer.gnome.org/gio/stable/GResource.html)
+to include the ui file in the binary. This is commonly done by listing all resources
+in a `.gresource.xml` file, such as this:
+
+``` { .xml source=examples/application2/exampleapp.gresource.xml }
+<?xml version="1.0" encoding="UTF-8"?>
+<gresources>
+ <gresource prefix="/org/gtk/exampleapp">
+ <file preprocess="xml-stripblanks">window.ui</file>
+ </gresource>
+</gresources>
+```
+
+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:
+
+```
+glib-compile-resources exampleapp.gresource.xml --target=resources.c --generate-source
+```
+
+Our application now looks like this:
+
+
+
+### Opening files
+
+In this step, we make our application show the content of all the files
+that it is given on the commandline.
+
+To this end, we add a member to the struct of our application window subclass
+and keep a reference to the GtkStack there. The first member of the struct
+should be the parent type from which the class is derived. Here,
+ExampleAppWindow is derived from GtkApplicationWindow. The
+gtk_widget_class_bind_template_child() function arranges things so that after
+instantiating the template, the `stack` member of the struct will point to the
+widget of the same name from the template.
+
+```
+...
+
+struct _ExampleAppWindow
+{
+ GtkApplicationWindow parent;
+
+ GtkWidget *stack;
+};
+
+G_DEFINE_TYPE (ExampleAppWindow, example_app_window, GTK_TYPE_APPLICATION_WINDOW)
+
+...
+
+static void
+example_app_window_class_init (ExampleAppWindowClass *class)
+{
+ gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
+ "/org/gtk/exampleapp/window.ui");
+ gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), ExampleAppWindow, stack);
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))
+
+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:
+
+```
+...
+
+void
+example_app_window_open (ExampleAppWindow *win,
+ GFile *file)
+{
+ char *basename;
+ GtkWidget *scrolled, *view;
+ char *contents;
+ gsize length;
+
+ basename = g_file_get_basename (file);
+
+ scrolled = gtk_scrolled_window_new (NULL, NULL);
+ gtk_widget_set_hexpand (scrolled, TRUE);
+ gtk_widget_set_vexpand (scrolled, TRUE);
+ view = gtk_text_view_new ();
+ gtk_text_view_set_editable (GTK_TEXT_VIEW (view), FALSE);
+ gtk_text_view_set_cursor_visible (GTK_TEXT_VIEW (view), FALSE);
+ gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (scrolled), view);
+ gtk_stack_add_titled (GTK_STACK (win->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);
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))
+
+Lastly, we add a GtkStackSwitcher to the titlebar area in the ui file, and we
+tell it to display information about our stack.
+
+The stack switcher gets all its information it needs to display tabs from
+the stack that it belongs to. Here, we are passing the label to show for
+each file as the last argument to the gtk_stack_add_titled() function.
+
+Our application is beginning to take shape:
+
+
+
+### A menu
+
+The menu is shown at the right side of the headerbar. It is meant to collect
+infrequently used actions that affect the whole application.
+
+Just like the window template, we specify our menu in a ui file, and add it
+as a resource to our binary.
+
+``` {.xml source=examples/application4/gears-menu.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <menu id="menu">
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Preferences</attribute>
+ <attribute name="action">app.preferences</attribute>
+ </item>
+ </section>
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Quit</attribute>
+ <attribute name="action">app.quit</attribute>
+ </item>
+ </section>
+ </menu>
+</interface>
+```
+
+To make the menu appear, we have to load the ui file and associate the
+resulting menu model with the menu button that we've added to the headerbar.
+Since menus work by activating GActions, we also have to add a suitable set
+of actions to our application.
+
+Adding the actions is best done in the startup() vfunc, which is guaranteed
+to be called once for each primary application instance:
+
+```
+...
+
+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));
+}
+
+static GActionEntry app_entries[] =
+{
+ { "preferences", preferences_activated, NULL, NULL, NULL },
+ { "quit", quit_activated, NULL, NULL, NULL }
+};
+
+static void
+example_app_startup (GApplication *app)
+{
+ GtkBuilder *builder;
+ GMenuModel *app_menu;
+ const gchar *quit_accels[2] = { "<Ctrl>Q", NULL };
+
+ G_APPLICATION_CLASS (example_app_parent_class)->startup (app);
+
+ g_action_map_add_action_entries (G_ACTION_MAP (app),
+ app_entries, G_N_ELEMENTS (app_entries),
+ app);
+ gtk_application_set_accels_for_action (GTK_APPLICATION (app),
+ "app.quit",
+ quit_accels);
+}
+
+static void
+example_app_class_init (ExampleAppClass *class)
+{
+ G_APPLICATION_CLASS (class)->startup = example_app_startup;
+ ...
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application4/exampleapp.c))
+
+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 shortcut was added with gtk_application_set_accels_for_action().
+
+The application menu looks like this:
+
+
+
+### A preference dialog
+
+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.
+
+We are going to use GSettings to store our preferences. GSettings requires
+a schema that describes our settings:
+
+``` {.xml source=examples/application5/org.gtk.exampleapp.gschema.xml }
+<?xml version="1.0" encoding="UTF-8"?>
+<schemalist>
+ <schema path="/org/gtk/exampleapp/" id="org.gtk.exampleapp">
+ <key name="font" type="s">
+ <default>'Monospace 12'</default>
+ <summary>Font</summary>
+ <description>The font to be used for content.</description>
+ </key>
+ <key name="transition" type="s">
+ <choices>
+ <choice value='none'/>
+ <choice value='crossfade'/>
+ <choice value='slide-left-right'/>
+ </choices>
+ <default>'none'</default>
+ <summary>Transition</summary>
+ <description>The transition to use when switching tabs.</description>
+ </key>
+ </schema>
+</schemalist>
+```
+
+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
+[macros](https://developer.gnome.org/gio/2.36/ch31s06.html) to do this in
+autotools-based projects.
+
+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.
+
+```
+...
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+ gtk_widget_init_template (GTK_WIDGET (win));
+ win->settings = g_settings_new ("org.gtk.exampleapp");
+
+ g_settings_bind (win->settings, "transition",
+ win->stack, "transition-type",
+ G_SETTINGS_BIND_DEFAULT);
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application5/exampleappwin.c))
+
+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.
+
+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.
+
+Lets start with the template.
+
+``` {.xml source=examples/application6/prefs.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <template class="ExampleAppPrefs" parent="GtkDialog">
+ <property name="title" translatable="yes">Preferences</property>
+ <property name="resizable">0</property>
+ <property name="modal">1</property>
+ <child internal-child="content_area">
+ <object class="GtkBox" id="content_area">
+ <child>
+ <object class="GtkGrid" id="grid">
+ <property name="margin-start">12</property>
+ <property name="margin-end">12</property>
+ <property name="margin-top">12</property>
+ <property name="margin-bottom">12</property>
+ <property name="row-spacing">12</property>
+ <property name="column-spacing">12</property>
+ <child>
+ <object class="GtkLabel" id="fontlabel">
+ <property name="label">_Font:</property>
+ <property name="use-underline">1</property>
+ <property name="mnemonic-widget">font</property>
+ <property name="xalign">1</property>
+ <layout>
+ <property name="left-attach">0</property>
+ <property name="top-attach">0</property>
+ </layout>
+ </object>
+ </child>
+ <child>
+ <object class="GtkFontButton" id="font">
+ <layout>
+ <property name="left-attach">1</property>
+ <property name="top-attach">0</property>
+ </layout>
+ </object>
+ </child>
+ <child>
+ <object class="GtkLabel" id="transitionlabel">
+ <property name="label">_Transition:</property>
+ <property name="use-underline">1</property>
+ <property name="mnemonic-widget">transition</property>
+ <property name="xalign">1</property>
+ <layout>
+ <property name="left-attach">0</property>
+ <property name="top-attach">1</property>
+ </layout>
+ </object>
+ </child>
+ <child>
+ <object class="GtkComboBoxText" id="transition">
+ <items>
+ <item translatable="yes" id="none">None</item>
+ <item translatable="yes" id="crossfade">Fade</item>
+ <item translatable="yes" id="slide-left-right">Slide</item>
+ </items>
+ <layout>
+ <property name="left-attach">1</property>
+ <property name="top-attach">1</property>
+ </layout>
+ </object>
+ </child>
+ </object>
+ </child>
+ </object>
+ </child>
+ </template>
+</interface>
+```
+
+Next comes the dialog subclass.
+
+``` {.c source=examples/application6/exampleappprefs.c }
+#include <gtk/gtk.h>
+
+#include "exampleapp.h"
+#include "exampleappwin.h"
+#include "exampleappprefs.h"
+
+struct _ExampleAppPrefs
+{
+ GtkDialog parent;
+
+ GSettings *settings;
+ GtkWidget *font;
+ GtkWidget *transition;
+};
+
+G_DEFINE_TYPE (ExampleAppPrefs, example_app_prefs, GTK_TYPE_DIALOG)
+
+static void
+example_app_prefs_init (ExampleAppPrefs *prefs)
+{
+ gtk_widget_init_template (GTK_WIDGET (prefs));
+ prefs->settings = g_settings_new ("org.gtk.exampleapp");
+
+ g_settings_bind (prefs->settings, "font",
+ prefs->font, "font",
+ G_SETTINGS_BIND_DEFAULT);
+ g_settings_bind (prefs->settings, "transition",
+ prefs->transition, "active-id",
+ G_SETTINGS_BIND_DEFAULT);
+}
+
+static void
+example_app_prefs_dispose (GObject *object)
+{
+ ExampleAppPrefs *prefs;
+
+ prefs = EXAMPLE_APP_PREFS (object);
+
+ g_clear_object (&prefs->settings);
+
+ G_OBJECT_CLASS (example_app_prefs_parent_class)->dispose (object);
+}
+
+static void
+example_app_prefs_class_init (ExampleAppPrefsClass *class)
+{
+ G_OBJECT_CLASS (class)->dispose = example_app_prefs_dispose;
+
+ gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (class),
+ "/org/gtk/exampleapp/prefs.ui");
+ gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), ExampleAppPrefs, font);
+ gtk_widget_class_bind_template_child (GTK_WIDGET_CLASS (class), ExampleAppPrefs, transition);
+}
+
+ExampleAppPrefs *
+example_app_prefs_new (ExampleAppWindow *win)
+{
+ return g_object_new (EXAMPLE_APP_PREFS_TYPE, "transient-for", win, "use-header-bar", TRUE, NULL);
+}
+```
+
+Now we revisit the `preferences_activated()` function in our application
+class, and make it open a new preference dialog.
+
+```
+...
+
+static void
+preferences_activated (GSimpleAction *action,
+ GVariant *parameter,
+ gpointer app)
+{
+ ExampleAppPrefs *prefs;
+ GtkWindow *win;
+
+ win = gtk_application_get_active_window (GTK_APPLICATION (app));
+ prefs = example_app_prefs_new (EXAMPLE_APP_WINDOW (win));
+ gtk_window_present (GTK_WINDOW (prefs));
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application6/exampleapp.c))
+
+After all this work, our application can now show a preference dialog
+like this:
+
+
+
+### Adding a search bar
+
+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.
+
+We add a toggle button to the header bar, which can be used to slide out
+the search bar below the header bar.
+
+``` {.xml source=examples/application7/window.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <template class="ExampleAppWindow" parent="GtkApplicationWindow">
+ <property name="title" translatable="yes">Example Application</property>
+ <property name="default-width">600</property>
+ <property name="default-height">400</property>
+ <child type="titlebar">
+ <object class="GtkHeaderBar" id="header">
+ <property name="show-title-buttons">1</property>
+ <child type="title">
+ <object class="GtkStackSwitcher" id="tabs">
+ <property name="stack">stack</property>
+ </object>
+ </child>
+ <child type="end">
+ <object class="GtkMenuButton" id="gears">
+ <property name="direction">none</property>
+ </object>
+ </child>
+ <child type="end">
+ <object class="GtkToggleButton" id="search">
+ <property name="sensitive">0</property>
+ <property name="icon-name">edit-find-symbolic</property>
+ </object>
+ </child>
+ </object>
+ </child>
+ <child>
+ <object class="GtkBox" id="content_box">
+ <property name="orientation">vertical</property>
+ <child>
+ <object class="GtkSearchBar" id="searchbar">
+ <child>
+ <object class="GtkSearchEntry" id="searchentry">
+ <signal name="search-changed" handler="search_text_changed"/>
+ </object>
+ </child>
+ </object>
+ </child>
+ <child>
+ <object class="GtkStack" id="stack">
+ <signal name="notify::visible-child" handler="visible_child_changed"/>
+ </object>
+ </child>
+ </object>
+ </child>
+ </template>
+</interface>
+```
+
+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.
+
+```
+...
+
+static void
+search_text_changed (GtkEntry *entry,
+ ExampleAppWindow *win)
+{
+ const gchar *text;
+ GtkWidget *tab;
+ GtkWidget *view;
+ GtkTextBuffer *buffer;
+ GtkTextIter start, match_start, match_end;
+
+ text = gtk_editable_get_text (GTK_EDITABLE (entry));
+
+ if (text[0] == '\0')
+ return;
+
+ tab = gtk_stack_get_visible_child (GTK_STACK (win->stack));
+ view = gtk_scrolled_window_get_child (GTK_SCROLLED_WINDOW (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);
+ }
+}
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+
+...
+
+ gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (class), search_text_changed);
+
+...
+
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application7/exampleappwin.c))
+
+With the search bar, our application now looks like this:
+
+
+
+### Adding a side bar
+
+As another piece of functionality, we are adding a sidebar, which demonstrates
+GtkMenuButton, GtkRevealer and GtkListBox.
+
+``` {.xml source=examples/application8/window.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <template class="ExampleAppWindow" parent="GtkApplicationWindow">
+ <property name="title" translatable="yes">Example Application</property>
+ <property name="default-width">600</property>
+ <property name="default-height">400</property>
+ <child type="titlebar">
+ <object class="GtkHeaderBar" id="header">
+ <property name="show-title-buttons">1</property>
+ <child type="title">
+ <object class="GtkStackSwitcher" id="tabs">
+ <property name="stack">stack</property>
+ </object>
+ </child>
+ <child type="end">
+ <object class="GtkToggleButton" id="search">
+ <property name="sensitive">0</property>
+ <property name="icon-name">edit-find-symbolic</property>
+ </object>
+ </child>
+ <child type="end">
+ <object class="GtkMenuButton" id="gears">
+ <property name="direction">none</property>
+ </object>
+ </child>
+ </object>
+ </child>
+ <child>
+ <object class="GtkBox" id="content_box">
+ <property name="orientation">vertical</property>
+ <child>
+ <object class="GtkSearchBar" id="searchbar">
+ <child>
+ <object class="GtkSearchEntry" id="searchentry">
+ <signal name="search-changed" handler="search_text_changed"/>
+ </object>
+ </child>
+ </object>
+ </child>
+ <child>
+ <object class="GtkBox" id="hbox">
+ <child>
+ <object class="GtkRevealer" id="sidebar">
+ <property name="transition-type">slide-right</property>
+ <child>
+ <object class="GtkScrolledWindow" id="sidebar-sw">
+ <property name="hscrollbar-policy">never</property>
+ <child>
+ <object class="GtkListBox" id="words">
+ <property name="selection-mode">none</property>
+ </object>
+ </child>
+ </object>
+ </child>
+ </object>
+ </child>
+ <child>
+ <object class="GtkStack" id="stack">
+ <signal name="notify::visible-child" handler="visible_child_changed"/>
+ </object>
+ </child>
+ </object>
+ </child>
+ </object>
+ </child>
+ </template>
+</interface>
+```
+
+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 a checkbutton for the new feature to the menu.
+
+``` {.xml source=examples/application8/gears-menu.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <menu id="menu">
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Words</attribute>
+ <attribute name="action">win.show-words</attribute>
+ </item>
+ <item>
+ <attribute name="label" translatable="yes">_Preferences</attribute>
+ <attribute name="action">app.preferences</attribute>
+ </item>
+ </section>
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Quit</attribute>
+ <attribute name="action">app.quit</attribute>
+ </item>
+ </section>
+ </menu>
+</interface>
+```
+
+To connect the menuitem to the show-words setting, we use
+a GAction corresponding to the given GSettings key.
+
+```
+...
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+
+...
+
+ 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);
+
+ action = g_settings_create_action (priv->settings, "show-words");
+ g_action_map_add_action (G_ACTION_MAP (win), action);
+ g_object_unref (action);
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application8/exampleappwin.c))
+
+What our application looks like now:
+
+
+
+### Properties
+
+Widgets and other objects have many useful properties.
+
+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.
+
+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.
+
+We add a new "Lines" menu item to the gears menu, which triggers the
+show-lines action:
+
+``` {.xml source=examples/application9/gears-menu.ui }
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+ <menu id="menu">
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Words</attribute>
+ <attribute name="action">win.show-words</attribute>
+ </item>
+ <item>
+ <attribute name="label" translatable="yes">_Lines</attribute>
+ <attribute name="action">win.show-lines</attribute>
+ </item>
+ <item>
+ <attribute name="label" translatable="yes">_Preferences</attribute>
+ <attribute name="action">app.preferences</attribute>
+ </item>
+ </section>
+ <section>
+ <item>
+ <attribute name="label" translatable="yes">_Quit</attribute>
+ <attribute name="action">app.quit</attribute>
+ </item>
+ </section>
+ </menu>
+</interface>
+```
+
+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.
+
+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.
+
+```
+...
+
+static void
+example_app_window_init (ExampleAppWindow *win)
+{
+ ...
+
+ action = (GAction*) g_property_action_new ("show-lines", win->lines, "visible");
+ g_action_map_add_action (G_ACTION_MAP (win), action);
+ g_object_unref (action);
+
+ g_object_bind_property (win->lines, "visible",
+ win->lines_label, "visible",
+ G_BINDING_DEFAULT);
+}
+
+...
+```
+([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application9/exampleappwin.c))
+
+We also need a function that counts the lines of the currently active tab,
+and updates the `lines` label. See the [full
source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application9/exampleappwin.c)
+if you are interested in the details.
+
+This brings our example application to this appearance:
+
+
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 18dd293336..1d13375288 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -21,7 +21,7 @@
<part id="gtk">
<title>Introduction</title>
<xi:include href="overview.xml"/>
- <xi:include href="xml/getting_started.xml"/>
+ <xi:include href="getting_started.xml"/>
<xi:include href="resources.xml" />
<xi:include href="xml/question_index.xml" />
</part>
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index dadb199297..c3535b1e21 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -373,6 +373,7 @@ expand_content_files = [
]
expand_content_md_files = [
+ 'getting_started.md',
'building.md',
'compiling.md',
'running.md',
@@ -400,7 +401,6 @@ endif
if get_option('gtk_doc')
configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf)
- configure_file(input: 'getting_started.xml.in', output: 'getting_started.xml', configuration: src_dir_conf)
# gtk-markdown-to-docbook uses pandoc
pandoc = find_program('pandoc', required: true)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
