Next: , Previous: Package_Gtk.Main, Up: Top



Package Gtk.Marshallers

This package provides a set of generic packages to easily create some Marshallers. Although this package has been designed to be easily reusable, its primary aim is to simplify the use of callbacks.

Note that most users don't need to understand or even look at this package, since the main functions are also renamed in the Gtk.Handlers package (They are called To_Marshaller). This package is rather complex (generic packages inside generic packages), and thus you should understand correctly how Gtk.Handlers work before looking at this one.

To understand the paradigm used in this package, some definitions are necessary:

A Handler, or Callback, is a subprogram provided by the user. This handler, when attached to a particular object, will be called when certain events happen during the life of this object. All handlers take as a first argument an access to the object they were attached to. Depending on the signal, this handler can also have some extra parameters; most of the time, only one extra parameter will be used. For more information about Handlers, refer to the package Gtk.Handlers, where this notion is explained in more details.

A General_Handler is an access to any Handler. Note that this is a type used internally, most users should *not* be using it. It is publicly declared so that users can create new marshallers that would not be already provided here.

A Handler_Proxy is a subprogram that calls its associated handler with the appropriate arguments (from an array of arguments stored in Glib.Values.GValues)

A Marshaller is the association of a General_Handler and a Handler_Proxy.

This package is divided in four generic packages. Each package has been designed to cover a certain kind of callback by providing the associated marshallers. There are two primary factors that describe a callback, and that decide which marshaller to use: Does the callback have access to some user data? Does the callback return some value?

Depending on that, the appropriate generic package should be chosen. For example, if the callback returns a value, but does not expect user data, then the "Return_Marshallers" package should be used. More details about the usage of each package is provided individually below.

Each of these packages is in turn divided into three generic sub-packages. The organization of these subpackages is always the same : o The type "Handler" is defined. It describes the profile of the Handler covered in this generic package. o a "To_Marshaller" function is provided to build a Marshaller from any Handler. o A "Emit_By_Name" procedure is also provided to allow the user to "emit" a signal. This service is explained in more details in Gtk.Handlers. o A private function "Call" is also defined. This is the actual Handler_Proxy that will be used when creating Marshallers with the "To_Marshaller" service.

Once again, selecting the right generic sub-package depends on the callback. For instance, the first sub-package, always called "Generic_Marshaller", is to be used when the handler has one extra argument which is a simple non-tagged type. More details about the usage of each sub-package is also provided individually.

Although most of the cases are covered by the packages below, some unusual cases may appear. This is the case for example when the callback accepts several extra parameters. In such cases, two options are available: The first option is to use the "standard" callback mechanism with one parameter, this parameter being an array of arguments that you will parse yourself. The second option is to create a new Marshaller package. This is more interesting if more than one callback will follow the same pattern. The body of this package can be used as a good model to build such new marshallers. See also the example in the GtkAda distribution for how to create your own marshallers.