.. _Signal_handling:

***************
Signal handling
***************

In GtkAda, the interaction between the interface and the core application is
done via signals. Most user actions on the graphical application trigger some
signals to be emitted.

A signal is a message that an object wants to broadcast. It is identified by
its name, and each one is associated with certain events which happen during
the widget's lifetime. For instance, when the user clicks on a Gtk_Button, a
'clicked' signal is emitted by that button. More examples of signals can be
found in the GtkAda reference manual.

It is possible to cause the application to react to such events by
*connecting* to a signal a special procedure called a *handler* or
*callback*.  This handler will be called every time that signal is
emitted, giving the application a chance to do any processing it needs. More
than one handler can be connected to the same signal on the same object; the
handlers are invoked in the order they were connected.

Predefined signals
==================

Widgets, depending on their type, may define zero or more different signals.
The signals defined for the parent widget are also automatically inherited;
thus every widget answers many signals.

The easiest way to find out which signals can be emitted by a widget is to look
at the GtkAda reference manual. Every widget will be documented there. The
GtkAda RM explains when particular signals are emitted, and the general form
that their handlers should have (although you can always add a `User_Data` if
you wish, see below).

In general, your handlers should have the exact same profile that is
documented (the GtkAda RM is automatically generated, so you can in fact
find the same documentation directly in GtkAda's :file:`*.ads` files).

However, if you connect to signals via the generic packages defined in
:file:`Gtk.Handlers` (see below), it is valid to pass a procedure that
drops all arguments except the first one, i.e. the actual widget that
emitted the signal. To get a better documented code, though, we recommend
to always use the full profile for your handlers.

.. _Connecting_signals:

Connecting signals
==================

There are currently two ways to connect widgets to signal handlers.
One of them is much simpler to use, although it has some limited capabilities.

Connecting via the `On_*` procedures
----------------------------------------

Each widget has a number of primitive operations (including inherited
ones) for all the signals it might emit. In fact, for each signal there
are two `On_<signal_name>` procedures that can be used to easily connect
to the corresponding signal::

    procedure Handler (Button : access Gtk_Button_Record'Class) is
    begin
       ...
    end Handler;

    Button.On_Clicked (Handler'Access);

The code above ensures that the procedure `Handler` is called whenever the
button is clicked.

The `On_*` procedures ensure that the profile of the handler is correct,
and thus are type-safe.

The type of the first parameter to the handler is always the type where
the signal is defined, not the type to which the handler is connected.

For instance, the "draw" signal is defined for a `Gtk_Widget`. But if you
connect this signal to a `Gtk_Button`, the first paramter of the handler
is always of type `access Gtk_Widget_Record'Class`.

There is a second version of the `On_*` procedures, which is used to pass a
different object than the one the signal is connected to. In practice, this is
the version that is used more often. For instance, clicking on a toolbar button
will in general affect some other widget than the button itself, and you would
typically pass the main window as a parameter to the handler. Here is an
example, note how the type of the first parameter is different::

    procedure Handler (Win : access GObject_Record'Class) is
    begin
       ...
    end Handler;

    Button.On_Clicked (Handler'Access, Slot => Main_Window);

This subprogram also ensures that the handler is automaticall disconnected if
the second object is destroyed.


Connecting via the `Gtk.Handlers` package
------------------------------------------

All signal handling work is performed internally using services provided
by the `Gtk.Handlers` package. But this package can also be used directly
by user applications.

This file is collection of several generic packages that need to be
instantiated before you can actually start connecting handlers to widgets.
A number of predefined instantiations are provided in :file:`GtkAda.Handlers`
to make it slightly easier.

Compared to the previous approach based on the `On_*` procedures described
above, this approach has a number of additional capabilities, at the cost
of slightly more complex code:

  * It is possible to retrieve a handle on the Widget/Signal/Handle tuple,
    so that you can later on disconnect the handler, or temporarily block
    the signal for instance.

  * It is possible to pass additional user data to the handler. For instance,
    you could have a single handler connected to multiple check buttons.
    When you press any of the button, the handler is called and passes an
    additional integer to indicate which button was pressed.
    This is sometimes convenient, although it can often be avoided by creating
    new Ada tagged types derived from the standard GtkAda types.

  * You have full control over the type of the first parameter to the handler.
    As discussed earlier, the `On_*` subprograms force specific types (either
    a `GObject_Record` or the type on which the signal was defined). With the
    generic packages, you can avoid the often necessary type casts in the
    handler, although this approach does not guarantee more (or less) type
    safety.

  * A very limited number of signals do not have a corresponding `On_*` for
    circular dependency (or elaboration circularity) reasons. For those,
    you need to use the generic packages. However, we believe these signals
    are hardly ever used by user-level applications.

A short, annotated example of connecting signals follows; a complete
example can be found in create_file_selection.adb (inside the :file:`testgtk/`
directory). In our example, an application opens a file selector to
allow the user to select a file.  GtkAda provides a high-level widget
called Gtk_File_Selection which can be used in this case::

  declare
     Window : Gtk_File_Selection;
  begin
     Gtk.File_Selection.Gtk_New (Window, Title => "Select a file");
  end;

When the 'OK' button is pressed, the application needs to retrieve the
selected file and then close the dialog. The only information that the
handler for the button press needs is which widget to operate upon.
This can be achieved by the following handler::

  procedure OK (Files : access Gtk_File_Selection_Record'Class) is
  begin
     --  Prints the name of the selected file.
     Ada.Text_IO.Put_Line ("Selected " & Get_Filename (Files));

     --  Destroys the file selector dialog
     Destroy (Files);
  end Ok;

We now need to connect the object we created in the first part with the new
callback we just defined. `Gtk.Handlers` defines four types of generic
packages, depending on the arguments one expects in the callback and whether
the callback returns a value or not. Note that you can not use an arbitrary
list of arguments; these depend on the signal, as explained in the previous
section.

In our example, since the callback does not return any value and does not
handle any `User_Data` (that is, we don't pass it extra data, which will be
specified at connection time), the appropriate package to use is
`Gtk.Handlers.Callback`. We thus instantiate that package.

Remember that generic package instantiations in GtkAda must be present in
memory at all times, since they take care of freeing allocated memory when
finished. GtkAda generic package instantiations must therefore always be
performed at the library level, and not inside any inner block::

  package Files_Cb is new Handlers.Callback (Gtk_File_Selection_Record);

The `Files_Cb` package now provides a set of Connect subprograms that can be
used to establish a tie between a widget and a handler.  It also provides a set
of other subprograms which you can use to emit the signals manually, although
most of the time, the signals are simply emitted internally by GtkAda. We will
not discuss the `Emit_By_Name` subprograms here.

The general form of handler, as used in `Gtk.Handlers`, expects some handlers
that take two or three arguments: the widget on which the signal was applied,
an array of all the extra arguments sent internally by GtkAda, and possibly
some user data given when the connection was made.

This is the most general form of handler and it covers all the possible cases.
However, it also expects the user to manually extract the needed values from
the array of arguments. This is not always the most convenient solution. This
is why GtkAda provides a second package related to signals, `Gtk.Marshallers`.

The `Gtk.Marshallers` package provides a set of functions that can be used as
callbacks directly for GtkAda, and that will call your application's handlers
after extracting the required values from the array of arguments. Although this
might sound somewhat complicated, in practice it simplifies the task of
connecting signals. In fact, the techniques employed are similar to what is
done internally by gtk+ in C. Because of the similarity of techniques, there is
no overhead involved in using `Gtk.Marshallers` with Ada over the C code in
gtk+.

A set of functions `To_Marshaller` is found in every generic package in
`Gtk.Handlers`. They each take a single argument, the name of the function you
want to call, and return a handler that can be used directly in `Connect`.

The connection is then done with the following piece of code::

  Files_Cb.Object_Connect
    (Get_Ok_Button (Window),  --  The object to connect to the handler
     "clicked",               --  The name of the signal
     Files_Cb.To_Marshaller (Ok'Access),  --  The signal handler
     Slot_Object => Window);

Note that this can be done just after creating the widget, in the same block.
As soon as it is created, a widget is ready to accept connections (although no
signals will be emitted before the widget is shown on the screen).

We use `To_Marshaller` since our handler does not accept the array of arguments
as a parameter, and we use the special `Object_Connect` procedure. This means
that the parameter to our callback (Files) will be the Slot_Object given in
Object_Connect, instead of being the button itself.

Compare the above code to the approach described in the first section, in
particular when using Ada05 notation::

   Window.Get_Ok_Button.On_Clicked (Ok'Access, Window);

.. _Handling_user_data:

Handling user data
==================

As described above, it is possible to define some data that is that passed to
the callback when it is called. This data is called user_data, and is passed to
the `Connect` or `Object_Connect` subprograms.

GtkAda will automatically free any memory it has allocated internally to store
this user data. For instance, if you instantiated the generic package
`User_Callback` with a String, it means that you want to be able to have a
callback of the form::

     procedure My_Callback (Widget : access Gtk_Widget_Record'Class;
                             User_Data : String);
  
and connect it with a call similar to::

     Connect (Button, "Clicked", To_Marshaller (My_Callback'Access),
              User_Data => "any string");

GtkAda needs to allocate some memory to store the string (an unconstrained
type). However, this memory is automatically freed when the callback is
destroyed.

There are a few subtleties in the use of user_data, most importantly when the
user data is itself a widget.

The following four examples do exactly the same thing: each creates two
buttons, where clicking on the first one will destroy the second one.  They all
work fine the first time, while both buttons exist. However, some of them will
fail if you press on the first button a second time.

Complete, compilable source code for these examples can be found in the
distribution's :file:`examples/user_data` directory, from which the code
samples below are excerpted.

First case: simple user data
----------------------------

This code will fail: even after `Button2` is destroyed, the Ada pointer
continues to reference memory that has been deallocated.  The second call to
`Destroy` will fail with a Storage_Error::

     package User_Callback is new Gtk.Handlers.User_Callback
       (Gtk_Widget_Record, Gtk_Widget);

     procedure My_Destroy2
       (Button : access Gtk_Widget_Record'Class; Data : Gtk_Widget) is
     begin
        Destroy (Data);
     end My_Destroy2;

     begin
        User_Callback.Connect
          (Button1, "clicked",
           User_Callback.To_Marshaller (My_Destroy2'Access),
           Gtk_Widget (Button2));
     end;

Second case: using Object_Connect instead
-----------------------------------------

One of the solutions to fix the above problem is to use
`Object_Connect` instead of `Connect`. In that case, GtkAda
automatically takes care of disconnecting the callback when either of
the two widgets is destroyed::

     procedure My_Destroy (Button : access Gtk_Widget_Record'Class) is
     begin
        Destroy (Button);
     end My_Destroy;

     begin
        Widget_Callback.Object_Connect
          (Button1, "clicked",
           Widget_Callback.To_Marshaller (My_Destroy'Access),
           Button2);
     end;

Third case: manually disconnecting the callback
-----------------------------------------------

Using `Object_Connect` is not always possible. In that case, one
of the possibilities is to store the `Id` of the callback, and
properly disconnect it when appropriate. This is the most complex
method, and very often is not applicable, since you cannot know for
sure when the callback is no longer needed::

     type My_Data3 is record
        Button, Object : Gtk_Widget;
        Id             : Handler_Id;
     end record;
     type My_Data3_Access is access My_Data3;

     package User_Callback3 is new Gtk.Handlers.User_Callback
       (Gtk_Widget_Record, My_Data3_Access);

     procedure My_Destroy3
       (Button : access Gtk_Widget_Record'Class;
        Data   : My_Data3_Access) is
     begin
        Destroy (Data.Button);
        Disconnect (Data.Object, Data.Id);
     end My_Destroy3;

        Id : Handler_Id;
     begin
        Data3 := new My_Data3' (Object => Gtk_Widget (Button1),
                                Button => Gtk_Widget (Button2),
                                Id     => (Null_Signal_Id, null));
        Id := User_Callback3.Connect
          (Button1, "clicked",
           User_Callback3.To_Marshaller (My_Destroy3'Access),
           Data3);
        Data3.Id := Id;
     end;

Fourth case: setting a watch on a specific widget
-------------------------------------------------

GtkAda provides a function `Add_Watch`, that will automatically
disconnect a callback when a given widget is destroyed. This is the
function used internally by `Object_Connect`. In the example
below, the callback is automatically disconnected whenever
`Button2` is destroyed::

     procedure My_Destroy2
       (Button : access Gtk_Widget_Record'Class; Data : Gtk_Widget) is
     begin
        Destroy (Data);
     end My_Destroy2;

        Id : Handler_Id;
     begin
        Id := User_Callback.Connect
          (Button1, "clicked",
           User_Callback.To_Marshaller (My_Destroy2'Access),
           Gtk_Widget (Button2));
        Add_Watch (Id, Button2);
     end;