From a1f8ffce4eb5cc023f810b9fe0e1e6749283ca65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20Ils=C3=B8?= Date: Wed, 28 Jan 2015 18:43:45 +0000 Subject: [PATCH] Getting started: BIG update of basics section https://bugzilla.gnome.org/show_bug.cgi?id=743680 --- docs/reference/gtk/getting_started.xml | 84 ++++++++++++++------------ 1 file changed, 45 insertions(+), 39 deletions(-) diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml index 8644ef877a..949b96809a 100644 --- a/docs/reference/gtk/getting_started.xml +++ b/docs/reference/gtk/getting_started.xml @@ -12,7 +12,7 @@ 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. - If you are creating advanced or complex user interfaces it is recommended to + 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. @@ -30,8 +30,8 @@
Basics - To begin our introduction to GTK, we'll start with the simplest - program possible. This program will create an empty 200 × 200 pixel + 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 window. @@ -43,7 +43,7 @@ - Create a new file with the following content named example-0.c. + Create a new file with the following content named example-0.c. FIXME: MISSING XINCLUDE CONTENT @@ -67,36 +67,50 @@ by third party code. The compiler will abort with an error if any other header is directly included. - We then proceed into the main() function of the - application, and we declare a window variable as a pointer - of type #GtkWidget. + 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 called and then + initialized using gtk_application_new(). - The following line will call gtk_init(), which - is the initialization function for GTK+; this function will set up GTK+, - the type system, the connection to the windowing environment, etc. The - gtk_init() takes as arguments the pointers to the command line arguments + When creating a #GtkApplication + you need to pick an application identifier (a name) + and input to gtk_application_new() as parameter. + For this example org.gtk.example is used + but for choosing an identifier for your application see + this guide. + Lastly gtk_application_new() takes a GApplicationFlags as input for your + application, if your application would have special needs. + + + Next the + activate signal + is connected to the activate() function above the main() functions. + The activate 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 counter and string array; this allows GTK+ to parse specific command line arguments that control the behavior of GTK+ itself. The parsed arguments will be removed from the array, leaving the unrecognized ones for your - application to parse. + application to parse. + - For more information on which command line arguments GTK+ - recognizes, please refer to the Running GTK+ - Applications section in this reference. - - The call to gtk_window_new() will create a new #GtkWindow and store - it inside the window variable. The type of the window - is %GTK_WINDOW_TOPLEVEL, which means that the #GtkWindow will be managed - by the windowing system: it will have a frame, a title bar and window - controls, depending on the platform. + Within g_application_run the activate() signal is sent and + we then proceed into the activate() 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 + createa 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 + 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 + But instead of casting window via (GtkWindow*), - window can be cast using the macro + 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 @@ -105,22 +119,14 @@ here. - In order to terminate the application when the #GtkWindow is - destroyed, we connect the #GtkWidget::destroy signal to the gtk_main_quit() - function. This function will terminate the GTK+ main loop started by calling - gtk_main() later. The #GtkWidget::destroy signal is emitted when a widget is - destroyed, either by explicitly calling gtk_widget_destroy() or when the - widget is unparented. Top-level #GtkWindows are also destroyed when - the Close window control button is clicked. + 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(). - #GtkWidgets are hidden by default. By calling gtk_widget_show() - on a #GtkWidget we are asking GTK+ to set the visibility attribute so that it - can be displayed. All this work is done after the main loop has been - started. - - The last line of interest is the call to gtk_main(). This function will - start the GTK+ main loop and will block the control flow of the - main() until the gtk_main_quit() function is called. + 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. While the program is running, GTK+ is receiving events. These are typically input events caused by