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

Contents

- Exported types
- Methods
  - getBlurb
  - getDefaultValue
  - getName
  - getNameQuark
  - getNick
  - getQdata
  - getRedirectTarget
  - isValidName
  - setQdata
  - sink
  - stealQdata

Description

`GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties.

## Parameter names

A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as for signal naming (see `GObject.signal_new`).

When creating and looking up a `GParamSpec`, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using `_` is discouraged.

Synopsis

- newtype ParamSpec = ParamSpec (ManagedPtr ParamSpec)
- class (BoxedPtr o, TypedObject o, IsDescendantOf ParamSpec o) => IsParamSpec o
- toParamSpec :: (MonadIO m, IsParamSpec o) => o -> m ParamSpec
- paramSpecGetBlurb :: (HasCallStack, MonadIO m) => GParamSpec -> m (Maybe Text)
- paramSpecGetDefaultValue :: (HasCallStack, MonadIO m) => GParamSpec -> m GValue
- paramSpecGetName :: (HasCallStack, MonadIO m) => GParamSpec -> m Text
- paramSpecGetNameQuark :: (HasCallStack, MonadIO m) => GParamSpec -> m Word32
- paramSpecGetNick :: (HasCallStack, MonadIO m) => GParamSpec -> m Text
- paramSpecGetQdata :: (HasCallStack, MonadIO m) => GParamSpec -> Word32 -> m (Ptr ())
- paramSpecGetRedirectTarget :: (HasCallStack, MonadIO m) => GParamSpec -> m (Maybe GParamSpec)
- paramSpecIsValidName :: (HasCallStack, MonadIO m) => Text -> m Bool
- paramSpecSetQdata :: (HasCallStack, MonadIO m) => GParamSpec -> Word32 -> Ptr () -> m ()
- paramSpecSink :: (HasCallStack, MonadIO m) => GParamSpec -> m ()
- paramSpecStealQdata :: (HasCallStack, MonadIO m) => GParamSpec -> Word32 -> m (Ptr ())

# Exported types

newtype ParamSpec Source #

Memory-managed wrapper type.

Constructors

ParamSpec (ManagedPtr ParamSpec) |

#### Instances

Instances details

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

class (BoxedPtr o, TypedObject o, IsDescendantOf ParamSpec o) => IsParamSpec o Source #

Type class for types which can be safely cast to `ParamSpec`, for instance with `toParamSpec`.

#### Instances

Instances details

(BoxedPtr o, TypedObject o, IsDescendantOf ParamSpec o) => IsParamSpec o Source # |
Instance details Defined in GI.GObject.Objects.ParamSpec

toParamSpec :: (MonadIO m, IsParamSpec o) => o -> m ParamSpec Source #

Cast to `ParamSpec`, 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

sink, stealQdata.

#### Getters

getBlurb, getDefaultValue, getName, getNameQuark, getNick, getQdata, getRedirectTarget.

#### Setters

setQdata.

## getBlurb

paramSpecGetBlurb Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a valid `ParamSpec`
-> m (Maybe Text) | Returns: the short description of `pspec`.

Get the short description of a `ParamSpec`.

## getDefaultValue

paramSpecGetDefaultValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a `ParamSpec`
-> m GValue | Returns: a pointer to a `Value` which must not be modified

Gets the default value of `pspec` as a pointer to a `Value`.

The `Value` will remain valid for the life of `pspec`.

Since: 2.38

## getName

paramSpecGetName Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a valid `ParamSpec`
-> m Text | Returns: the name of `pspec`.

Get the name of a `ParamSpec`.

The name is always an "interned" string (as per `internString`). This allows for pointer-value comparisons.

## getNameQuark

paramSpecGetNameQuark Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a `ParamSpec`
-> m Word32 | Returns: the GQuark for `pspec`->name.

Gets the GQuark for the name.

Since: 2.46

## getNick

paramSpecGetNick Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a valid `ParamSpec`
-> m Text | Returns: the nickname of `pspec`.

Get the nickname of a `ParamSpec`.

## getQdata

paramSpecGetQdata Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a valid `ParamSpec`
-> Word32 | `quark`: a `GQuark`, naming the user data pointer
-> m (Ptr ()) | Returns: the user data pointer set, or `Nothing`

Gets back user data pointers stored via `paramSpecSetQdata`.

## getRedirectTarget

paramSpecGetRedirectTarget Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a `ParamSpec`
-> m (Maybe GParamSpec) | Returns: paramspec to which requests on this paramspec should be redirected, or `Nothing` if none.

If the paramspec redirects operations to another paramspec, returns that paramspec. Redirect is used typically for providing a new implementation of a property in a derived type while preserving all the properties from the parent type. Redirection is established by creating a property of type `ParamSpecOverride`. See `objectClassOverrideProperty` for an example of the use of this capability.

Since: 2.4

## isValidName

paramSpecIsValidName Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `name`: the canonical name of the property
-> m Bool | Returns: `True` if `name` is a valid property name, `False` otherwise.

Validate a property name for a `ParamSpec`. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them.

See [canonical parameter names][class`gObject`.ParamSpec`parameter`-names] for details of the rules for valid names.

Since: 2.66

## setQdata

paramSpecSetQdata Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: the `ParamSpec` to set store a user data pointer
-> Word32 | `quark`: a `GQuark`, naming the user data pointer
-> Ptr () | `data`: an opaque user data pointer
-> m () |

Sets an opaque, named pointer on a `ParamSpec`. The name is specified through a `GQuark` (retrieved e.g. via `quarkFromStaticString`), and the pointer can be gotten back from the `pspec` with `paramSpecGetQdata`. Setting a previously set user data pointer, overrides (frees) the old pointer set, using `Nothing` as pointer essentially removes the data stored.

## sink

paramSpecSink Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: a valid `ParamSpec`
-> m () |

The initial reference count of a newly created `ParamSpec` is 1, even though no one has explicitly called `g_param_spec_ref()` on it yet. So the initial reference count is flagged as "floating", until someone calls `g_param_spec_ref (pspec); g_param_spec_sink (pspec);` in sequence on it, taking over the initial reference count (thus ending up with a `pspec` that has a reference count of 1 still, but is not flagged "floating" anymore).

## stealQdata

paramSpecStealQdata Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GParamSpec | `pspec`: the `ParamSpec` to get a stored user data pointer from
-> Word32 | `quark`: a `GQuark`, naming the user data pointer
-> m (Ptr ()) | Returns: the user data pointer set, or `Nothing`

Gets back user data pointers stored via `paramSpecSetQdata` and removes the `data` from `pspec` without invoking its `destroy()` function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier.