From ce1244fdd74d736e81cb12653fdc956146d03ffc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 18 Jan 2011 21:42:29 -0500 Subject: [PATCH] Add a paragraph explaining events and signals --- docs/reference/gtk/getting_started.xml | 185 +++++++++++++------------ 1 file changed, 98 insertions(+), 87 deletions(-) diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml index 6a021fa870..3698aa5e90 100644 --- a/docs/reference/gtk/getting_started.xml +++ b/docs/reference/gtk/getting_started.xml @@ -12,97 +12,108 @@ Compiling the GTK+ libraries section in this reference. - To begin our introduction to GTK, we'll start with the simplest - program possible. This program will create an empty 200x200 pixel - window: +
+ Basics - - - + To begin our introduction to GTK, we'll start with the simplest + program possible. This program will create an empty 200x200 pixel + window: - - - FIXME: MISSING XINCLUDE CONTENT - - + + + - You can compile the program above with GCC using: - - - gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0` - - - For more information on how to compile a GTK+ application, please - refer to the Compiling GTK+ Applications - 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 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. - - The following line will call gtk_init(), which - is the initialization function for GTK+; this function will set up GTK+, - the type system, the connection to the windowing environment, etc. The - gtk_init() takes as arguments the pointers to the command line arguments - counter and string array; this allows GTK+ to parse specific command line - arguments that control the behavior of GTK+ itself. The parsed arguments - will be removed from the array, leaving the unrecognized ones for your - application to parse. - - 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. - - 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. - - #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. - - The following example is slightly more complex, and tries to - showcase some of the capabilities of GTK+. - - In the long tradition of programming languages and libraries, - it is called Hello, World. - - - - - - - Hello World in GTK+ - - + + FIXME: MISSING XINCLUDE CONTENT - - + + + You can compile the program above with GCC using: + + + gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0` + + + For more information on how to compile a GTK+ application, please + refer to the Compiling GTK+ Applications + 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 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. + + The following line will call gtk_init(), which + is the initialization function for GTK+; this function will set up GTK+, + the type system, the connection to the windowing environment, etc. The + gtk_init() takes as arguments the pointers to the command line arguments + counter and string array; this allows GTK+ to parse specific command line + arguments that control the behavior of GTK+ itself. The parsed arguments + will be removed from the array, leaving the unrecognized ones for your + application to parse. + + 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. + + 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. + + #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. + + 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+. + + In the long tradition of programming languages and libraries, + it is called Hello, World. + + + + + + + Hello World in GTK+ + + + FIXME: MISSING XINCLUDE CONTENT + + + +