gi-gobject-2.0.31: GObject bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GObject.Objects.SignalGroup

Contents

- Exported types
- Methods
  - block
  - connectClosure
  - connectData
  - connectSwapped
  - dupTarget
  - new
  - setTarget
  - unblock
- Properties
  - target
  - targetType
- Signals
  - bind
  - unbind

Description

`GSignalGroup` manages a collection of signals on a `GObject`.

`GSignalGroup` simplifies 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 `GtkTextView:buffer` property to `GSignalGroup:target` and connect all the signals you need. When the `GtkTextView:buffer` property changes all of the signals will be transitioned correctly.

Since: 2.72

Synopsis

- newtype SignalGroup = SignalGroup (ManagedPtr SignalGroup)
- class (GObject o, IsDescendantOf SignalGroup o) => IsSignalGroup o
- toSignalGroup :: (MonadIO m, IsSignalGroup o) => o -> m SignalGroup
- signalGroupBlock :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> m ()
- signalGroupConnectClosure :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> Text -> GClosure b -> Bool -> m ()
- signalGroupConnectData :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> Text -> Callback -> [ConnectFlags] -> m ()
- signalGroupConnectSwapped :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> Text -> Callback -> m ()
- signalGroupDupTarget :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> m (Maybe Object)
- signalGroupNew :: (HasCallStack, MonadIO m) => GType -> m SignalGroup
- signalGroupSetTarget :: (HasCallStack, MonadIO m, IsSignalGroup a, IsObject b) => a -> Maybe b -> m ()
- signalGroupUnblock :: (HasCallStack, MonadIO m, IsSignalGroup a) => a -> m ()
- clearSignalGroupTarget :: (MonadIO m, IsSignalGroup o) => o -> m ()
- constructSignalGroupTarget :: (IsSignalGroup o, MonadIO m, IsObject a) => a -> m (GValueConstruct o)
- getSignalGroupTarget :: (MonadIO m, IsSignalGroup o) => o -> m (Maybe Object)
- setSignalGroupTarget :: (MonadIO m, IsSignalGroup o, IsObject a) => o -> a -> m ()
- constructSignalGroupTargetType :: (IsSignalGroup o, MonadIO m) => GType -> m (GValueConstruct o)
- getSignalGroupTargetType :: (MonadIO m, IsSignalGroup o) => o -> m GType
- type SignalGroupBindCallback = Object -> IO ()
- afterSignalGroupBind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupBindCallback) -> m SignalHandlerId
- onSignalGroupBind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupBindCallback) -> m SignalHandlerId
- type SignalGroupUnbindCallback = IO ()
- afterSignalGroupUnbind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupUnbindCallback) -> m SignalHandlerId
- onSignalGroupUnbind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupUnbindCallback) -> m SignalHandlerId

# Exported types

newtype SignalGroup Source #

Memory-managed wrapper type.

Constructors

SignalGroup (ManagedPtr SignalGroup) |

#### Instances

Instances details

Eq SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup Methods (==) :: SignalGroup -> SignalGroup -> Bool Source # (/=) :: SignalGroup -> SignalGroup -> Bool Source #
GObject SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup
ManagedPtrNewtype SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup Methods toManagedPtr :: SignalGroup -> ManagedPtr SignalGroup Source #
TypedObject SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup Methods glibType :: IO GType Source #
HasParentTypes SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup
IsGValue (Maybe SignalGroup) Source # | Convert `SignalGroup` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GObject.Objects.SignalGroup Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe SignalGroup -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe SignalGroup) Source #
type ParentTypes SignalGroup Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup type ParentTypes SignalGroup = '[Object]

class (GObject o, IsDescendantOf SignalGroup o) => IsSignalGroup o Source #

Type class for types which can be safely cast to `SignalGroup`, for instance with `toSignalGroup`.

#### Instances

Instances details

(GObject o, IsDescendantOf SignalGroup o) => IsSignalGroup o Source # |
Instance details Defined in GI.GObject.Objects.SignalGroup

toSignalGroup :: (MonadIO m, IsSignalGroup o) => o -> m SignalGroup Source #

Cast to `SignalGroup`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, block, connectClosure, connectData, connectSwapped, dupTarget, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unblock, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty, setTarget.

## block

signalGroupBlock Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: the `SignalGroup`
-> m () |

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.

Since: 2.72

## connectClosure

signalGroupConnectClosure Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: a `SignalGroup`
-> Text | `detailedSignal`: a string of the form `signal-name` with optional `::signal-detail`
-> GClosure b | `closure`: the closure to connect.
-> Bool | `after`: whether the handler should be called before or after the default handler of the signal.
-> m () |

Connects `closure` to the signal `detailedSignal` on SignalGroup:target.

You cannot connect a signal handler after SignalGroup:target has been set.

Since: 2.74

## connectData

signalGroupConnectData Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: a `SignalGroup`
-> Text | `detailedSignal`: a string of the form "signal-namedetail"
-> Callback | `cHandler`: the `Callback` to connect
-> [ConnectFlags] | `flags`: the flags used to create the signal connection
-> m () |

Connects `cHandler` to the signal `detailedSignal` on the target instance of `self`.

You cannot connect a signal handler after SignalGroup:target has been set.

Since: 2.72

## connectSwapped

signalGroupConnectSwapped Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: a `SignalGroup`
-> Text | `detailedSignal`: a string of the form "signal-namedetail"
-> Callback | `cHandler`: the `Callback` to connect
-> m () |

Connects `cHandler` to the signal `detailedSignal` on the target instance of `self`.

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

You cannot connect a signal handler after SignalGroup:target has been set.

Since: 2.72

## dupTarget

signalGroupDupTarget Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: the `SignalGroup`
-> m (Maybe Object) | Returns: The target instance

Gets the target instance used when connecting signals.

Since: 2.72

## new

signalGroupNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GType | `targetType`: the `GType` of the target instance.
-> m SignalGroup | Returns: a new `SignalGroup`

Creates a new `SignalGroup` for target instances of `targetType`.

Since: 2.72

## setTarget

signalGroupSetTarget Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a, IsObject b) |
=> a | `self`: the `SignalGroup`.
-> Maybe b | `target`: The target instance used when connecting signals.
-> m () |

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`.

Since: 2.72

## unblock

signalGroupUnblock Source #

Arguments

:: (HasCallStack, MonadIO m, IsSignalGroup a) |
=> a | `self`: the `SignalGroup`
-> m () |

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.

Since: 2.72

# Properties

## target

The target instance used when connecting signals.

Since: 2.72

clearSignalGroupTarget :: (MonadIO m, IsSignalGroup o) => o -> m () Source #

Set the value of the “`target`” property to `Nothing`. When overloading is enabled, this is equivalent to

    clear #target

constructSignalGroupTarget :: (IsSignalGroup o, MonadIO m, IsObject a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`target`” property. This is rarely needed directly, but it is used by `new`.

getSignalGroupTarget :: (MonadIO m, IsSignalGroup o) => o -> m (Maybe Object) Source #

Get the value of the “`target`” property. When overloading is enabled, this is equivalent to

    get signalGroup #target

setSignalGroupTarget :: (MonadIO m, IsSignalGroup o, IsObject a) => o -> a -> m () Source #

Set the value of the “`target`” property. When overloading is enabled, this is equivalent to

    set signalGroup [ #target := value ]

## targetType

The `GType` of the target property.

Since: 2.72

constructSignalGroupTargetType :: (IsSignalGroup o, MonadIO m) => GType -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`target-type`” property. This is rarely needed directly, but it is used by `new`.

getSignalGroupTargetType :: (MonadIO m, IsSignalGroup o) => o -> m GType Source #

Get the value of the “`target-type`” property. When overloading is enabled, this is equivalent to

    get signalGroup #targetType

# Signals

## bind

type SignalGroupBindCallback Source #

Arguments

= Object | `instance`: a `Object` containing the new value for SignalGroup:target
-> IO () |

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

Since: 2.72

afterSignalGroupBind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupBindCallback) -> m SignalHandlerId Source #

Connect a signal handler for the bind signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after signalGroup #bind callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onSignalGroupBind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupBindCallback) -> m SignalHandlerId Source #

Connect a signal handler for the bind signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on signalGroup #bind callback

## unbind

type SignalGroupUnbindCallback = IO () Source #

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-`Nothing`.

Since: 2.72

afterSignalGroupUnbind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupUnbindCallback) -> m SignalHandlerId Source #

Connect a signal handler for the unbind signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after signalGroup #unbind callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onSignalGroupUnbind :: (IsSignalGroup a, MonadIO m) => a -> ((?self :: a) => SignalGroupUnbindCallback) -> m SignalHandlerId Source #

Connect a signal handler for the unbind signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on signalGroup #unbind callback