GSignal

void gperl_signal_set_marshaller_for (GType instance_type, char * detailed_signal, GClosureMarshal marshaller)

You need this function only in rare cases, usually as workarounds for bad signal parameter types or to implement writable arguments. Use the given marshaller to marshal all handlers for detailed_signal on instance_type. gperl_signal_connect will look for marshallers registered here, and apply them to the GPerlClosure it creates for the given callback being connected.

A canonical form of detailed_signal will be used so that marshaller is applied for all possible spellings of the signal name.

Use the helper macros in gperl_marshal.h to help write your marshaller function. That header, which is installed with the Glib module but not #included through gperl.h, includes commentary and examples which you should follow closely to avoid nasty bugs. Use the Source, Luke.

WARNING: Bend over backwards and turn your head around 720 degrees before attempting to write a GPerlClosure marshaller without using the macros in gperl_marshal.h. If you absolutely cannot use those macros, be certain to understand what those macros do so you can get the semantics correct, and keep your code synchronized with them, or you may miss very important bugfixes.

gulong gperl_signal_connect (SV * instance, char * detailed_signal, SV * callback, SV * data, GConnectFlags flags)

The actual workhorse behind GObject::signal_connect, the binding for g_signal_connect, for use from within XS. This creates a GPerlClosure wrapper for the given callback and data, and connects that closure to the signal named detailed_signal on the given GObject instance. This is only good for named signals. flags is the same as for g_signal_connect(). data may be NULL, but callback must not be.

Returns the id of the installed callback.

DESCRIPTION

This page describes some functions related to signals in Glib. Since most things you can do with signals are tied to Glib::Object instances, the majority of the signal functions are documented there.

Thread safety

Some libraries, most notably GStreamer, sometimes invoke signal handlers from a foreign thread that has no Perl interpreter associated with it. When this happens, we have no choice but to hand the marshalling over to the main loop which in turn later wakes up the main thread and lets it handle the request. We cannot invoke the signal handler from the foreign thread since the Perl interpreter may not be used concurrently.

The downside to this approach is that the foreign thread is blocked until the main thread has finished executing the signal handler. This might lead to deadlocks. It might help in this case to wrap the crucial parts of the signal handler inside a Glib::Idle callback so that the signal handler can return directly.

Emit the signal name on $object. The number and types of additional arguments in ... are determined by the signal; similarly, the presence and type of return value depends on the signal being emitted.

See also Glib::Type::list_signals, which returns the same kind of hash refs as this does.

Since 1.080.

signal_name

The name of the signal being emitted.

detail

The detail passed on for this emission. For example, a notify signal will have the property name as the detail.

run_type

The current stage of signal emission, one of "run-first", "run-last", or "run-cleanup".

The $hook_func should be reference to a subroutine that looks something like this:

  sub emission_hook {
      my ($invocation_hint, $parameters, $hook_data) = @_;
      # $parameters is a reference to the @_ to be passed to
      # signal handlers, including the instance as $parameters->[0].
      return $stay_connected;  # boolean
  }

This function returns an id that can be used with remove_emission_hook.

Since 1.100.

Since 1.100.

Register callback to be called on each emission of $detailed_signal. Returns an identifier that may be used to remove this handler with $object->signal_handler_disconnect.

Like signal_connect, except that $callback will be run after the default handler.

Like signal_connect, except that $data and $object will be swapped on invocation of $callback.

Chain up to an overridden class closure; it is only valid to call this from a class closure override.

Translation: because of various details in how GObjects are implemented, the way to override a virtual method on a GObject is to provide a new "class closure", or default handler for a signal. This happens when a class is registered with the type system (see Glib::Type::register and Glib::Object::Subclass). When called from inside such an override, this method runs the overridden class closure. This is equivalent to calling $self->SUPER::$method (@_) in normal Perl objects.