GtkAda Reference Manual - Package Gtk.Handlers

[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Gtk.Handlers

The aim of this package is to provide some services to connect a handler to a signal emitted by a Gtk Object. To understand the services provided by this package, some definitions are necessary:

Signal: A signal is a kind of message that an object wants to broadcast. All GObjects can emit signals. These messages are associated to certain events happening during the life of an object. For instance, when a user clicks on a button, the "clicked" signal is emitted by the button.

Handler (or callback): A handler is a function or procedure that the user "connects" to a signal for a particular object. Connecting a handler to a signal means associating this handler to the signal. When the signal is emitted, all connected handlers are called back. Usually, the role of those callbacks is to do some processing triggered by a user action. For instance, when "clicked" signal is emitted by the "OK" button of a dialog, the connected handler can be used to close the dialog or recompute some value.

In GtkAda, the handlers are defined in a form as general as possible. The first argument is always an access to the object it has been connected to. The second object is a table of values (See Glib.Values for more details about this table). It is the responsibility of this handler to extract the values from it, and to convert them to the correct Ada type.

Because such handlers are not very convenient to use, this package also provides some services to connect a marshaller instead. It will then do the extraction work before calling the more programmer-friendly handler, as defined in Gtk.Marshallers (see Gtk.Marshallers for more details).

The subdivision of this package is identical to Gtk.Marshallers; it is made of four generic sub-packages, each representing one of the four possible kinds of handlers: they can return a value or not, and they can have some user specific data associated to them or not. Selecting the right package depends on the profile of the handler. For example, the handler for the "delete_event" signal of a Gtk_Window has a return value, and has an extra parameter (a Gint). All handlers also have a user_data field by default, but its usage is optional. To connect a handler to this signal, if the user_data field is not used, the Return_Callback generic should be instantiated. On the other hand, if the user_data field is necessary, then the User_Return_Callback generic should be used.

Note also that the real handler in Gtk+ should expect at least as many arguments as in the marshaller you are using. If your marshaller has one argument, the C handler must have at least one argument too.

The common generic parameter to all sub-packages is the widget type, which is the basic widget manipulated. This can be Glib.Object.GObject_Record type if you want to reduce the number of instantiations, but the conversion to the original type will have to be done inside the handler.

All sub-packages are organized in the same way.

First, the type "Handler" is defined. It represents the general form of the callbacks supported by the sub-package.

The corresponding sub-package of Gtk.Marshallers is instantiated.

A series of "Connect" procedures and functions is given. All cases are covered: the functions return the Handler_Id of the newly created association, while the procedures just connect the handler, dropping the Handler_Id; some services allow the user to connect a Handler while some others allow the usage of Marshallers, which are more convenient. Note that more than one handler may be connected to a signal; the handlers will then be invoked in the order of connection.

Some "Connect_Object" services are also provided. Those services never have a user_data. They accept an additional parameter called Slot_Object. When the callback in invoked, the Gtk Object emitting the signal is substituted by this Slot_Object. These callbacks are always automatically disconnected as soon as one of the two widgets involved is destroyed.

There are several methods to connect a handler. For each method, although the option of connecting a Handler is provided, the recommended way is to use Marshallers. Each connect service is documented below, in the first sub-package.

A series of "To_Marshaller" functions are provided. They return some marshallers for the most commonly used types in order to ease the usage of this package. Most of the time, it will not be necessary to use some other marshallers.

As for the "To_Marshaller" functions, a series of "Emit_By_Name" procedures are also provided for the same most common types, to allow the user to easily emit signals. These procedures are mainly intended for people building new GObjects.

At the end of this package, some general services related to the management of signals and handlers are also provided. Each one of them is documented individually below.

IMPORTANT NOTE: These packages must be instantiated at library-level

- Gtk.Handlers Example

## Example

     --  This example connects the "delete_event" signal to a widget.
     --  The handlers for this signal get an extra argument which is
     --  the Gdk_Event that generated the signal.

     with Gtk.Handlers;    use Gtk.Handlers;
     with Gtk.Marshallers; use Gtk.Marshallers;

     function My_Cb (Widget : access Gtk_Widget_Record'Class;
                     Event  : Gdk.Event.Gdk_Event)
                     return Gint;
     --  your own function

     package Return_Widget_Cb is new Gtk.Handlers.Return_Callback
        (Gtk.Widget.Gtk_Widget_Record, Gint);

     Return_Widget_Cb.Connect (W, "delete_event",
        Return_Widget_Cb.To_Marshaller (My_Cb'Access));

[Contents] [Back] [Prev] [Up] [Next] [Forward]