Safe Haskell | None |
---|---|
Language | Haskell98 |
Basic attributes interface
Attributes of an object can be get, set and constructed. For types
descending from GObject
, properties are
encoded in attributes, although attributes are slightly more
general (every property of a GObject
is an
attribute, but we can also have attributes for types not descending
from GObject
).
As an example consider a button
widget and a property (of the
Button class, or any of its parent classes or implemented
interfaces) called "label". The simplest way of getting the value
of the button is to do
value <- getButtonLabel button
And for setting:
setButtonLabel button label
This mechanism quickly becomes rather cumbersome, for example for setting the "window" property in a DOMDOMWindow in WebKit:
win <- getDOMDOMWindowWindow dom
and perhaps more importantly, one needs to chase down the type which introduces the property:
setWidgetSensitive button False
There is no setButtonSensitive
, since it is the Widget
type
that introduces the "sensitive" property.
Overloaded attributes
A much more convenient overloaded attribute resolution API is provided by this module. Getting the value of an object's attribute is straightforward:
value <- get button _label
The definition of _label
is simply a Proxy
encoding the name of
the attribute to get:
_label = Proxy :: Proxy "label"
These proxies can be automatically generated by invoking the code
generator with the -a
option. The leading underscore is simply so
the autogenerated identifiers do not pollute the namespace, but if
this is not a concern the autogenerated names (in the autogenerated
GI/Properties.hs
) can be edited as one wishes.
The syntax for setting or updating an attribute is only slightly more complex. At the simplest level it is just:
set button [ _label := value ]
or for the WebKit example above
set dom [_window := win]
However as the list notation would indicate, you can set or update multiple attributes of the same object in one go:
set button [ _label := value, _sensitive := False ]
You are not limited to setting the value of an attribute, you can also apply an update function to an attribute's value. That is the function receives the current value of the attribute and returns the new value.
set spinButton [ _value :~ (+1) ]
There are other variants of these operators, (see AttrOp
). :=>
and
:~>
and like :=
and :~
but operate in the IO
monad rather
than being pure. There is also ::=
and ::~
which take the object
as an extra parameter.
Attributes can also be set during construction of a
GObject
using new
button <- new Button [_label := "Can't touch this!", _sensitive := False]
In addition for value being set/get having to have the right type,
there can be attributes that are read-only, or that can only be set
during construction with new
, but cannot be
set
afterwards. That these invariants hold is also checked during
compile time.
- class AttrInfo info where
- type AttrAllowedOps info :: [AttrOpTag]
- type AttrSetTypeConstraint info :: * -> Constraint
- type AttrBaseTypeConstraint info :: * -> Constraint
- type AttrGetType info
- type AttrLabel info :: Symbol
- attrGet :: AttrBaseTypeConstraint info o => proxy info -> o -> IO (AttrGetType info)
- attrSet :: (AttrBaseTypeConstraint info o, AttrSetTypeConstraint info b) => proxy info -> o -> b -> IO ()
- attrConstruct :: AttrSetTypeConstraint info b => proxy info -> b -> IO (String, GValue)
- data AttrOpTag
- data AttrOp obj tag where
- (:=) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> b -> AttrOp obj tag
- (:=>) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> IO b -> AttrOp obj tag
- (:~) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (a -> b) -> AttrOp obj tag
- (:~>) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (a -> IO b) -> AttrOp obj tag
- (::=) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> (obj -> b) -> AttrOp obj tag
- (::~) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (obj -> a -> b) -> AttrOp obj tag
- get :: forall info attr obj proxy m. (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed AttrGet info, MonadIO m) => obj -> proxy (attr :: Symbol) -> m (AttrGetType info)
- set :: forall o m. MonadIO m => o -> [AttrOp o AttrSet] -> m ()
Documentation
class AttrInfo info where Source
Info describing an attribute.
type AttrAllowedOps info :: [AttrOpTag] Source
The operations that are allowed on the attribute.
type AttrSetTypeConstraint info :: * -> Constraint Source
Constraint on the value being set.
type AttrBaseTypeConstraint info :: * -> Constraint Source
Constraint on the type for which we are allowed to create/set/get the attribute.
type AttrGetType info Source
Type returned by attrGet
.
type AttrLabel info :: Symbol Source
A string describing the attribute (for error messages).
attrGet :: AttrBaseTypeConstraint info o => proxy info -> o -> IO (AttrGetType info) Source
Get the value of the given attribute.
attrSet :: (AttrBaseTypeConstraint info o, AttrSetTypeConstraint info b) => proxy info -> o -> b -> IO () Source
Set the value of the given attribute, after the object having the attribute has already been created.
attrConstruct :: AttrSetTypeConstraint info b => proxy info -> b -> IO (String, GValue) Source
Build a GValue
representing the attribute.
data AttrOp obj tag where Source
Constructors for the different operations allowed on an attribute.
(:=) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> b -> AttrOp obj tag infixr 0 | |
(:=>) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> IO b -> AttrOp obj tag infixr 0 | |
(:~) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (a -> b) -> AttrOp obj tag infixr 0 | |
(:~>) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (a -> IO b) -> AttrOp obj tag infixr 0 | |
(::=) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed tag info, AttrSetTypeConstraint info b) => proxy (attr :: Symbol) -> (obj -> b) -> AttrOp obj tag infixr 0 | |
(::~) :: (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, tag ~ AttrSet, AttrOpAllowed AttrSet info, AttrOpAllowed AttrGet info, AttrSetTypeConstraint info b, a ~ AttrGetType info) => proxy (attr :: Symbol) -> (obj -> a -> b) -> AttrOp obj tag infixr 0 |
get :: forall info attr obj proxy m. (info ~ ResolveAttribute attr obj, AttrInfo info, AttrBaseTypeConstraint info obj, AttrOpAllowed AttrGet info, MonadIO m) => obj -> proxy (attr :: Symbol) -> m (AttrGetType info) Source
Get the value of an attribute for an object.