diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 4f71a8f058..0140db6cb3 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -132,16 +132,18 @@ content_files = \ gtk-query-immodules-3.0.xml \ gtk-update-icon-cache-3.0.xml \ gtk-builder-convert-3.0.xml \ - visual_index.xml + visual_index.xml \ + getting_started.xml expand_content_files = \ drawing-model.xml \ + getting_started.xml \ glossary.xml \ migrating-2to3.xml \ migrating-checklist.sgml \ - tree_widget.sgml \ + question_index.sgml \ text_widget.sgml \ - question_index.sgml + tree_widget.sgml # Images to copy into HTML directory HTML_IMAGES = \ diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml new file mode 100644 index 0000000000..8ce21b900b --- /dev/null +++ b/docs/reference/gtk/getting_started.xml @@ -0,0 +1,96 @@ + + + + Getting Started with GTK+ + + To begin our introduction to GTK, we'll start with the simplest + program possible. This program will create a 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 will be 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 + + + + + diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index f5497d93bf..d089e86413 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -115,6 +115,7 @@ that is, GUI components such as GtkButton or GtkTextView. + diff --git a/examples/hello-world.c b/examples/hello-world.c new file mode 100644 index 0000000000..50c792f12f --- /dev/null +++ b/examples/hello-world.c @@ -0,0 +1,103 @@ +#include + +/* This is a callback function. The data arguments are ignored + * in this example. More on callbacks below. */ +static void +print_hello (GtkWidget *widget, + gpointer data) +{ + g_print ("Hello World\n"); +} + +static gboolean +on_delete_event (GtkWidget *widget, + GdkEvent *event, + gpointer data) +{ + /* If you return FALSE in the "delete_event" signal handler, + * GTK will emit the "destroy" signal. Returning TRUE means + * you don't want the window to be destroyed. + * + * This is useful for popping up 'are you sure you want to quit?' + * type dialogs. + */ + + g_print ("delete event occurred\n"); + + return TRUE; +} + +int +main (int argc, + char *argv[]) +{ + /* GtkWidget is the storage type for widgets */ + GtkWidget *window; + GtkWidget *button; + + /* This is called in all GTK applications. Arguments are parsed + * from the command line and are returned to the application. + */ + gtk_init (&argc, &argv); + + /* create a new window, and set its title */ + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_window_set_title (GTK_WINDOW (window), "Hello"); + + /* When the window emits the "delete-event" signal (which is emitted + * by GTK+ in response to an event coming from the window manager, + * usually as a result of clicking the "close" window control), we + * ask it to call the on_delete_event() function as defined above. + * + * The data passed to the callback function is NULL and is ignored + * in the callback function. + */ + g_signal_connect (window, "delete-event", G_CALLBACK (on_delete_event), NULL); + + /* Here we connect the "destroy" event to the gtk_main_quit() function. + * + * This signal is emitted when we call gtk_widget_destroy() on the window, + * or if we return FALSE in the "delete_event" callback. + */ + g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL); + + /* Sets the border width of the window. */ + gtk_container_set_border_width (GTK_CONTAINER (window), 10); + + /* Creates a new button with the label "Hello World". */ + button = gtk_button_new_with_label ("Hello World"); + + /* When the button receives the "clicked" signal, it will call the + * function print_hello() passing it NULL as its argument. + * + * The print_hello() function is defined above. + */ + g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL); + + /* The g_signal_connect_swapped() function will connect the "clicked" signal + * of the button to the gtk_widget_destroy() function; instead of calling it + * using the button as its argument, it will swap it with the user data + * argument. This will cause the window to be destroyed by calling + * gtk_widget_destroy() on the window. + */ + g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_widget_destroy), window); + + /* This packs the button into the window. A GtkWindow inherits from GtkBin, + * which is a special container that can only have one child + */ + gtk_container_add (GTK_CONTAINER (window), button); + + /* The final step is to display this newly created widget... */ + gtk_widget_show (button); + + /* ... and the window */ + gtk_widget_show (window); + + /* All GTK applications must have a gtk_main(). Control ends here + * and waits for an event to occur (like a key press or a mouse event), + * until gtk_main_quit() is called. + */ + gtk_main (); + + return 0; +} diff --git a/examples/window-default.c b/examples/window-default.c new file mode 100644 index 0000000000..79888def97 --- /dev/null +++ b/examples/window-default.c @@ -0,0 +1,20 @@ +#include + +int +main (int argc, + char *argv[]) +{ + GtkWidget *window; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + + g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL); + + gtk_widget_show (window); + + gtk_main (); + + return 0; +}