gtk_tut.txt

来自「gtk1.2的教程」· 文本 代码 · 共 2,235 行 · 第 1/5 页

  o  drag_end_event

  o  drop_enter_event

  o  drop_leave_event

  o  drop_data_available_event

  o  other_event

  In order to connect a callback function to one of these events, you
  use the function gtk_signal_connect, as described above, using one of
  the above event names as the name parameter. The callback function for
  events has a slightly different form than that for signals:



       void callback_func( GtkWidget *widget,
                           GdkEvent  *event,
                           gpointer   callback_data );




  GdkEvent is a C union 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 type parameter
  which 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:
         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_BEGIN
         GDK_DRAG_REQUEST
         GDK_DROP_ENTER
         GDK_DROP_LEAVE
         GDK_DROP_DATA_AVAIL
         GDK_CLIENT_EVENT
         GDK_VISIBILITY_NOTIFY
         GDK_NO_EXPOSE
         GDK_OTHER_EVENT       /* Deprecated, use filters instead */




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



       gtk_signal_connect( GTK_OBJECT(button), "button_press_event",
                           GTK_SIGNAL_FUNC(button_press_callback),
                           NULL);




  This assumes that button 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:



       static gint button_press_callback( GtkWidget      *widget,
                                          GdkEventButton *event,
                                          gpointer        data );




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


  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 ``Advanced Event and Signal
  Handling'' for more details on this propagation process.

  For details on the GdkEvent data types, see the appendix entitled
  ``GDK Event Types''.


  2.5.  Stepping Through Hello World

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

  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.



       void hello( GtkWidget *widget,
                   gpointer   data )
       {
           g_print ("Hello World\n");
       }




  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.

  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.



       gint delete_event( GtkWidget *widget,
                          GdkEvent  *event,
                          gpointer   data )
       {
           g_print ("delete event occurred\n");

           return (TRUE);
       }




  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.






  void destroy( GtkWidget *widget,
                gpointer   data )
  {
      gtk_main_quit ();
  }




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



       int main( int   argc,
                 char *argv[] )
       {




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



           GtkWidget *window;
           GtkWidget *button;




  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.



           gtk_init (&argc, &argv);




  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.



           window = gtk_window_new (GTK_WINDOW_TOPLEVEL);




  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 GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type
  casting and checking for us, as well as aid the readability of the
  code.



           gtk_signal_connect (GTK_OBJECT (window), "delete_event",
                               GTK_SIGNAL_FUNC (delete_event), NULL);
           gtk_signal_connect (GTK_OBJECT (window), "destroy",
                               GTK_SIGNAL_FUNC (destroy), NULL);




  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 ``Setting Widget
  Attributes''

  And again, GTK_CONTAINER is a macro to perform type casting.



           gtk_container_set_border_width (GTK_CONTAINER (window), 10);




  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.



           button = gtk_button_new_with_label ("Hello World");




  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.



           gtk_signal_connect (GTK_OBJECT (button), "clicked",
                               GTK_SIGNAL_FUNC (hello), NULL);




  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 gtk_signal_connect_object()
  function here instead of straight gtk_signal_connect().




      gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
                                 GTK_SIGNAL_FUNC (gtk_widget_destroy),
                                 GTK_OBJECT (window));




  This is a packing call, which will be explained in depth later on in
  ``Packing Widgets''. 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.



           gtk_container_add (GTK_CONTAINER (window), button);




  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.



           gtk_widget_show (button);

           gtk_widget_show (window);




  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.



           gtk_main ();




  And the final return. Control returns here after gtk_quit() is called.



           return (0);




  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.

  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.


  3.  Moving On

  3.1.  Data Types

  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 GLlib system. This
  is done to get around that nasty dependency on the size of simple data
  types when doing calculations.

  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 glib/glib.h (which gets included from gtk.h).

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


  3.2.  More on Signal Handlers

  Lets take another look at the gtk_signal_connect declaration.



       gint gtk_signal_connect( GtkObject *object,
                                gchar *name,
                                GtkSignalFunc func,
                                gpointer func_data );




  Notice the gint 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.

  This tag allows you to remove this callback from the list by using:



       void gtk_signal_disconnect( GtkObject *object,
                                   gint id );




  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.

  You can also temporarily disable signal handlers with the
  gtk_signal_handler_block() and gtk_signal_handler_unblock() family of
  functions.
       void gtk_signal_handler_block( GtkObject *object,
                                      guint      handler_id );

       void gtk_signal_handler_block_by_func( GtkObject     *object,
                                              GtkSignalFunc  func,
                                              gpointer       data );

       void gtk_signal_handler_block_by_data( GtkObject *object,
                                              gpointer   data );

       void gtk_signal_handler_unblock( GtkObject *object,
                                        guint      handler_id );

       void gtk_signal_handler_unblock_by_func( GtkObject     *object,
                                                GtkSignalFunc  func,
                                                gpointer       data );

       void gtk_signal_handler_unblock_by_data( GtkObject *object,
                                                gpointer   data);