haskell-gi-base-0.26.9: Foundation for libraries generated by haskell-gi

Safe Haskell | None
Language | Haskell2010

Data.GI.Base.Signals

Description

Routines for connecting `GObject`s to signals. There are two basic variants, `on` and `after`, which correspond to g_signal_connect and g_signal_connect_after, respectively.

Basic usage is

     on widget #signalName $ do ...

or

     after widget #signalName $ do ...

Note that in the Haskell bindings we represent the signal name in camelCase, so a signal like script-message-received in the original API becomes scriptMessageReceived in the bindings.

There are two variants of note. If you want to provide a detail when connecting the signal you can use `:::`, as follows:

     on widget (#scriptMessageReceived ::: "handlerName") $ do ...

On the other hand, if you want to connect to the "notify" signal for a property of a widget, it is recommended to use instead `PropertyNotify`, as follows:

     on widget (PropertyNotify #propertyName) $ do ...

which has the advantage that it will be checked at compile time that the widget does indeed have the property "`propertyName`".

Synopsis

- on :: forall object info m. (GObject object, MonadIO m, SignalInfo info) => object -> SignalProxy object info -> ((?self :: object) => HaskellCallbackType info) -> m SignalHandlerId
- after :: forall object info m. (GObject object, MonadIO m, SignalInfo info) => object -> SignalProxy object info -> ((?self :: object) => HaskellCallbackType info) -> m SignalHandlerId
- data SignalProxy object info where
  - SignalProxy :: forall object info. SignalProxy object info
  - (:::) :: forall object info. SignalProxy object info -> Text -> SignalProxy object info
  - PropertyNotify :: forall info1 (propName :: Symbol) object (pl :: Symbol). (info1 ~ ResolveAttribute propName object, AttrInfo info1, pl ~ AttrLabel info1, KnownSymbol pl) => AttrLabelProxy propName -> SignalProxy object GObjectNotifySignalInfo
  - PropertySet :: forall info1 (propName :: Symbol) object b (pl :: Symbol). (info1 ~ ResolveAttribute propName object, AttrInfo info1, AttrBaseTypeConstraint info1 object, b ~ AttrGetType info1, pl ~ AttrLabel info1, KnownSymbol pl) => AttrLabelProxy propName -> SignalProxy object (GObjectPropertySetSignalInfo b)
- data SignalConnectMode
  - = SignalConnectBefore
  - | SignalConnectAfter
- connectSignalFunPtr :: GObject o => o -> Text -> FunPtr a -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId
- disconnectSignalHandler :: GObject o => o -> SignalHandlerId -> IO ()
- type SignalHandlerId = CULong
- class SignalInfo info where
  - type HaskellCallbackType info
  - connectSignal :: GObject o => o -> (o -> HaskellCallbackType info) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId
  - dbgSignalInfo :: Maybe ResolvedSymbolInfo
- data GObjectNotifySignalInfo
- type family SignalCodeGenError (signalName :: Symbol) where ...
- resolveSignal :: (GObject object, SignalInfo info) => object -> SignalProxy object info -> Maybe ResolvedSymbolInfo
- connectGObjectNotify :: GObject o => o -> (o -> GObjectNotifyCallback) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId

# Documentation

on :: forall object info m. (GObject object, MonadIO m, SignalInfo info) => object -> SignalProxy object info -> ((?self :: object) => HaskellCallbackType info) -> m SignalHandlerId Source #

Connect a signal to a signal handler.

after :: forall object info m. (GObject object, MonadIO m, SignalInfo info) => object -> SignalProxy object info -> ((?self :: object) => HaskellCallbackType info) -> m SignalHandlerId Source #

Connect a signal to a handler, running the handler after the default one.

data SignalProxy object info where Source #

Support for overloaded signal connectors.

Constructors

SignalProxy :: forall object info. SignalProxy object info | A basic signal name connector.
(:::) :: forall object info. SignalProxy object info -> Text -> SignalProxy object info | A signal connector annotated with a detail.
PropertyNotify :: forall info1 (propName :: Symbol) object (pl :: Symbol). (info1 ~ ResolveAttribute propName object, AttrInfo info1, pl ~ AttrLabel info1, KnownSymbol pl) => AttrLabelProxy propName -> SignalProxy object GObjectNotifySignalInfo | A signal connector for the `notify` signal on the given property.

PropertySet :: forall info1 (propName :: Symbol) object b (pl :: Symbol). (info1 ~ ResolveAttribute propName object, AttrInfo info1, AttrBaseTypeConstraint info1 object, b ~ AttrGetType info1, pl ~ AttrLabel info1, KnownSymbol pl) => AttrLabelProxy propName -> SignalProxy object (GObjectPropertySetSignalInfo b)

A signal connector for the `notify` signal on the given property, similar to `PropertyNotify`, but it passes the new value of the property to the callback for convenience.

#### Instances

Instances details

info ~ ResolveSignal slot object => IsLabel slot (SignalProxy object info) Source # | Support for overloaded labels.
Instance details Defined in Data.GI.Base.Signals Methods fromLabel :: SignalProxy object info Source #

data SignalConnectMode Source #

Whether to connect a handler to a signal with `connectSignal` so that it runs before/after the default handler for the given signal.

Constructors

SignalConnectBefore | Run before the default handler.
SignalConnectAfter | Run after the default handler.

connectSignalFunPtr :: GObject o => o -> Text -> FunPtr a -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId Source #

Connect a signal to a handler, given as a `FunPtr`.

disconnectSignalHandler :: GObject o => o -> SignalHandlerId -> IO () Source #

Disconnect a previously connected signal.

type SignalHandlerId = CULong Source #

Type of a `GObject` signal handler id.

class SignalInfo info where Source #

Information about an overloaded signal.

Minimal complete definition

connectSignal

Associated Types

type HaskellCallbackType info Source #

The type for the signal handler.

Methods

connectSignal :: GObject o => o -> (o -> HaskellCallbackType info) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId Source #

Connect a Haskell function to a signal of the given `GObject`, specifying whether the handler will be called before or after the default handler. Note that the callback being passed here admits an extra initial parameter with respect to the usual Haskell callback type. This will be passed as an implicit `?self` argument to the Haskell callback.

dbgSignalInfo :: Maybe ResolvedSymbolInfo Source #

Optional extra debug information, for `resolveSignal` below.

#### Instances

Instances details

SignalInfo GObjectNotifySignalInfo Source # |

Instance details

Defined in Data.GI.Base.Signals

Associated Types

type HaskellCallbackType GObjectNotifySignalInfo |
Instance details Defined in Data.GI.Base.Signals type HaskellCallbackType GObjectNotifySignalInfo

Methods

connectSignal :: GObject o => o -> (o -> HaskellCallbackType GObjectNotifySignalInfo) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId Source #

dbgSignalInfo :: Maybe ResolvedSymbolInfo Source #

data GObjectNotifySignalInfo Source #

Connection information for a "notify" signal indicating that a specific property changed (see `PropertyNotify` for the relevant constructor).

#### Instances

Instances details

SignalInfo GObjectNotifySignalInfo Source # |

Instance details

Defined in Data.GI.Base.Signals

Associated Types

type HaskellCallbackType GObjectNotifySignalInfo |
Instance details Defined in Data.GI.Base.Signals type HaskellCallbackType GObjectNotifySignalInfo

Methods

connectSignal :: GObject o => o -> (o -> HaskellCallbackType GObjectNotifySignalInfo) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId Source #

dbgSignalInfo :: Maybe ResolvedSymbolInfo Source #

type HaskellCallbackType GObjectNotifySignalInfo Source # |
Instance details Defined in Data.GI.Base.Signals type HaskellCallbackType GObjectNotifySignalInfo

type family SignalCodeGenError (signalName :: Symbol) where ... Source #

Generate an informative type error whenever one tries to use a signal for which code generation has failed.

Equations

SignalCodeGenError signalName = TypeError ((('Text "The signal \8216" ':<>: 'Text signalName) ':<>: 'Text "\8217 is not supported, because haskell-gi failed to generate appropriate bindings.") ':$$: 'Text "Please file an issue at https://github.com/haskell-gi/haskell-gi/issues.") :: Type |

resolveSignal :: (GObject object, SignalInfo info) => object -> SignalProxy object info -> Maybe ResolvedSymbolInfo Source #

Return the fully qualified signal name that a given overloaded signal resolves to (mostly useful for debugging).

    resolveSignal #childNotify button

connectGObjectNotify :: GObject o => o -> (o -> GObjectNotifyCallback) -> SignalConnectMode -> Maybe Text -> IO SignalHandlerId Source #

Connect the given notify callback for a GObject.