callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Move the introduction of the tutorial in the reference

Browse Source 
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
This commit is contained in:
Emmanuele Bassi 2010-10-15 11:04:27 -04:00 committed by Matthias Clasen
parent 22d28ef47d
commit f085c8b272
5 changed files with 225 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/reference/gtk/Makefile.am
View File

@ -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 = \

96
docs/reference/gtk/getting_started.xml Normal file
View File

@ -0,0 +1,96 @@
<?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>

1
docs/reference/gtk/gtk-docs.sgml
View File

@ -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" />

103
examples/hello-world.c Normal file
View File

@ -0,0 +1,103 @@
#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;
}

20
examples/window-default.c Normal file
View File

@ -0,0 +1,20 @@
#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;
}