Commit f085c8b2 authored by Emmanuele Bassi's avatar Emmanuele Bassi Committed by Matthias Clasen

docs: Move the introduction of the tutorial in the reference

The tutorial should just go away, but some of its contents can be moved
to the API reference as chapters.

https://bugzilla.gnome.org/show_bug.cgi?id=632059
parent 22d28ef4
......@@ -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 = \
......
<?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>
<para>To begin our introduction to GTK, we'll start with the simplest
program possible. This program will create a 200x200 pixel window:</para>
<para>
<inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
</para>
<informalexample><programlisting>
<xi:include href="../../../../examples/window-default.c" parse="text">
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
</xi:include>
</programlisting></informalexample>
<para>You can compile the program above with GCC using:</para>
<para><literallayout>
<literal>gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0`</literal>
</literallayout></para>
<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 will be included.</para></warning>
<para>We then proceed into the <function>main</function>() function of the
application, and we declare a <varname>window</varname> variable as a pointer
of type #GtkWidget.</para>
<para>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.</para>
<note><para>For more information on which command line arguments GTK+
recognizes, please refer to the <link linkend="gtk-running">Running GTK+
Applications</link> section in this reference.</para></note>
<para>The call to gtk_window_new() will create a new #GtkWindow and store
it inside the <varname>window</varname> 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.</para>
<para>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 #GtkWindow<!-- -->s are also destroyed when
the Close window control button is clicked.</para>
<para>#GtkWidget<!-- -->s 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.</para>
<para>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
<function>main</function>() until the gtk_main_quit() function is
called.</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>
<example id="gtk-getting-started-hello-world">
<title>Hello World in GTK+</title>
<programlisting>
<xi:include href="../../../examples/hello-world.c" parse="text">
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
</xi:include>
</programlisting>
</example>
</chapter>
......@@ -115,6 +115,7 @@ that is, GUI components such as GtkButton or GtkTextView.
<xi:include href="building.sgml" />
<xi:include href="compiling.sgml" />
<xi:include href="running.sgml" />
<xi:include href="xml/getting_started.xml"/>
<xi:include href="x11.sgml" />
<xi:include href="windows.sgml" />
<xi:include href="osx.sgml" />
......
#include <gtk/gtk.h>
/* 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;
}
#include <gtk/gtk.h>
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;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment