Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- Unsupported methods
- bindProperty
- bindPropertyFull
- compatControl
- forceFloating
- freezeNotify
- getData
- getProperty
- getQdata
- interfaceFindProperty
- interfaceInstallProperty
- isFloating
- new
- notify
- notifyByPspec
- ref
- refSink
- replaceData
- replaceQdata
- runDispose
- setData
- setProperty
- stealData
- stealQdata
- thawNotify
- unref
- watchClosure
- Signals
All the fields in the GObject structure are private
to the Object
implementation and should never be accessed directly.
- newtype Object = Object (ManagedPtr Object)
- class GObject o => IsObject o
- toObject :: IsObject o => o -> IO Object
- noObject :: Maybe Object
- data ObjectInterfaceListPropertiesMethodInfo
- data ObjectBindPropertyMethodInfo
- objectBindProperty :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> Text -> b -> Text -> [BindingFlags] -> m Binding
- data ObjectBindPropertyFullMethodInfo
- objectBindPropertyFull :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> Text -> b -> Text -> [BindingFlags] -> Closure -> Closure -> m Binding
- objectCompatControl :: (HasCallStack, MonadIO m) => Word64 -> Ptr () -> m Word64
- data ObjectForceFloatingMethodInfo
- objectForceFloating :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectFreezeNotifyMethodInfo
- objectFreezeNotify :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectGetDataMethodInfo
- objectGetData :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> m (Ptr ())
- data ObjectGetPropertyMethodInfo
- objectGetProperty :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> GValue -> m ()
- data ObjectGetQdataMethodInfo
- objectGetQdata :: (HasCallStack, MonadIO m, IsObject a) => a -> Word32 -> m (Ptr ())
- objectInterfaceFindProperty :: (HasCallStack, MonadIO m) => TypeInterface -> Text -> m GParamSpec
- objectInterfaceInstallProperty :: (HasCallStack, MonadIO m) => TypeInterface -> GParamSpec -> m ()
- data ObjectIsFloatingMethodInfo
- objectIsFloating :: (HasCallStack, MonadIO m, IsObject a) => a -> m Bool
- objectNew :: (HasCallStack, MonadIO m) => GType -> [Parameter] -> m Object
- data ObjectNotifyMethodInfo
- objectNotify :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> m ()
- data ObjectNotifyByPspecMethodInfo
- objectNotifyByPspec :: (HasCallStack, MonadIO m, IsObject a) => a -> GParamSpec -> m ()
- data ObjectRefMethodInfo
- objectRef :: (HasCallStack, MonadIO m, IsObject a) => a -> m Object
- data ObjectRefSinkMethodInfo
- objectRefSink :: (HasCallStack, MonadIO m, IsObject a) => a -> m Object
- data ObjectReplaceDataMethodInfo
- objectReplaceData :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Ptr () -> Ptr () -> Maybe DestroyNotify -> Maybe DestroyNotify -> m Bool
- data ObjectReplaceQdataMethodInfo
- objectReplaceQdata :: (HasCallStack, MonadIO m, IsObject a) => a -> Word32 -> Ptr () -> Ptr () -> Maybe DestroyNotify -> Maybe DestroyNotify -> m Bool
- data ObjectRunDisposeMethodInfo
- objectRunDispose :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectSetDataMethodInfo
- objectSetData :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Ptr () -> m ()
- data ObjectSetPropertyMethodInfo
- objectSetProperty :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> GValue -> m ()
- data ObjectStealDataMethodInfo
- objectStealData :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> m (Ptr ())
- data ObjectStealQdataMethodInfo
- objectStealQdata :: (HasCallStack, MonadIO m, IsObject a) => a -> Word32 -> m (Ptr ())
- data ObjectThawNotifyMethodInfo
- objectThawNotify :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectUnrefMethodInfo
- objectUnref :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectWatchClosureMethodInfo
- objectWatchClosure :: (HasCallStack, MonadIO m, IsObject a) => a -> Closure -> m ()
- type C_ObjectNotifyCallback = Ptr () -> Ptr GParamSpec -> Ptr () -> IO ()
- type ObjectNotifyCallback = GParamSpec -> IO ()
- data ObjectNotifySignalInfo
- afterObjectNotify :: (GObject a, MonadIO m) => a -> ObjectNotifyCallback -> m SignalHandlerId
- genClosure_ObjectNotify :: ObjectNotifyCallback -> IO Closure
- mk_ObjectNotifyCallback :: C_ObjectNotifyCallback -> IO (FunPtr C_ObjectNotifyCallback)
- noObjectNotifyCallback :: Maybe ObjectNotifyCallback
- onObjectNotify :: (GObject a, MonadIO m) => a -> ObjectNotifyCallback -> m SignalHandlerId
- wrap_ObjectNotifyCallback :: ObjectNotifyCallback -> Ptr () -> Ptr GParamSpec -> Ptr () -> IO ()
Exported types
GObject Object Source # | |
IsObject Object Source # | |
((~) * info (ResolveObjectMethod t Object), MethodInfo * info Object p) => IsLabel t (Object -> p) Source # | |
((~) * info (ResolveObjectMethod t Object), MethodInfo * info Object p) => IsLabelProxy t (Object -> p) Source # | |
HasAttributeList * Object Source # | |
type AttributeList Object Source # | |
type SignalList Object Source # | |
Methods
Unsupported methods
data ObjectInterfaceListPropertiesMethodInfo Source #
((~) * p (), (~) * o (MethodResolutionFailed * "interfaceListProperties" Object)) => MethodInfo * ObjectInterfaceListPropertiesMethodInfo o p Source # | |
bindProperty
data ObjectBindPropertyMethodInfo Source #
((~) * signature (Text -> b -> Text -> [BindingFlags] -> m Binding), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectBindPropertyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> a |
|
-> Text |
|
-> b |
|
-> Text |
|
-> [BindingFlags] |
|
-> m Binding | Returns: the |
Creates a binding between sourceProperty
on source
and targetProperty
on target
. Whenever the sourceProperty
is changed the targetProperty
is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget Object
instance to be
updated with the same value of the "active" property of the action Object
instance.
If flags
contains BindingFlagsBidirectional
then the binding will be mutual:
if targetProperty
on target
changes then the sourceProperty
on source
will be updated as well.
The binding will automatically be removed when either the source
or the
target
instances are finalized. To remove the binding without affecting the
source
and the target
you can just call objectUnref
on the returned
Binding
instance.
A Object
can have multiple bindings.
Since: 2.26
bindPropertyFull
data ObjectBindPropertyFullMethodInfo Source #
((~) * signature (Text -> b -> Text -> [BindingFlags] -> Closure -> Closure -> m Binding), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectBindPropertyFullMethodInfo a signature Source # | |
objectBindPropertyFull Source #
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> a |
|
-> Text |
|
-> b |
|
-> Text |
|
-> [BindingFlags] |
|
-> Closure |
|
-> Closure |
|
-> m Binding | Returns: the |
Creates a binding between sourceProperty
on source
and targetProperty
on target
, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of
g_object_bind_property_full()
, using GClosures
instead of
function pointers.
Since: 2.26
compatControl
objectCompatControl :: (HasCallStack, MonadIO m) => Word64 -> Ptr () -> m Word64 Source #
No description available in the introspection data.
forceFloating
data ObjectForceFloatingMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectForceFloatingMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m () |
This function is intended for Object
implementations to re-enforce
a [floating][floating-ref] object reference. Doing this is seldom
required: all GInitiallyUnowneds
are created with a floating reference
which usually just needs to be sunken by calling objectRefSink
.
Since: 2.10
freezeNotify
data ObjectFreezeNotifyMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectFreezeNotifyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m () |
Increases the freeze count on object
. If the freeze count is
non-zero, the emission of "notify" signals on object
is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
Object
::notify
signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
getData
data ObjectGetDataMethodInfo Source #
((~) * signature (Text -> m (Ptr ())), MonadIO m, IsObject a) => MethodInfo * ObjectGetDataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> m (Ptr ()) | Returns: the data if found, or |
Gets a named field from the objects table of associations (see objectSetData
).
getProperty
data ObjectGetPropertyMethodInfo Source #
((~) * signature (Text -> GValue -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectGetPropertyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> GValue |
|
-> m () |
Gets a property of an object. value
must have been initialized to the
expected type of the property (or a type to which the expected type can be
transformed) using valueInit
.
In general, a copy is made of the property contents and the caller is
responsible for freeing the memory by calling valueUnset
.
Note that objectGetProperty
is really intended for language
bindings, g_object_get()
is much more convenient for C programming.
getQdata
data ObjectGetQdataMethodInfo Source #
((~) * signature (Word32 -> m (Ptr ())), MonadIO m, IsObject a) => MethodInfo * ObjectGetQdataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Word32 |
|
-> m (Ptr ()) | Returns: The user data pointer set, or |
This function gets back user data pointers stored via
g_object_set_qdata()
.
interfaceFindProperty
objectInterfaceFindProperty Source #
:: (HasCallStack, MonadIO m) | |
=> TypeInterface |
|
-> Text |
|
-> m GParamSpec | Returns: the |
Find the ParamSpec
with the given name for an
interface. Generally, the interface vtable passed in as gIface
will be the default vtable from typeDefaultInterfaceRef
, or,
if you know the interface has already been loaded,
typeDefaultInterfacePeek
.
Since: 2.4
interfaceInstallProperty
objectInterfaceInstallProperty Source #
:: (HasCallStack, MonadIO m) | |
=> TypeInterface |
|
-> GParamSpec |
|
-> m () |
Add a property to an interface; this is only useful for interfaces
that are added to GObject-derived types. Adding a property to an
interface forces all objects classes with that interface to have a
compatible property. The compatible property could be a newly
created ParamSpec
, but normally
objectClassOverrideProperty
will be used so that the object
class only needs to provide an implementation and inherits the
property description, default value, bounds, and so forth from the
interface property.
This function is meant to be called from the interface's default
vtable initialization function (the classInit
member of
TypeInfo
.) It must not be called after after classInit
has
been called for any object types implementing this interface.
Since: 2.4
isFloating
data ObjectIsFloatingMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsObject a) => MethodInfo * ObjectIsFloatingMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether object
has a [floating][floating-ref] reference.
Since: 2.10
new
:: (HasCallStack, MonadIO m) | |
=> GType |
|
-> [Parameter] |
|
-> m Object | Returns: a new instance of
|
Creates a new instance of a Object
subtype and sets its properties.
Construction parameters (see G_PARAM_CONSTRUCT
, G_PARAM_CONSTRUCT_ONLY
)
which are not explicitly specified are set to their default values.
notify
data ObjectNotifyMethodInfo Source #
((~) * signature (Text -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectNotifyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> m () |
Emits a "notify" signal for the property propertyName
on object
.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use objectNotifyByPspec
instead.
Note that emission of the notify signal may be blocked with
objectFreezeNotify
. In this case, the signal emissions are queued
and will be emitted (in reverse order) when objectThawNotify
is
called.
notifyByPspec
data ObjectNotifyByPspecMethodInfo Source #
((~) * signature (GParamSpec -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectNotifyByPspecMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> GParamSpec |
|
-> m () |
Emits a "notify" signal for the property specified by pspec
on object
.
This function omits the property name lookup, hence it is faster than
objectNotify
.
One way to avoid using objectNotify
from within the
class that registered the properties, and using objectNotifyByPspec
instead, is to store the GParamSpec used with
objectClassInstallProperty
inside a static array, e.g.:
C code
enum { PROP_0, PROP_FOO, PROP_LAST }; static GParamSpec *properties[PROP_LAST]; static void my_object_class_init (MyObjectClass *klass) { properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", 0, 100, 50, G_PARAM_READWRITE); g_object_class_install_property (gobject_class, PROP_FOO, properties[PROP_FOO]); }
and then notify a change on the "foo" property with:
C code
g_object_notify_by_pspec (self, properties[PROP_FOO]);
Since: 2.26
ref
data ObjectRefMethodInfo Source #
((~) * signature (m Object), MonadIO m, IsObject a) => MethodInfo * ObjectRefMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Object | Returns: the same |
Increases the reference count of object
.
refSink
data ObjectRefSinkMethodInfo Source #
((~) * signature (m Object), MonadIO m, IsObject a) => MethodInfo * ObjectRefSinkMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Object | Returns: |
Increase the reference count of object
, and possibly remove the
[floating][floating-ref] reference, if object
has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since: 2.10
replaceData
data ObjectReplaceDataMethodInfo Source #
((~) * signature (Text -> Ptr () -> Ptr () -> Maybe DestroyNotify -> Maybe DestroyNotify -> m Bool), MonadIO m, IsObject a) => MethodInfo * ObjectReplaceDataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Ptr () |
|
-> Ptr () |
|
-> Maybe DestroyNotify |
|
-> Maybe DestroyNotify |
|
-> m Bool | Returns: |
Compares the user data for the key key
on object
with
oldval
, and if they are the same, replaces oldval
with
newval
.
This is like a typical atomic compare-and-exchange operation, for user data on an object.
If the previous value was replaced then ownership of the
old value (oldval
) is passed to the caller, including
the registered destroy notify for it (passed out in oldDestroy
).
Its up to the caller to free this as he wishes, which may
or may not include using oldDestroy
as sometimes replacement
should not destroy the object in the normal way.
Since: 2.34
replaceQdata
data ObjectReplaceQdataMethodInfo Source #
((~) * signature (Word32 -> Ptr () -> Ptr () -> Maybe DestroyNotify -> Maybe DestroyNotify -> m Bool), MonadIO m, IsObject a) => MethodInfo * ObjectReplaceQdataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Word32 |
|
-> Ptr () |
|
-> Ptr () |
|
-> Maybe DestroyNotify |
|
-> Maybe DestroyNotify |
|
-> m Bool | Returns: |
Compares the user data for the key quark
on object
with
oldval
, and if they are the same, replaces oldval
with
newval
.
This is like a typical atomic compare-and-exchange operation, for user data on an object.
If the previous value was replaced then ownership of the
old value (oldval
) is passed to the caller, including
the registered destroy notify for it (passed out in oldDestroy
).
Its up to the caller to free this as he wishes, which may
or may not include using oldDestroy
as sometimes replacement
should not destroy the object in the normal way.
Since: 2.34
runDispose
data ObjectRunDisposeMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectRunDisposeMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m () |
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
setData
data ObjectSetDataMethodInfo Source #
((~) * signature (Text -> Ptr () -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectSetDataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Ptr () |
|
-> m () |
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
setProperty
data ObjectSetPropertyMethodInfo Source #
((~) * signature (Text -> GValue -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectSetPropertyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> GValue |
|
-> m () |
Sets a property on an object.
stealData
data ObjectStealDataMethodInfo Source #
((~) * signature (Text -> m (Ptr ())), MonadIO m, IsObject a) => MethodInfo * ObjectStealDataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> m (Ptr ()) | Returns: the data if found, or |
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
stealQdata
data ObjectStealQdataMethodInfo Source #
((~) * signature (Word32 -> m (Ptr ())), MonadIO m, IsObject a) => MethodInfo * ObjectStealQdataMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Word32 |
|
-> m (Ptr ()) | Returns: The user data pointer set, or |
This function gets back user data pointers stored via
g_object_set_qdata()
and removes the data
from object
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, for example:
C code
void object_add_to_user_list (GObject *object, const gchar *new_string) { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); // retrive the old string list GList *list = g_object_steal_qdata (object, quark_string_list); // prepend new string list = g_list_prepend (list, g_strdup (new_string)); // this changed 'list', so we need to set it again g_object_set_qdata_full (object, quark_string_list, list, free_string_list); } static void free_string_list (gpointer data) { GList *node, *list = data; for (node = list; node; node = node->next) g_free (node->data); g_list_free (list); }
Using objectGetQdata
in the above example, instead of
objectStealQdata
would have left the destroy function set,
and thus the partial string list would have been freed upon
g_object_set_qdata_full()
.
thawNotify
data ObjectThawNotifyMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectThawNotifyMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m () |
Reverts the effect of a previous call to
objectFreezeNotify
. The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one
Object
::notify
signal is emitted for each property, in the reverse order
in which they have been queued.
It is an error to call this function when the freeze count is zero.
unref
data ObjectUnrefMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectUnrefMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m () |
Decreases the reference count of object
. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the Object
may be reused in future (for example, if it is
an instance variable of another object), it is recommended to clear the
pointer to Nothing
rather than retain a dangling pointer to a potentially
invalid Object
instance. Use g_clear_object()
for this.
watchClosure
data ObjectWatchClosureMethodInfo Source #
((~) * signature (Closure -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectWatchClosureMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Closure |
|
-> m () |
This function essentially limits the life time of the closure
to
the life time of the object. That is, when the object is finalized,
the closure
is invalidated by calling closureInvalidate
on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, objectRef
and objectUnref
are
added as marshal guards to the closure
, to ensure that an extra
reference count is held on object
during invocation of the
closure
. Usually, this function will be called on closures that
use this object
as closure data.
Signals
notify
type C_ObjectNotifyCallback = Ptr () -> Ptr GParamSpec -> Ptr () -> IO () Source #
type ObjectNotifyCallback = GParamSpec -> IO () Source #
afterObjectNotify :: (GObject a, MonadIO m) => a -> ObjectNotifyCallback -> m SignalHandlerId Source #
onObjectNotify :: (GObject a, MonadIO m) => a -> ObjectNotifyCallback -> m SignalHandlerId Source #
wrap_ObjectNotifyCallback :: ObjectNotifyCallback -> Ptr () -> Ptr GParamSpec -> Ptr () -> IO () Source #