GI.GObject.Objects.Object

The base object type.

GObject is the fundamental type providing the common attributes and methods for all object types in GTK, Pango and other libraries based on GObject. The GObject class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail [here][gobject-Signals].

For a tutorial on implementing a new GObject class, see <http://developer.gnome.org/gobject/stable/tutorial.html#how-to-define-and-implement-a-new-gobject How to define and implement a new GObject>. For a list of naming conventions for GObjects and their methods, see the GType conventions. For the high-level concepts behind GObject, read Instantiatable classed types: Objects.

Since GLib 2.72, all GObjects are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is guint64 or gdouble). If you need larger alignment for an element in a GObject, you should allocate it on the heap (aligned), or arrange for your GObject to be appropriately padded. This guarantee applies to the GObject (or derived) struct, the GObjectClass (or derived) struct, and any private data allocated by G_ADD_PRIVATE().

Exported types

newtype Object

Memory-managed wrapper type.

Constructors

Object (ManagedPtr Object)

Instances

Eq Object

Defined in GI.GObject.Objects.Object

Methods

(==) :: Object -> Object -> Bool

(/=) :: Object -> Object -> Bool

GObject Object

Defined in GI.GObject.Objects.Object

ManagedPtrNewtype Object

Defined in GI.GObject.Objects.Object

Methods

toManagedPtr :: Object -> ManagedPtr Object

TypedObject Object

Defined in GI.GObject.Objects.Object

Methods

glibType :: IO GType

HasParentTypes Object

Defined in GI.GObject.Objects.Object

IsGValue (Maybe Object)

Convert Object to and from GValue. See toGValue and fromGValue.

Defined in GI.GObject.Objects.Object

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Object -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Object)

type ParentTypes Object

Defined in GI.GObject.Objects.Object

type ParentTypes Object = '[] :: [Type]

class (GObject o, IsDescendantOf Object o) => IsObject o

Type class for types which can be safely cast to Object, for instance with toObject.

Instances

(GObject o, IsDescendantOf Object o) => IsObject o

Defined in GI.GObject.Objects.Object

toObject :: (MonadIO m, IsObject o) => o -> m Object

Cast to Object, 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

Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

Getters

getData, getProperty, getQdata.

Setters

setData, setDataFull, setProperty.

bindProperty

objectBindProperty

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b)

=> a

source: the source Object

-> Text

sourceProperty: the property on source to bind

-> b

target: the target Object

-> Text

targetProperty: the property on target to bind

-> [BindingFlags]

flags: flags to pass to Binding

-> m Binding

Returns: the Binding instance representing the binding between the two Object instances. The binding is released whenever the Binding reference count reaches zero.

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:

C code

 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.

Removing the binding by calling objectUnref on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use bindingUnbind instead to be on the safe side.

A Object can have multiple bindings.

Since: 2.26

bindPropertyFull

objectBindPropertyFull

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b)

=> a

source: the source Object

-> Text

sourceProperty: the property on source to bind

-> b

target: the target Object

-> Text

targetProperty: the property on target to bind

-> [BindingFlags]

flags: flags to pass to Binding

-> GClosure c

transformTo: a Closure wrapping the transformation function from the source to the target, or Nothing to use the default

-> GClosure d

transformFrom: a Closure wrapping the transformation function from the target to the source, or Nothing to use the default

-> m Binding

Returns: the Binding instance representing the binding between the two Object instances. The binding is released whenever the Binding reference count reaches zero.

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) => CSize -> Ptr () -> m CSize

No description available in the introspection data.

forceFloating

objectForceFloating

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

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

objectFreezeNotify

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

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

objectGetData

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: Object containing the associations

-> Text

key: name of the key for that association

-> m (Ptr ())

Returns: the data if found, or Nothing if no such data exists.

Gets a named field from the objects table of associations (see objectSetData).

getProperty

objectGetProperty

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> Text

propertyName: the name of the property to get

-> GValue

value: return location for the property value

-> m ()

Gets a property of an object.

The value can be:

• an empty Value initialized by G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a Value initialized with the expected type of the property
• a Value initialized with a type to which the expected type of the property can be transformed

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

objectGetQdata

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: The GObject 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

This function gets back user data pointers stored via g_object_set_qdata().

getv

objectGetv

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> [Text]

names: the names of each property to get

-> [GValue]

values: the values of each property to get

-> m ()

Gets nProperties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

Since: 2.54

interfaceFindProperty

objectInterfaceFindProperty

Arguments

:: (HasCallStack, MonadIO m)

=> TypeInterface

gIface: any interface vtable for the interface, or the default vtable for the interface

-> Text

propertyName: name of a property to look up.

-> m GParamSpec

Returns: the ParamSpec for the property of the interface with the name propertyName, or Nothing if no such property exists.

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

Arguments

:: (HasCallStack, MonadIO m)

=> TypeInterface

gIface: any interface vtable for the interface, or the default vtable for the interface.

-> GParamSpec

pspec: the ParamSpec for the new property

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

If pspec is a floating reference, it will be consumed.

Since: 2.4

isFloating

objectIsFloating

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> m Bool

Returns: True if object has a floating reference

Checks whether object has a [floating][floating-ref] reference.

Since: 2.10

newv

objectNewv

Arguments

:: (HasCallStack, MonadIO m)

=> GType

objectType: the type id of the Object subtype to instantiate

-> [Parameter]

parameters: an array of Parameter

-> m Object

Returns: a new instance of objectType

Deprecated: (Since version 2.54)Use g_object_new_with_properties() instead.deprecated. See Parameter for more information.

Creates a new instance of a Object subtype and sets its properties.

Construction parameters (see ParamFlagsConstruct, ParamFlagsConstructOnly) which are not explicitly specified are set to their default values.

notify

objectNotify

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> Text

propertyName: the name of a property installed on the class of object.

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

objectNotifyByPspec

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> GParamSpec

pspec: the ParamSpec of a property installed on the class of object.

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

 typedef enum
 {
   PROP_FOO = 1,
   PROP_LAST
 } MyObjectProperty;

 static GParamSpec *properties[PROP_LAST];

 static void
 my_object_class_init (MyObjectClass *klass)
 {
   properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                            0, 100,
                                            50,
                                            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
   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

objectRef

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> m Object

Returns: the same object

Increases the reference count of object.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

refSink

objectRefSink

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> m Object

Returns: object

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 GLib 2.56, the type of object will be propagated to the return type under the same conditions as for objectRef.

Since: 2.10

runDispose

objectRunDispose

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

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

objectSetData

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: Object containing the associations.

-> Text

key: name of the key

-> Ptr ()

data: data to associate with that key

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

Internally, the key is converted to a GQuark using quarkFromString. This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the GQuark storage growing unbounded.

setDataFull

objectSetDataFull

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: Object containing the associations

-> Text

key: name of the key

-> Ptr ()

data: data to associate with that key

-> Maybe DestroyNotify

destroy: function to call when the association is destroyed

-> m ()

Like objectSetData except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed.

Note that the destroy callback is not called if data is Nothing.

setProperty

objectSetProperty

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

-> Text

propertyName: the name of the property to set

-> GValue

value: the value

-> m ()

Sets a property on an object.

stealData

objectStealData

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: Object containing the associations

-> Text

key: name of the key

-> m (Ptr ())

Returns: the data if found, or Nothing if no such data exists.

Remove a specified datum from the object's data associations, without invoking the association's destroy handler.

stealQdata

objectStealQdata

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: The GObject 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

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");
  // retrieve 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

objectThawNotify

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

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

objectUnref

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object

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

objectWatchClosure

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: Object restricting lifetime of closure

-> GClosure b

closure: Closure to watch

-> 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 ObjectNotifyCallback

Arguments

 = GParamSpec

pspec: the ParamSpec of the property which changed.

-> IO ()

The notify signal is emitted on an object when one of its properties has its value set through objectSetProperty, g_object_set(), et al.

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with ParamFlagsExplicitNotify, then any call to objectSetProperty results in notify being emitted, even if the new value is the same as the old. If they did pass ParamFlagsExplicitNotify, then this signal is emitted only when they explicitly call objectNotify or objectNotifyByPspec, and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

C code

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use [canonical parameter names][canonical-parameter-names] as detail strings for the notify signal.

afterObjectNotify :: (IsObject a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => ObjectNotifyCallback) -> m SignalHandlerId

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

after object #notify callback

This signal admits a optional parameter detail. If it's not Nothing, we will connect to “notify::detail” instead.

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.

onObjectNotify :: (IsObject a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => ObjectNotifyCallback) -> m SignalHandlerId

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

on object #notify callback

This signal admits a optional parameter detail. If it's not Nothing, we will connect to “notify::detail” instead.