gtk-tut.sgml

linux下电话本所依赖的一些图形库

    /* 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 */
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    
    /* When the window is given the "delete_event" signal (this is given
     * by the window manager, usually by the "close" option, or on the
     * titlebar), we ask it to call the 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 (G_OBJECT (window), "delete_event",
		      G_CALLBACK (delete_event), NULL);
    
    /* Here we connect the "destroy" event to a signal handler.  
     * This event occurs when we call gtk_widget_destroy() on the window,
     * or if we return FALSE in the "delete_event" callback. */
    g_signal_connect (G_OBJECT (window), "destroy",
		      G_CALLBACK (destroy), 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 hello() passing it NULL as its argument.  The hello()
     * function is defined above. */
    g_signal_connect (G_OBJECT (button), "clicked",
		      G_CALLBACK (hello), NULL);
    
    /* This will cause the window to be destroyed by calling
     * gtk_widget_destroy(window) when "clicked".  Again, the destroy
     * signal could come from here, or the window manager. */
    g_signal_connect_swapped (G_OBJECT (button), "clicked",
			      G_CALLBACK (gtk_widget_destroy),
                              G_OBJECT (window));
    
    /* This packs the button into the window (a gtk container). */
    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
     * mouse event). */
    gtk_main ();
    
    return 0;
}
<!-- example-end -->
</programlisting>

</sect1>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-Compiling">
<title>Compiling Hello World</title>

<para>To compile use:</para>

<para><literallayout>
<literal>gcc -Wall -g helloworld.c -o helloworld `pkg-config --cflags gtk+-2.0` \</literal>
<literal>    `pkg-config --libs gtk+-2.0`</literal>
</literallayout></para>

<para>This uses the program <literal>pkg-config</literal>, which can be obtained from
<ulink url="http://www.freedesktop.org">www.freedesktop.org</ulink>. This program 
reads the <filename>.pc</filename> which comes with GTK to determine what 
compiler switches are needed to compile programs that use GTK. 
<literal>pkg-config --cflags gtk+-2.0</literal> will output a list of include
directories for the compiler to look in, and 
<literal>pkg-config --libs gtk+-2.0</literal>
will output the list of libraries for the compiler to link with and
the directories to find them in. In the above example they could have
been combined into a single instance, such as
<literal>pkg-config --cflags --libs gtk+-2.0</literal>.</para>

<para>Note that the type of single quote used in the compile command above
is significant.</para>

<para>The libraries that are usually linked in are:</para>

<itemizedlist>
<listitem><simpara>The GTK library (<literal>-lgtk</literal>), the widget library, 
based on top of GDK.</simpara>
</listitem>

<listitem><simpara>The GDK library (<literal>-lgdk</literal>), the Xlib wrapper.</simpara>
</listitem>

<listitem><simpara>The gdk-pixbuf library (<literal>-lgdk_pixbuf</literal>), the image 
manipulation library.</simpara>
</listitem>

<listitem><simpara>The Pango library (<literal>-lpango</literal>) for internationalized 
text.</simpara>
</listitem>

<listitem><simpara>The gobject library (<literal>-lgobject</literal>), containing the
type system on which GTK is based.</simpara>
</listitem>

<listitem><simpara>The gmodule library (<literal>-lgmodule</literal>), which is used 
to load run time extensions.</simpara>
</listitem>

<listitem><simpara>The GLib library (<literal>-lglib</literal>), containing miscellaneous
functions; only g_print() is used in this particular example. GTK is built on top
of GLib so you will always require this library. See the section on
<link linkend="ch-glib">GLib</link> for details.</simpara>
</listitem>

<listitem><simpara>The Xlib library (<literal>-lX11</literal>) which is used by GDK.</simpara>
</listitem>

<listitem><simpara>The Xext library (<literal>-lXext</literal>). This contains code 
for shared memory pixmaps and other X extensions.</simpara>
</listitem>

<listitem><simpara>The math library (<literal>-lm</literal>). This is used by GTK 
for various purposes.</simpara>
</listitem>
</itemizedlist>

</sect1>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-TheoryOfSignalsAndCallbacks">
<title>Theory of Signals and Callbacks</title>

<note>
<para>In version 2.0, the signal system has been moved from GTK to GLib, therefore the
functions and types explained in this section have a "g_" prefix rather than a "gtk_" 
prefix. We won't go into details about the extensions which the GLib 2.0 signal system
has relative to the GTK 1.2 signal system.</para>
</note>

<para>Before we look in detail at <emphasis>helloworld</emphasis>, we'll discuss signals
and callbacks. GTK is an event driven toolkit, which means it will
sleep in gtk_main() until an event occurs and control is passed to the
appropriate function.</para>

<para>This passing of control is done using the idea of "signals". (Note
that these signals are not the same as the Unix system signals, and
are not implemented using them, although the terminology is almost
identical.) When an event occurs, such as the press of a mouse button,
the appropriate signal will be "emitted" by the widget that was
pressed.  This is how GTK does most of its useful work. There are
signals that all widgets inherit, such as "destroy", and there are
signals that are widget specific, such as "toggled" on a toggle
button.</para>

<para>To make a button perform an action, we set up a signal handler to
catch these signals and call the appropriate function. This is done by
using a function such as:</para>

<programlisting role="C">
gulong g_signal_connect( gpointer      *object,
                         const gchar   *name,
                         GCallback     func,
                         gpointer      func_data );
</programlisting>

<para>where the first argument is the widget which will be emitting the
signal, and the second the name of the signal you wish to catch. The
third is the function you wish to be called when it is caught, and the
fourth, the data you wish to have passed to this function.</para>

<para>The function specified in the third argument is called a "callback
function", and should generally be of the form</para>

<programlisting role="C">
void callback_func( GtkWidget *widget,
                    ... /* other signal arguments */
                    gpointer   callback_data );
</programlisting>

<para>where the first argument will be a pointer to the widget that emitted
the signal, and the last a pointer to the data given as the last
argument to the g_signal_connect() function as shown above.</para>

<para>Note that the above form for a signal callback function declaration is
only a general guide, as some widget specific signals generate
different calling parameters.</para>

<para>Another call used in the <emphasis>helloworld</emphasis> example, is:</para>

<programlisting role="C">
gulong g_signal_connect_swapped( gpointer     *object,
                                 const gchar  *name,
                                 GCallback    func,
                                 gpointer     *callback_data );
</programlisting>

<para>g_signal_connect_swapped() is the same as g_signal_connect() except
that the instance on which the signal is emitted and data will be swapped when
calling the handler. So when using this function to connect signals, the callback
should be of the form</para>

<programlisting role="C">
void callback_func( gpointer   callback_data,
                    ... /* other signal arguments */
                    GtkWidget *widget);
</programlisting>

<para>where the object is usually a widget. We usually don't setup callbacks
for g_signal_connect_swapped() however. They are usually used to call a
GTK function that accepts a single widget or object as an argument, when a signal
is emitted on some <emphasis>other</emphasis> object. In the 
<emphasis>helloworld</emphasis> example, we connect to the "clicked" signal
on the button, but call gtk_widget_destroy() on the window.</para>

<para>If your callbacks need additional data, use g_signal_connect() instead
of g_signal_connect_swapped().</para>

</sect1>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-Events">
<title>Events</title>

<para>In addition to the signal mechanism described above, there is a set
of <emphasis>events</emphasis> that reflect the X event mechanism. Callbacks may
also be attached to these events. These events are:</para>

<itemizedlist spacing=Compact>
<listitem><simpara> event</simpara>
</listitem>
<listitem><simpara> button_press_event</simpara>
</listitem>
<listitem><simpara> button_release_event</simpara>
</listitem>
<listitem><simpara> scroll_event</simpara>
</listitem>
<listitem><simpara> motion_notify_event</simpara>
</listitem>
<listitem><simpara> delete_event</simpara>
</listitem>
<listitem><simpara> destroy_event</simpara>
</listitem>
<listitem><simpara> expose_event</simpara>
</listitem>
<listitem><simpara> key_press_event</simpara>
</listitem>
<listitem><simpara> key_release_event</simpara>
</listitem>
<listitem><simpara> enter_notify_event</simpara>
</listitem>
<listitem><simpara> leave_notify_event</simpara>
</listitem>
<listitem><simpara> configure_event</simpara>
</listitem>
<listitem><simpara> focus_in_event</simpara>
</listitem>
<listitem><simpara> focus_out_event</simpara>
</listitem>
<listitem><simpara> map_event</simpara>
</listitem>
<listitem><simpara> unmap_event</simpara>
</listitem>
<listitem><simpara> property_notify_event</simpara>
</listitem>
<listitem><simpara> selection_clear_event</simpara>
</listitem>
<listitem><simpara> selection_request_event</simpara>
</listitem>
<listitem><simpara> selection_notify_event</simpara>
</listitem>
<listitem><simpara> proximity_in_event</simpara>
</listitem>
<listitem><simpara> proximity_out_event</simpara>
</listitem>
<listitem><simpara> visibility_notify_event</simpara>
</listitem>
<listitem><simpara> client_event</simpara>
</listitem>
<listitem><simpara> no_expose_event</simpara>
</listitem>
<listitem><simpara> window_state_event</simpara>
</listitem>
</itemizedlist>

<para>In order to connect a callback function to one of these events you
use the function g_signal_connect(), as described above, using one of
the above event names as the <literal>name</literal> parameter. The callback
function for events has a slightly different form than that for
signals:</para>

<programlisting role="C">
gint callback_func( GtkWidget *widget,
                    GdkEvent  *event,
                    gpointer   callback_data );
</programlisting>

<para>GdkEvent is a C <literal>union</literal> structure whose type will depend upon 
which of the above events has occurred. In order for us to tell which event
has been issued each of the possible alternatives has a <literal>type</literal>
member that reflects the event being issued. The other components
of the event structure will depend upon the type of the
event. Possible values for the type are:</para>

<programlisting role="C">
  GDK_NOTHING
  GDK_DELETE
  GDK_DESTROY
  GDK_EXPOSE
  GDK_MOTION_NOTIFY
  GDK_BUTTON_PRESS
  GDK_2BUTTON_PRESS
  GDK_3BUTTON_PRESS
  GDK_BUTTON_RELEASE
  GDK_KEY_PRESS
  GDK_KEY_RELEASE
  GDK_ENTER_NOTIFY
  GDK_LEAVE_NOTIFY
  GDK_FOCUS_CHANGE
  GDK_CONFIGURE
  GDK_MAP
  GDK_UNMAP
  GDK_PROPERTY_NOTIFY
  GDK_SELECTION_CLEAR
  GDK_SELECTION_REQUEST
  GDK_SELECTION_NOTIFY
  GDK_PROXIMITY_IN
  GDK_PROXIMITY_OUT
  GDK_DRAG_ENTER
  GDK_DRAG_LEAVE
  GDK_DRAG_MOTION
  GDK_DRAG_STATUS
  GDK_DROP_START
  GDK_DROP_FINISHED
  GDK_CLIENT_EVENT
  GDK_VISIBILITY_NOTIFY
  GDK_NO_EXPOSE
  GDK_SCROLL
  GDK_WINDOW_STATE
  GDK_SETTING
</programlisting>

<para>So, to connect a callback function to one of these events we would use
something like:</para>