forked from AuroraMiddleware/gtk
Add a paragraph explaining events and signals
This commit is contained in:
Matthias Clasen
parent
0b7496558d
commit
ce1244fdd7
@ -12,97 +12,108 @@
|
||||
<link linkend="gtk-compiling">Compiling the GTK+ libraries</link>
|
||||
section in this reference.</para>
|
||||
|
||||
<para>To begin our introduction to GTK, we'll start with the simplest
|
||||
program possible. This program will create an empty 200x200 pixel
|
||||
window:</para>
|
||||
<section>
|
||||
<title>Basics</title>
|
||||
|
||||
<para>
|
||||
<inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
|
||||
</para>
|
||||
<para>To begin our introduction to GTK, we'll start with the simplest
|
||||
program possible. This program will create an empty 200x200 pixel
|
||||
window:</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>
|
||||
<inlinegraphic fileref="window-default.png" format="PNG"></inlinegraphic>
|
||||
</para>
|
||||
|
||||
<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 is directly 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>
|
||||
|
||||
<para>
|
||||
<inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
|
||||
</para>
|
||||
|
||||
<example id="gtk-getting-started-hello-world">
|
||||
<title>Hello World in GTK+</title>
|
||||
<programlisting>
|
||||
<xi:include href="../../../../examples/hello-world.c" parse="text">
|
||||
<informalexample><programlisting>
|
||||
<xi:include href="../../../../examples/window-default.c" parse="text">
|
||||
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
|
||||
</xi:include>
|
||||
</programlisting>
|
||||
</example>
|
||||
</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 is directly 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
|
||||
main() until the gtk_main_quit() function is called.</para>
|
||||
|
||||
<para>While the program is running, GTK+ is receiving
|
||||
<firstterm>events</firstterm>. 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, <firstterm>signals</firstterm> 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.</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>
|
||||
|
||||
<para>
|
||||
<inlinegraphic fileref="hello-world.png" format="PNG"></inlinegraphic>
|
||||
</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>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user