gtk-tut.sgml

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

<programlisting role="C">
g_signal_connect (G_OBJECT (button), "button_press_event",
                  G_CALLBACK (button_press_callback), NULL);
</programlisting>

<para>This assumes that <literal>button</literal> is a Button widget. Now, when the
mouse is over the button and a mouse button is pressed, the function
button_press_callback() will be called. This function may be declared as:</para>

<programlisting role="C">
static gboolean button_press_callback( GtkWidget      *widget, 
                                       GdkEventButton *event,
                                       gpointer        data );
</programlisting>

<para>Note that we can declare the second argument as type
<literal>GdkEventButton</literal> as we know what type of event will occur for this
function to be called.</para>

<para>The value returned from this function indicates whether the event
should be propagated further by the GTK event handling
mechanism. Returning TRUE indicates that the event has been handled,
and that it should not propagate further. Returning FALSE continues
the normal event handling.  See the section on
<link linkend="ch-AdvancedEventsAndSignals">Advanced Event and Signal Handling</link> 
for more details on this propagation process.</para>

<para>For details on the GdkEvent data types, see the appendix entitled
<link linkend="app-GDKEventTypes">GDK Event Types</link>.</para>

<para>The GDK selection and drag-and-drop APIs also emit a number of events which
are reflected in GTK by the signals. See <link 
linkend="sec-SignalsOnSourceWidgets">Signals on the source widget</link> and <link 
linkend="sec-SignalsOnDestWidgets">Signals on the destination widget</link>
for details on the signatures of the callback functions for these signals:</para>

<itemizedlist spacing=Compact>
<listitem><simpara> selection_received</simpara>
</listitem>
<listitem><simpara> selection_get</simpara>
</listitem>
<listitem><simpara> drag_begin_event</simpara>
</listitem>
<listitem><simpara> drag_end_event</simpara>
</listitem>
<listitem><simpara> drag_data_delete</simpara>
</listitem>
<listitem><simpara> drag_motion</simpara>
</listitem>
<listitem><simpara> drag_drop</simpara>
</listitem>
<listitem><simpara> drag_data_get</simpara>
</listitem>
<listitem><simpara> drag_data_received</simpara>
</listitem>
</itemizedlist>

</sect1>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-SteppingThroughHelloWorld">
<title>Stepping Through Hello World</title>

<para>Now that we know the theory behind this, let's clarify by walking
through the example <emphasis>helloworld</emphasis> program.</para>

<para>Here is the callback function that will be called when the button is
"clicked". We ignore both the widget and the data in this example, but
it is not hard to do things with them. The next example will use the
data argument to tell us which button was pressed.</para>

<programlisting role="C">
static void hello( GtkWidget *widget,
                   gpointer   data )
{
    g_print ("Hello World\n");
}
</programlisting>

<para>The next callback is a bit special. The "delete_event" occurs when the
window manager sends this event to the application. We have a choice
here as to what to do about these events. We can ignore them, make
some sort of response, or simply quit the application.</para>

<para>The value you return in this callback lets GTK know what action to
take.  By returning TRUE, we let it know that we don't want to have
the "destroy" signal emitted, keeping our application running. By
returning FALSE, we ask that "destroy" be emitted, which in turn will
call our "destroy" signal handler.</para>


<programlisting role="C">
static gboolean delete_event( GtkWidget *widget,
                              GdkEvent  *event,
                              gpointer   data )
{
    g_print ("delete event occurred\n");

    return TRUE; 
}
</programlisting>

<para>Here is another callback function which causes the program to quit by
calling gtk_main_quit(). This function tells GTK that it is to exit
from gtk_main when control is returned to it.</para>

<programlisting role="C">
static void destroy( GtkWidget *widget,
                     gpointer   data )
{
    gtk_main_quit ();
}
</programlisting>

<para>I assume you know about the main() function... yes, as with other
applications, all GTK applications will also have one of these.</para>

<programlisting role="C">
int main( int   argc,
          char *argv[] )
{
</programlisting>

<para>This next part declares pointers to a structure of type
GtkWidget. These are used below to create a window and a button.</para>

<programlisting role="C">
    GtkWidget *window;
    GtkWidget *button;
</programlisting>

<para>Here is our gtk_init() again. As before, this initializes the toolkit,
and parses the arguments found on the command line. Any argument it
recognizes from the command line, it removes from the list, and
modifies argc and argv to make it look like they never existed,
allowing your application to parse the remaining arguments.</para>

<programlisting role="C">
    gtk_init (&amp;argc, &amp;argv);
</programlisting>

<para>Create a new window. This is fairly straightforward. Memory is
allocated for the GtkWidget *window structure so it now points to a
valid structure. It sets up a new window, but it is not displayed
until we call gtk_widget_show(window) near the end of our program.</para>

<programlisting role="C">
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
</programlisting>

<para>Here are two examples of connecting a signal handler to an object, in
this case, the window. Here, the "delete_event" and "destroy" signals
are caught. The first is emitted when we use the window manager to
kill the window, or when we use the gtk_widget_destroy() call passing
in the window widget as the object to destroy. The second is emitted
when, in the "delete_event" handler, we return FALSE.
 
The <literal>G_OBJECT</literal> and <literal>G_CALLBACK</literal> are macros 
that perform type casting and checking for us, as well as aid the readability of
the code.</para>

<programlisting role="C">
    g_signal_connect (G_OBJECT (window), "delete_event",
                      G_CALLBACK (delete_event), NULL);
    g_signal_connect (G_OBJECT (window), "destroy",
                      G_CALLBACK (destroy), NULL);
</programlisting>

<para>This next function is used to set an attribute of a container object.
This just sets the window so it has a blank area along the inside of
it 10 pixels wide where no widgets will go. There are other similar
functions which we will look at in the section on
<link linkend="ch-SettingWidgetAttributes">Setting Widget Attributes</link></para>

<para>And again, <literal>GTK_CONTAINER</literal> is a macro to perform type casting.</para>

<programlisting role="C">
    gtk_container_set_border_width (GTK_CONTAINER (window), 10);
</programlisting>

<para>This call creates a new button. It allocates space for a new GtkWidget
structure in memory, initializes it, and makes the button pointer
point to it. It will have the label "Hello World" on it when
displayed.</para>

<programlisting role="C">
    button = gtk_button_new_with_label ("Hello World");
</programlisting>

<para>Here, we take this button, and make it do something useful. We attach
a signal handler to it so when it emits the "clicked" signal, our
hello() function is called. The data is ignored, so we simply pass in
NULL to the hello() callback function. Obviously, the "clicked" signal
is emitted when we click the button with our mouse pointer.</para>

<programlisting role="C">
    g_signal_connect (G_OBJECT (button), "clicked",
                      G_CALLBACK (hello), NULL);
</programlisting>

<para>We are also going to use this button to exit our program. This will
illustrate how the "destroy" signal may come from either the window
manager, or our program. When the button is "clicked", same as above,
it calls the first hello() callback function, and then this one in the
order they are set up. You may have as many callback functions as you
need, and all will be executed in the order you connected
them. Because the gtk_widget_destroy() function accepts only a
GtkWidget *widget as an argument, we use the g_signal_connect_swapped() 
function here instead of straight g_signal_connect().</para>

<programlisting role="C">
    g_signal_connect_swapped (G_OBJECT (button), "clicked",
                              G_CALLBACK (gtk_widget_destroy),
                              G_OBJECT (window));
</programlisting>

<para>This is a packing call, which will be explained in depth later on in
<link linkend="ch-PackingWidgets">Packing Widgets</link>. But it is
fairly easy to understand. It simply tells GTK that the button is to
be placed in the window where it will be displayed. Note that a GTK
container can only contain one widget. There are other widgets, that
are described later, which are designed to layout multiple widgets in
various ways.
 </para>

<programlisting role="C">
    gtk_container_add (GTK_CONTAINER (window), button);
</programlisting>

<para>Now we have everything set up the way we want it to be. With all the
signal handlers in place, and the button placed in the window where it
should be, we ask GTK to "show" the widgets on the screen. The window
widget is shown last so the whole window will pop up at once rather
than seeing the window pop up, and then the button form inside of
it. Although with such a simple example, you'd never notice.</para>

<programlisting role="C">
    gtk_widget_show (button);

    gtk_widget_show (window);
</programlisting>

<para>And of course, we call gtk_main() which waits for events to come from
the X server and will call on the widgets to emit signals when these
events come.</para>

<programlisting role="C">
    gtk_main ();
</programlisting>

<para>And the final return. Control returns here after gtk_quit() is called.</para>

<programlisting role="C">
    return 0;
</programlisting>

<para>Now, when we click the mouse button on a GTK button, the widget emits
a "clicked" signal. In order for us to use this information, our
program sets up a signal handler to catch that signal, which
dispatches the function of our choice. In our example, when the button
we created is "clicked", the hello() function is called with a NULL
argument, and then the next handler for this signal is called. This
calls the gtk_widget_destroy() function, passing it the window widget
as its argument, destroying the window widget. This causes the window
to emit the "destroy" signal, which is caught, and calls our destroy()
callback function, which simply exits GTK.</para>

<para>Another course of events is to use the window manager to kill the
window, which will cause the "delete_event" to be emitted. This will
call our "delete_event" handler. If we return TRUE here, the window
will be left as is and nothing will happen. Returning FALSE will cause
GTK to emit the "destroy" signal which of course calls the "destroy"
callback, exiting GTK.</para>

</sect1>
</chapter>

<!-- ***************************************************************** -->
<chapter id="ch-MovingOn">
<title>Moving On</title>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-DataTypes">
<title>Data Types</title>

<para>There are a few things you probably noticed in the previous examples
that need explaining. The gint, gchar, etc. that you see are typedefs
to int and char, respectively, that are part of the GLib system. This
is done to get around that nasty dependency on the size of simple data
types when doing calculations.</para>

<para>A good example is "gint32" which will be typedef'd to a 32 bit integer
for any given platform, whether it be the 64 bit alpha, or the 32 bit
i386. The typedefs are very straightforward and intuitive. They are
all defined in <filename>glib/glib.h</filename> (which gets included from 
<filename>gtk.h</filename>).</para>

<para>You'll also notice GTK's ability to use GtkWidget when the function
calls for a GtkObject. GTK is an object oriented design, and a widget
is an object.</para>

</sect1>

<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-MoreOnSignalHandlers">
<title>More on Signal Handlers</title>

<para>Lets take another look at the g_signal_connect() declaration.</para>

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

<para>Notice the gulong return value? This is a tag that identifies your
callback function. As stated above, you may have as many callbacks per
signal and per object as you need, and each will be executed in turn,
in the order they were attached.</para>

<para>This tag allows you to remove this callback from the list by using:</para>

<programlisting role="C">
void g_signal_handler_disconnect( gpointer object,
                                  gulong   id );
</programlisting>

<para>So, by passing in the widget you wish to remove the handler from, and
the tag returned by one of the signal_connect functions, you can
disconnect a signal handler.</para>

<para>You can also temporarily disable signal handlers with the
g_signal_handler_block() and g_signal_handler_unblock() family of
functions.</para>

<programlisting role="C">
void g_signal_handler_block( gpointer object,
                             gulong   id );

void g_signal_handlers_block_by_func( gpointer  object,
                                      GCallback func,
                                      gpointer  data );

void g_signal_handler_unblock( gpointer object,
                               gulong   id );

void g_signal_handlers_unblock_by_func( gpointer  object,
                                        GCallback func,