Description

This class is a helper class to support methods which do not fit in Gnome::GObject::Object. It mostly deals with signals. Most important method used all the time is .register-signal().

register-signal

Register a handler to process a signal or an event. There are several types of callbacks which can be handled by this registration. They can be controlled by using a named argument with a special name.

method register-signal (
  $handler-object, Str:D $handler-name,
  Str:D $signal-name, *%user-options
  --> Int
)

• $handler-object; The object wherein the handler is defined.

• $handler-name; The name of the method.

• $signal-name; The name of the event to be handled. Each gtk object has its own series of signals.

• :$_handler-id; The handler id which is returned from the registration

• :$_native-object; The native object provided by the caller.

• %user-options; Any other user data in whatever type provided as one or more named arguments. These arguments are provided to the user handler when an event for the handler is fired. The names starting with '_' are reserved to provide other info to the user.

  The following reserved named arguments are available;

  method some-button-click-handler (
    …,
    Gnome::Gtk3::Button() :_native-object($button)
  ) {
    …
  }
  

The method returns a handler id which can be used for example to disconnect the callback later.

Callback handlers

• Simple handlers; e.g. a click event handler has only named arguments and are optional.

• Complex handlers (only a bit) also have positional arguments and MUST be typed because they are checked to create a signature for the call to a native subroutine. You can use the raku native types like int32 but several types are automatically converted to native types. The types such as gboolean, etc are defined in Gnome::N::GlibToRakuTypes.

  Raku type	Native glib type	Native Raku type
  Bool	gboolean	int32
  UInt	guint	uint32/uint64
  Int	gint	int32/int64
  Num	gfloat	num32
  Rat	gdouble	num64

• Some handlers must return a value and is used by the calling process. You MUST describe this too in the andlers API, otherwise the returned value is thrown away.

• Any user options are provided via named arguments from the call to register-signal().

Example 1

An example of a registration and the handlers signature to handle a button click event.

# Handler class with callback methods
class ButtonHandlers {
  method click-button (
    Gnome::Gtk3::Button() :_native-object($button),
    Int :$_handler_id, :$my-option ) {
    …
  }
}

$button.register-signal(
  ButtonHandlers.new, 'click-button', 'clicked', :my-option(…)
);