GSignalGroup

GSignalGroup — Manage a collection of signals on a GObject

Functions

Properties

GObject * target Read / Write
GType * target-type Read / Write / Construct Only

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GSignalGroup

Includes

#include <glib-object.h>
#include <gobject/gvaluecollector.h>

Description

GSignalGroup manages to simplify the process of connecting many signals to a GObject as a group. As such there is no API to disconnect a signal from the group.

In particular, this allows you to:

  • Change the target instance, which automatically causes disconnection of the signals from the old instance and connecting to the new instance.

  • Block and unblock signals as a group

  • Ensuring that blocked state transfers across target instances.

One place you might want to use such a structure is with GtkTextView and GtkTextBuffer. Often times, you'll need to connect to many signals on GtkTextBuffer from a GtkTextView subclass. This allows you to create a signal group during instance construction, simply bind the “buffer” property to “target” and connect all the signals you need. When the “buffer” property changes all of the signals will be transitioned correctly.

Functions

g_signal_group_block ()

void
g_signal_group_block (GSignalGroup *self);

Blocks all signal handlers managed by self so they will not be called during any signal emissions. Must be unblocked exactly the same number of times it has been blocked to become active again.

This blocked state will be kept across changes of the target instance.

Parameters

self

the GSignalGroup

 

Since: 2.72


g_signal_group_connect ()

void
g_signal_group_connect (GSignalGroup *self,
                        const gchar *detailed_signal,
                        GCallback c_handler,
                        gpointer data);

Connects c_handler to the signal detailed_signal on the target instance of self .

You cannot connect a signal handler after “target” has been set.

[skip]

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form "signal-name::detail"

 

c_handler

the GCallback to connect.

[scope notified]

data

the data to pass to c_handler calls

 

Since: 2.72


g_signal_group_connect_after ()

void
g_signal_group_connect_after (GSignalGroup *self,
                              const gchar *detailed_signal,
                              GCallback c_handler,
                              gpointer data);

Connects c_handler to the signal detailed_signal on the target instance of self .

The c_handler will be called after the default handler of the signal.

You cannot connect a signal handler after “target” has been set.

[skip]

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form "signal-name::detail"

 

c_handler

the GCallback to connect.

[scope notified]

data

the data to pass to c_handler calls

 

Since: 2.72


g_signal_group_connect_data ()

void
g_signal_group_connect_data (GSignalGroup *self,
                             const gchar *detailed_signal,
                             GCallback c_handler,
                             gpointer data,
                             GClosureNotify notify,
                             GConnectFlags flags);

Connects c_handler to the signal detailed_signal on the target instance of self .

You cannot connect a signal handler after “target” has been set.

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form "signal-name::detail"

 

c_handler

the GCallback to connect.

[scope notified][closure data][destroy notify]

data

the data to pass to c_handler calls

 

notify

function to be called when disposing of self

 

flags

the flags used to create the signal connection

 

Since: 2.72


g_signal_group_connect_object ()

void
g_signal_group_connect_object (GSignalGroup *self,
                               const gchar *detailed_signal,
                               GCallback c_handler,
                               gpointer object,
                               GConnectFlags flags);

Connects c_handler to the signal detailed_signal on “target”.

Ensures that the object stays alive during the call to c_handler by temporarily adding a reference count. When the object is destroyed the signal handler will automatically be removed.

You cannot connect a signal handler after “target” has been set.

[skip]

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form signal-name with optional ::signal-detail

 

c_handler

the GCallback to connect.

[scope notified]

object

the GObject to pass as data to c_handler calls.

[not nullable][transfer none]

flags

GConnectFlags for the signal connection

 

Since: 2.72


g_signal_group_connect_swapped ()

void
g_signal_group_connect_swapped (GSignalGroup *self,
                                const gchar *detailed_signal,
                                GCallback c_handler,
                                gpointer data);

Connects c_handler to the signal detailed_signal on the target instance of self .

The instance on which the signal is emitted and data will be swapped when calling c_handler .

You cannot connect a signal handler after “target” has been set.

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form "signal-name::detail"

 

c_handler

the GCallback to connect.

[scope async]

data

the data to pass to c_handler calls

 

Since: 2.72


g_signal_group_connect_closure ()

void
g_signal_group_connect_closure (GSignalGroup *self,
                                const gchar *detailed_signal,
                                GClosure *closure,
                                gboolean after);

Connects closure to the signal detailed_signal on “target”.

You cannot connect a signal handler after “target” has been set.

Parameters

self

a GSignalGroup

 

detailed_signal

a string of the form signal-name with optional ::signal-detail

 

closure

the closure to connect.

[not nullable]

after

whether the handler should be called before or after the default handler of the signal.

 

Since: 2.74


g_signal_group_dup_target ()

gpointer
g_signal_group_dup_target (GSignalGroup *self);

Gets the target instance used when connecting signals.

Parameters

self

the GSignalGroup

 

Returns

The target instance.

[nullable][transfer full][type GObject]

Since: 2.72


g_signal_group_get_type ()

GType
g_signal_group_get_type (void);

g_signal_group_new ()

GSignalGroup *
g_signal_group_new (GType target_type);

Creates a new GSignalGroup for target instances of target_type .

Parameters

target_type

the GType of the target instance.

 

Returns

a new GSignalGroup.

[transfer full]

Since: 2.72


g_signal_group_set_target ()

void
g_signal_group_set_target (GSignalGroup *self,
                           gpointer target);

Sets the target instance used when connecting signals. Any signal that has been registered with g_signal_group_connect_object() or similar functions will be connected to this object.

If the target instance was previously set, signals will be disconnected from that object prior to connecting to target .

Parameters

self

the GSignalGroup.

 

target

The target instance used when connecting signals.

[nullable][type GObject][transfer none]

Since: 2.72


g_signal_group_unblock ()

void
g_signal_group_unblock (GSignalGroup *self);

Unblocks all signal handlers managed by self so they will be called again during any signal emissions unless it is blocked again. Must be unblocked exactly the same number of times it has been blocked to become active again.

Parameters

self

the GSignalGroup

 

Since: 2.72

Types and Values

GSignalGroup

typedef struct _GSignalGroup GSignalGroup;

GSignalGroup is an opaque structure whose members cannot be accessed directly.

Since: 2.72

Property Details

The “target” property

  “target”                   GObject *

The target instance used when connecting signals.

Owner: GSignalGroup

Flags: Read / Write

Since: 2.72


The “target-type” property

  “target-type”              GType *

The GType of the target property.

Owner: GSignalGroup

Flags: Read / Write / Construct Only

Allowed values: GObject

Since: 2.72

Signal Details

The “bind” signal

void
user_function (GSignalGroup *self,
               GObject      *instance,
               gpointer      user_data)

This signal is emitted when “target” is set to a new value other than NULL. It is similar to “notify” on target except it will not emit when “target” is NULL and also allows for receiving the GObject without a data-race.

Parameters

self

the GSignalGroup

 

instance

a GObject containing the new value for “target”

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 2.72


The “unbind” signal

void
user_function (GSignalGroup *self,
               gpointer      user_data)

This signal is emitted when the target instance of self is set to a new GObject.

This signal will only be emitted if the previous target of self is non-NULL.

Parameters

self

a GSignalGroup

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 2.72