Struct glib::SignalGroup

#[repr(transparent)]
pub struct SignalGroup { /* private fields */ }

Available on crate feature v2_74 only.

SignalGroup manages to simplify the process of connecting many signals to a Object 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 GtkTextView:buffer property to target and connect all the signals you need. When the GtkTextView:buffer property changes all of the signals will be transitioned correctly.

Properties

target

The target instance used when connecting signals.

Readable | Writeable

target-type

The GType of the target property.

Readable | Writeable | Construct Only

Signals

bind

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

unbind

This signal is emitted when the target instance of self_ is set to a new Object.

This signal will only be emitted if the previous target of self_ is non-None.

Implements

ObjectExt

Implementations

impl SignalGroup

pub fn new(target_type: Type) -> SignalGroup

Creates a new SignalGroup for target instances of target_type.

target_type

the GType of the target instance.

Returns

a new SignalGroup

pub fn block(&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.

pub fn target(&self) -> Option<Object>

pub fn set_target(&self, target: Option<&impl IsA<Object>>)

pub fn unblock(&self)

pub fn target_type(&self) -> Type

Available on crate feature v2_72 only.

The GType of the target property.

impl SignalGroup

pub fn connect_closure( &self, signal_name: &str, after: bool, closure: RustClosure )

pub fn connect<F>(&self, signal_name: &str, after: bool, callback: F)where F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static,

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

You cannot connect a signal handler afterReturns the depth of the stack of calls to MainContext::dispatch() on any MainContext in the current thread. That is, when called from the toplevel, it gives 0. When called from within a callback from MainContext::iteration() (or MainLoop::run(), etc.) it returns 1. When called from within a callback to a recursive call to MainContext::iteration(), it returns 2. And so forth.

This function is useful in a situation like the following: Imagine an extremely simple “garbage collected” system.

⚠️ The following code is in C ⚠️

static GList *free_list;

gpointer
allocate_memory (gsize size)
{
  gpointer result = g_malloc (size);
  free_list = g_list_prepend (free_list, result);
  return result;
}

void
free_allocated_memory (void)
{
  GList *l;
  for (l = free_list; l; l = l->next);
    g_free (l->data);
  g_list_free (free_list);
  free_list = NULL;
 }

[...]

while (TRUE);
 {
   g_main_context_iteration (NULL, TRUE);
   free_allocated_memory();
  }

This works from an application, however, if you want to do the same thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to free_allocated_memory(), but that doesn’t work, since the idle function could be called from a recursive callback. This can be fixed by using main_depth()

⚠️ The following code is in C ⚠️

gpointer
allocate_memory (gsize size)
{
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block->mem = g_malloc (size);
  block->depth = g_main_depth ();
  free_list = g_list_prepend (free_list, block);
  return block->mem;
}

void
free_allocated_memory (void)
{
  GList *l;

  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
  SignalGroup::fn connect_unbind -->
This signal is emitted when the target instance of `self_` is set to a
new [`Object`][crate::Object].

This signal will only be emitted if the previous target of `self_` is
non-[`None`].

pub fn connect_local<F>(&self, signal_name: &str, after: bool, callback: F)where F: Fn(&[Value]) -> Option<Value> + 'static,

Like Self::connect but doesn’t require a Send+Sync closure. Signal emission will panic if the signal on the current target is emitted from a different thread from the thread that connected the signal.

pub fn connect_notify<F>(&self, name: Option<&str>, callback: F)where F: Fn(&Object, &ParamSpec) + Send + Sync + 'static,

pub fn connect_notify_local<F>(&self, name: Option<&str>, callback: F)where F: Fn(&Object, &ParamSpec) + 'static,

pub fn connect_bind<F: Fn(&Self, &Object) + Send + Sync + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_bind_local<F: Fn(&Self, &Object) + 'static>( &self, f: F ) -> SignalHandlerId

Like Self::connect_bind but doesn’t require a Send+Sync closure. Signal emission will panic if the signal is emitted from a different thread from the thread that connected the signal.

pub fn connect_unbind<F: Fn(&Self) + Send + Sync + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_unbind_local<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Like Self::connect_unbind but doesn’t require a Send+Sync closure. Signal emission will panic if the signal is emitted from a different thread from the thread that connected the signal.

Trait Implementations

impl Clone for SignalGroup

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SignalGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SignalGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for SignalGroup

type ParamSpec = ParamSpecObject

type SetValue = SignalGroup

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, SignalGroup>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for SignalGroup

fn hash<H>(&self, state: &mut H)where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SignalGroup

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for SignalGroup

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for SignalGroup

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for SignalGroup

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for SignalGroup

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for SignalGroup

impl Send for SignalGroup

impl Sync for SignalGroup