ObjectProtocol
public protocol ObjectProtocol
The base object type.
All the fields in the GObject
structure are private to the implementation
and should never be accessed directly.
The ObjectProtocol
protocol exposes the methods and properties of an underlying GObject
instance.
The default implementation of these can be found in the protocol extension below.
For a concrete class that implements these methods and properties, see Object
.
Alternatively, use ObjectRef
as a lighweight, unowned
reference if you already have an instance you just want to use.
-
Untyped pointer to the underlying
GObject
instance.Declaration
Swift
var ptr: UnsafeMutableRawPointer! { get }
-
object_ptr
Default implementationTyped pointer to the underlying
GObject
instance.Default Implementation
Return the stored, untyped pointer as a typed pointer to the
GObject
instance.Declaration
Swift
var object_ptr: UnsafeMutablePointer<GObject>! { get }
-
Required Initialiser for types conforming to
ObjectProtocol
Declaration
Swift
init(raw: UnsafeMutableRawPointer)
-
connect(signal:
Extension methodflags: handler: ) Connect a Swift signal handler to the given, typed
ObjectSignalName
signalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: ObjectSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int
Parameters
signal
The signal to connect
flags
The connection flags to use
data
A pointer to user data to provide to the callback
destroyData
A
GClosureNotify
C function to destroy the data pointed to byuserData
handler
The Swift signal handler (function or callback) to invoke on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
connect(signal:
Extension methodflags: data: destroyData: signalHandler: ) Connect a C signal handler to the given, typed
ObjectSignalName
signalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: ObjectSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int
Parameters
signal
The signal to connect
flags
The connection flags to use
data
A pointer to user data to provide to the callback
destroyData
A
GClosureNotify
C function to destroy the data pointed to byuserData
signalHandler
The C function to be called on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
onNotify(flags:
Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property()
,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
G_PARAM_EXPLICIT_NOTIFY
, then any call tog_object_set_property()
results innotify
being emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY
, then this signal is emitted only when they explicitly callg_object_notify()
org_object_notify_by_pspec()
, 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 Language Example):
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 as detail strings for the notify signal.
Note
This represents the underlyingnotify
signalDeclaration
Swift
@discardableResult @inlinable func onNotify(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: ObjectRef, _ pspec: ParamSpecRef) -> Void) -> Int
Parameters
flags
Flags
unownedSelf
Reference to instance of self
pspec
the
GParamSpec
of the property which changed.handler
The signal handler to call Run the given callback whenever the
notify
signal is emitted -
notifySignal
Extension methodTyped
notify
signal for using theconnect(signal:)
methodsDeclaration
Swift
static var notifySignal: ObjectSignalName { get }
-
addToggleRef(notify:
Extension methoddata: ) Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.
This functionality is intended for binding
object
to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added byg_object_add_toggle_ref()
and a reverse reference to the proxy object which is either a strong reference or weak reference.The setup is that when there are no other references to
object
, only a weak reference is held in the reverse direction fromobject
to the proxy object, but when there are other references held toobject
, a strong reference is held. Thenotify
callback is called when the reference fromobject
to the proxy object should be “toggled” from strong to weak (is_last_ref
true) or weak to strong (is_last_ref
false).Since a (normal) reference must be held to the object before calling
g_object_add_toggle_ref()
, the initial state of the reverse link is always strong.Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object.
Declaration
Swift
@inlinable func addToggleRef(notify: GToggleNotify?, data: gpointer? = nil)
-
addWeakPointer(weakPointerLocation:
Extension method) Adds a weak reference from weak_pointer to
object
to indicate that the pointer located atweak_pointer_location
is only valid during the lifetime ofobject
. When theobject
is finalized,weak_pointer
will be set tonil
.Note that as with
g_object_weak_ref()
, the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object’s lastg_object_unref()
might happen in another thread. UseGWeakRef
if thread-safety is required.Declaration
Swift
@inlinable func addWeakPointer(weakPointerLocation: UnsafeMutablePointer<gpointer?>!)
-
bindProperty(sourceProperty:
Extension methodtarget: targetProperty: flags: ) Creates a binding between
source_property
onsource
andtarget_property
ontarget
.Whenever the
source_property
is changed thetarget_property
is updated using the same value. For instance:(C Language Example):
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the “sensitive” property of the widget
GObject
instance to be updated with the same value of the “active” property of the actionGObject
instance.If
flags
containsG_BINDING_BIDIRECTIONAL
then the binding will be mutual: iftarget_property
ontarget
changes then thesource_property
onsource
will be updated as well.The binding will automatically be removed when either the
source
or thetarget
instances are finalized. To remove the binding without affecting thesource
and thetarget
you can just callg_object_unref()
on the returnedGBinding
instance.Removing the binding by calling
g_object_unref()
on it must only be done if the binding,source
andtarget
are only used from a single thread and it is clear that bothsource
andtarget
outlive the binding. Especially it is not safe to rely on this if the binding,source
ortarget
can be finalized from different threads. Keep another reference to the binding and useg_binding_unbind()
instead to be on the safe side.A
GObject
can have multiple bindings.Declaration
Swift
@inlinable func bindProperty<ObjectT>(sourceProperty: UnsafePointer<gchar>!, target: ObjectT, targetProperty: UnsafePointer<gchar>!, flags: BindingFlags) -> GLibObject.BindingRef! where ObjectT : ObjectProtocol
-
bindPropertyFull(sourceProperty:
Extension methodtarget: targetProperty: flags: transformTo: transformFrom: userData: notify: ) Complete version of
g_object_bind_property()
.Creates a binding between
source_property
onsource
andtarget_property
ontarget
, allowing you to set the transformation functions to be used by the binding.If
flags
containsG_BINDING_BIDIRECTIONAL
then the binding will be mutual: iftarget_property
ontarget
changes then thesource_property
onsource
will be updated as well. Thetransform_from
function is only used in case of bidirectional bindings, otherwise it will be ignoredThe binding will automatically be removed when either the
source
or thetarget
instances are finalized. This will release the reference that is being held on theGBinding
instance; if you want to hold on to theGBinding
instance, you will need to hold a reference to it.To remove the binding, call
g_binding_unbind()
.A
GObject
can have multiple bindings.The same
user_data
parameter will be used for bothtransform_to
andtransform_from
transformation functions; thenotify
function will be called once, when the binding is removed. If you need different data for each transformation function, please useg_object_bind_property_with_closures()
instead.Declaration
Swift
@inlinable func bindPropertyFull<ObjectT>(sourceProperty: UnsafePointer<gchar>!, target: ObjectT, targetProperty: UnsafePointer<gchar>!, flags: BindingFlags, transformTo: GBindingTransformFunc? = nil, transformFrom: GBindingTransformFunc? = nil, userData: gpointer? = nil, notify: GDestroyNotify? = nil) -> GLibObject.BindingRef! where ObjectT : ObjectProtocol
-
bindPropertyWithClosures(sourceProperty:
Extension methodtarget: targetProperty: flags: transformTo: transformFrom: ) Creates a binding between
source_property
onsource
andtarget_property
ontarget
, 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()
, usingGClosures
instead of function pointers.Declaration
Swift
@inlinable func bindPropertyWithClosures<ClosureT, ObjectT>(sourceProperty: UnsafePointer<gchar>!, target: ObjectT, targetProperty: UnsafePointer<gchar>!, flags: BindingFlags, transformTo: ClosureT, transformFrom: ClosureT) -> GLibObject.BindingRef! where ClosureT : ClosureProtocol, ObjectT : ObjectProtocol
-
dupData(key:
Extension methoddupFunc: userData: ) This is a variant of
g_object_get_data()
which returns a ‘duplicate’ of the value.dup_func
defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.If the
key
is not set on the object thendup_func
will be called with anil
argument.Note that
dup_func
is called while user data ofobject
is locked.This function can be useful to avoid races when multiple threads are using object data on the same key on the same object.
Declaration
Swift
@inlinable func dupData(key: UnsafePointer<gchar>!, dupFunc: GDuplicateFunc? = nil, userData: gpointer? = nil) -> gpointer?
-
dupQdata(quark:
Extension methoddupFunc: userData: ) This is a variant of
g_object_get_qdata()
which returns a ‘duplicate’ of the value.dup_func
defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.If the
quark
is not set on the object thendup_func
will be called with anil
argument.Note that
dup_func
is called while user data ofobject
is locked.This function can be useful to avoid races when multiple threads are using object data on the same key on the same object.
Declaration
Swift
@inlinable func dupQdata(quark: GQuark, dupFunc: GDuplicateFunc? = nil, userData: gpointer? = nil) -> gpointer?
-
forceFloating()
Extension methodThis function is intended for
GObject
implementations to re-enforce a floating object reference. Doing this is seldom required: allGInitiallyUnowneds
are created with a floating reference which usually just needs to be sunken by callingg_object_ref_sink()
.Declaration
Swift
@inlinable func forceFloating()
-
freezeNotify()
Extension methodIncreases the freeze count on
object
. If the freeze count is non-zero, the emission of “notify” signals onobject
is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most oneGObject::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.
Declaration
Swift
@inlinable func freezeNotify()
-
getData(key:
Extension method) Gets a named field from the objects table of associations (see
g_object_set_data()
).Declaration
Swift
@inlinable func getData(key: UnsafePointer<gchar>!) -> gpointer?
-
getProperty(propertyName:
Extension methodvalue: ) Gets a property of an object.
The
value
can be:- an empty
GValue
initialized byG_VALUE_INIT
, which will be automatically initialized with the expected type of the property (since GLib 2.60) - a
GValue
initialized with the expected type of the property - a
GValue
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
g_value_unset()
.Note that
g_object_get_property()
is really intended for language bindings,g_object_get()
is much more convenient for C programming.Declaration
Swift
@inlinable func getProperty<ValueT>(propertyName: UnsafePointer<gchar>!, value: ValueT) where ValueT : ValueProtocol
- an empty
-
getQdata(quark:
Extension method) This function gets back user data pointers stored via
g_object_set_qdata()
.Declaration
Swift
@inlinable func getQdata(quark: GQuark) -> gpointer?
-
getValist(firstPropertyName:
Extension methodvarArgs: ) Gets properties of an object.
In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling
g_free()
org_object_unref()
.See
g_object_get()
.Declaration
Swift
@inlinable func getValist(firstPropertyName: UnsafePointer<gchar>!, varArgs: CVaListPointer)
-
getv(nProperties:
Extension methodnames: values: ) Gets
n_properties
properties for anobject
. Obtained properties will be set tovalues
. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.Declaration
Swift
@inlinable func getv(nProperties: Int, names: UnsafeMutablePointer<UnsafePointer<gchar>?>!, values: UnsafeMutablePointer<GValue>!)
-
notify(propertyName:
Extension method) Emits a “notify” signal for the property
property_name
onobject
.When possible, eg. when signaling a property change from within the class that registered the property, you should use
g_object_notify_by_pspec()
instead.Note that emission of the notify signal may be blocked with
g_object_freeze_notify()
. In this case, the signal emissions are queued and will be emitted (in reverse order) wheng_object_thaw_notify()
is called.Declaration
Swift
@inlinable func notify(propertyName: UnsafePointer<gchar>!)
-
notifyBy(pspec:
Extension method) Emits a “notify” signal for the property specified by
pspec
onobject
.This function omits the property name lookup, hence it is faster than
g_object_notify()
.One way to avoid using
g_object_notify()
from within the class that registered the properties, and usingg_object_notify_by_pspec()
instead, is to store the GParamSpec used withg_object_class_install_property()
inside a static array, e.g.:(C Language Example):
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 Language Example):
g_object_notify_by_pspec (self, properties[PROP_FOO]);
Declaration
Swift
@inlinable func notifyBy<ParamSpecT>(pspec: ParamSpecT) where ParamSpecT : ParamSpecProtocol
-
ref()
Extension methodIncreases the reference count of
object
.Since GLib 2.56, if
GLIB_VERSION_MAX_ALLOWED
is 2.56 or greater, the type ofobject
will be propagated to the return type (using the GCCtypeof()
extension), so any casting the caller needs to do on the return type must be explicit.Declaration
Swift
@discardableResult @inlinable func ref() -> GLibObject.ObjectRef!
-
refSink()
Extension methodIncrease the reference count of
object
, and possibly remove the floating reference, ifobject
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 forg_object_ref()
.Declaration
Swift
@discardableResult @inlinable func refSink() -> GLibObject.ObjectRef!
-
removeToggleRef(notify:
Extension methoddata: ) Removes a reference added with
g_object_add_toggle_ref()
. The reference count of the object is decreased by one.Declaration
Swift
@inlinable func removeToggleRef(notify: GToggleNotify?, data: gpointer? = nil)
-
removeWeakPointer(weakPointerLocation:
Extension method) Removes a weak reference from
object
that was previously added usingg_object_add_weak_pointer()
. Theweak_pointer_location
has to match the one used withg_object_add_weak_pointer()
.Declaration
Swift
@inlinable func removeWeakPointer(weakPointerLocation: UnsafeMutablePointer<gpointer?>!)
-
replaceData(key:
Extension methodoldval: newval: destroy: oldDestroy: ) Compares the user data for the key
key
onobject
witholdval
, and if they are the same, replacesoldval
withnewval
.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 inold_destroy
). It’s up to the caller to free this as needed, which may or may not include usingold_destroy
as sometimes replacement should not destroy the object in the normal way.See
g_object_set_data()
for guidance on using a small, bounded set of values forkey
.Declaration
Swift
@inlinable func replaceData(key: UnsafePointer<gchar>!, oldval: gpointer? = nil, newval: gpointer? = nil, destroy: GDestroyNotify? = nil, oldDestroy: UnsafeMutablePointer<GDestroyNotify?>! = nil) -> Bool
-
replaceQdata(quark:
Extension methodoldval: newval: destroy: oldDestroy: ) Compares the user data for the key
quark
onobject
witholdval
, and if they are the same, replacesoldval
withnewval
.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 inold_destroy
). It’s up to the caller to free this as needed, which may or may not include usingold_destroy
as sometimes replacement should not destroy the object in the normal way.Declaration
Swift
@inlinable func replaceQdata(quark: GQuark, oldval: gpointer? = nil, newval: gpointer? = nil, destroy: GDestroyNotify? = nil, oldDestroy: UnsafeMutablePointer<GDestroyNotify?>! = nil) -> Bool
-
runDispose()
Extension methodReleases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Declaration
Swift
@inlinable func runDispose()
-
setData(key:
Extension methoddata: ) 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 aGQuark
usingg_quark_from_string()
. This means a copy ofkey
is kept permanently (even afterobject
has been finalized) — so it is recommended to only use a small, bounded set of values forkey
in your program, to avoid theGQuark
storage growing unbounded.Declaration
Swift
@inlinable func setData(key: UnsafePointer<gchar>!, data: gpointer? = nil)
-
setDataFull(key:
Extension methoddata: destroy: ) Like
g_object_set_data()
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 ifdata
isnil
.Declaration
Swift
@inlinable func setDataFull(key: UnsafePointer<gchar>!, data: gpointer? = nil, destroy: GDestroyNotify? = nil)
-
setProperty(propertyName:
Extension methodvalue: ) Sets a property on an object.
Declaration
Swift
@inlinable func setProperty<ValueT>(propertyName: UnsafePointer<gchar>!, value: ValueT) where ValueT : ValueProtocol
-
setQdata(quark:
Extension methoddata: ) This sets an opaque, named pointer on an object. The name is specified through a
GQuark
(retrieved e.g. viag_quark_from_static_string()
), and the pointer can be gotten back from theobject
withg_object_get_qdata()
until theobject
is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, usingNULL
as pointer essentially removes the data stored.Declaration
Swift
@inlinable func setQdata(quark: GQuark, data: gpointer? = nil)
-
setQdataFull(quark:
Extension methoddata: destroy: ) This function works like
g_object_set_qdata()
, but in addition, a void (*destroy) (gpointer) function may be specified which is called withdata
as argument when theobject
is finalized, or the data is being overwritten by a call tog_object_set_qdata()
with the samequark
.Declaration
Swift
@inlinable func setQdataFull(quark: GQuark, data: gpointer? = nil, destroy: GDestroyNotify? = nil)
-
setValist(firstPropertyName:
Extension methodvarArgs: ) Sets properties on an object.
Declaration
Swift
@inlinable func setValist(firstPropertyName: UnsafePointer<gchar>!, varArgs: CVaListPointer)
-
setv(nProperties:
Extension methodnames: values: ) Sets
n_properties
properties for anobject
. Properties to be set will be taken fromvalues
. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.Declaration
Swift
@inlinable func setv(nProperties: Int, names: UnsafeMutablePointer<UnsafePointer<gchar>?>!, values: UnsafePointer<GValue>!)
-
stealData(key:
Extension method) Remove a specified datum from the object’s data associations, without invoking the association’s destroy handler.
Declaration
Swift
@inlinable func stealData(key: UnsafePointer<gchar>!) -> gpointer?
-
stealQdata(quark:
Extension method) This function gets back user data pointers stored via
g_object_set_qdata()
and removes thedata
from object without invoking itsdestroy()
function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example: (C Language Example):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
g_object_get_qdata()
in the above example, instead ofg_object_steal_qdata()
would have left the destroy function set, and thus the partial string list would have been freed upong_object_set_qdata_full()
.Declaration
Swift
@inlinable func stealQdata(quark: GQuark) -> gpointer?
-
takeRef()
Extension methodIf
object
is floating, sink it. Otherwise, do nothing.In other words, this function will convert a floating reference (if present) into a full reference.
Typically you want to use
g_object_ref_sink()
in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful.The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a GObject. We certainly want to allow the user the flexibility to return a non-floating reference from this callback (for the case where the object that is being returned already exists).
At the same time, the API style of some popular GObject-based libraries (such as Gtk) make it likely that for newly-created GObject instances, the user can be saved some typing if they are allowed to return a floating reference.
Using this function on the return value of the user’s callback allows the user to do whichever is more convenient for them. The caller will alway receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference.
This function has an odd interaction when combined with
g_object_ref_sink()
running at the same time in another thread on the sameGObject
instance. Ifg_object_ref_sink()
runs first then the result will be that the floating reference is converted to a hard reference. Ifg_object_take_ref()
runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation.Declaration
Swift
@inlinable func takeRef() -> GLibObject.ObjectRef!
-
thawNotify()
Extension methodReverts the effect of a previous call to
g_object_freeze_notify()
. The freeze count is decreased onobject
and when it reaches zero, queued “notify” signals are emitted.Duplicate notifications for each property are squashed so that at most one
GObject::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.
Declaration
Swift
@inlinable func thawNotify()
-
unref()
Extension methodDecreases 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
GObject
may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer tonil
rather than retain a dangling pointer to a potentially invalidGObject
instance. Useg_clear_object()
for this.Declaration
Swift
@inlinable func unref()
-
watch(closure:
Extension method) This function essentially limits the life time of the
closure
to the life time of the object. That is, when the object is finalized, theclosure
is invalidated by callingg_closure_invalidate()
on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also,g_object_ref()
andg_object_unref()
are added as marshal guards to theclosure
, to ensure that an extra reference count is held onobject
during invocation of theclosure
. Usually, this function will be called on closures that use thisobject
as closure data.Declaration
Swift
@inlinable func watch<ClosureT>(closure: ClosureT) where ClosureT : ClosureProtocol
-
weakRef(notify:
Extension methoddata: ) Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called “weak references” because they allow you to safely hold a pointer to an object without calling
g_object_ref()
(g_object_ref()
adds a strong reference, that is, forces the object to stay alive).Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object’s last
g_object_unref()
might happen in another thread. UseGWeakRef
if thread-safety is required.Declaration
Swift
@inlinable func weakRef(notify: GWeakNotify?, data: gpointer? = nil)
-
weakUnref(notify:
Extension methoddata: ) Removes a weak reference callback to an object.
Declaration
Swift
@inlinable func weakUnref(notify: GWeakNotify?, data: gpointer? = nil)
-
cclosureNewObject(callbackFunc:
Extension method) A variant of
g_cclosure_new()
which usesobject
asuser_data
and callsg_object_watch_closure()
onobject
and the created closure. This function is useful when you have a callback closely associated with aGObject
, and want the callback to no longer run after the object is is freed.Declaration
Swift
@inlinable func cclosureNewObject(callbackFunc: @escaping GCallback) -> GLibObject.ClosureRef!
-
cclosureNewObjectSwap(callbackFunc:
Extension method) A variant of
g_cclosure_new_swap()
which usesobject
asuser_data
and callsg_object_watch_closure()
onobject
and the created closure. This function is useful when you have a callback closely associated with aGObject
, and want the callback to no longer run after the object is is freed.Declaration
Swift
@inlinable func cclosureNewObjectSwap(callbackFunc: @escaping GCallback) -> GLibObject.ClosureRef!
-
clearSignalHandler(handlerIDPtr:
Extension method) Disconnects a handler from
instance
so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. Thehandler_id_ptr
is then set to zero, which is never a valid handler ID value (seeg_signal_connect()
).If the handler ID is 0 then this function does nothing.
There is also a macro version of this function so that the code will be inlined.
Declaration
Swift
@inlinable func clearSignalHandler(handlerIDPtr: UnsafeMutablePointer<gulong>!)
-
signalConnectClosure(detailedSignal:
Extension methodclosure: after: ) Connects a closure to a signal for a particular object.
Declaration
Swift
@inlinable func signalConnectClosure<ClosureT>(detailedSignal: UnsafePointer<gchar>!, closure: ClosureT, after: Bool) -> Int where ClosureT : ClosureProtocol
-
signalConnectClosureByID(signalID:
Extension methoddetail: closure: after: ) Connects a closure to a signal for a particular object.
Declaration
Swift
@inlinable func signalConnectClosureByID<ClosureT>(signalID: Int, detail: GQuark, closure: ClosureT, after: Bool) -> Int where ClosureT : ClosureProtocol
-
Connects a
GCallback
function to a signal for a particular object. Similar tog_signal_connect()
, but allows to provide aGClosureNotify
for the data which will be called when the signal handler is disconnected and no longer used. Specifyconnect_flags
if you need..._after()
or..._swapped()
variants of this function.Declaration
Swift
@inlinable func signalConnectData(detailedSignal: UnsafePointer<gchar>!, cHandler: @escaping GCallback, data: gpointer? = nil, destroyData: GClosureNotify? = nil, connectFlags: ConnectFlags) -> Int
-
signalConnectObject(instance:
Extension methoddetailedSignal: cHandler: connectFlags: ) This is similar to
g_signal_connect_data()
, but uses a closure which ensures that thegobject
stays alive during the call toc_handler
by temporarily adding a reference count togobject
.When the
gobject
is destroyed the signal handler will be automatically disconnected. Note that this is not currently threadsafe (ie: emitting a signal whilegobject
is being destroyed in another thread is not safe).Declaration
Swift
@inlinable func signalConnectObject<TypeInstanceT>(instance: TypeInstanceT, detailedSignal: UnsafePointer<gchar>!, cHandler: @escaping GCallback, connectFlags: ConnectFlags) -> Int where TypeInstanceT : TypeInstanceProtocol
-
signalGetInvocationHint()
Extension methodReturns the invocation hint of the innermost signal emission of instance.
Declaration
Swift
@inlinable func signalGetInvocationHint() -> GLibObject.SignalInvocationHintRef!
-
signalHandlerBlock(handlerID:
Extension method) Blocks a handler of an instance so it will not be called during any signal emissions unless it is unblocked again. Thus “blocking” a signal handler means to temporarily deactivate it, a signal handler has to be unblocked exactly the same amount of times it has been blocked before to become active again.
The
handler_id
has to be a valid signal handler id, connected to a signal ofinstance
.Declaration
Swift
@inlinable func signalHandlerBlock(handlerID: Int)
-
signalHandlerDisconnect(handlerID:
Extension method) Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The
handler_id
becomes invalid and may be reused.The
handler_id
has to be a valid signal handler id, connected to a signal ofinstance
.Declaration
Swift
@inlinable func signalHandlerDisconnect(handlerID: Int)
-
signalHandlerFind(mask:
Extension methodsignalID: detail: closure: func: data: ) Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. The matchmask
has to be non-0 for successful matches. If no handler was found, 0 is returned.Declaration
Swift
@inlinable func signalHandlerFind(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureRef? = nil, func: gpointer? = nil, data: gpointer? = nil) -> Int
-
signalHandlerFind(mask:
Extension methodsignalID: detail: closure: func: data: ) Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. The matchmask
has to be non-0 for successful matches. If no handler was found, 0 is returned.Declaration
Swift
@inlinable func signalHandlerFind<ClosureT>(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureT?, func: gpointer? = nil, data: gpointer? = nil) -> Int where ClosureT : ClosureProtocol
-
signalHandlerIsConnected(handlerID:
Extension method) Returns whether
handler_id
is the ID of a handler connected toinstance
.Declaration
Swift
@inlinable func signalHandlerIsConnected(handlerID: Int) -> Bool
-
signalHandlerUnblock(handlerID:
Extension method) Undoes the effect of a previous
g_signal_handler_block()
call. A blocked handler is skipped during signal emissions and will not be invoked, unblocking it (for exactly the amount of times it has been blocked before) reverts its “blocked” state, so the handler will be recognized by the signal system and is called upon future or currently ongoing signal emissions (since the order in which handlers are called during signal emissions is deterministic, whether the unblocked handler in question is called as part of a currently ongoing emission depends on how far that emission has proceeded yet).The
handler_id
has to be a valid id of a signal handler that is connected to a signal ofinstance
and is currently blocked.Declaration
Swift
@inlinable func signalHandlerUnblock(handlerID: Int)
-
signalHandlersBlockMatched(mask:
Extension methodsignalID: detail: closure: func: data: ) Blocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of blocked handlers otherwise.Declaration
Swift
@inlinable func signalHandlersBlockMatched(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureRef? = nil, func: gpointer? = nil, data: gpointer? = nil) -> Int
-
signalHandlersBlockMatched(mask:
Extension methodsignalID: detail: closure: func: data: ) Blocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of blocked handlers otherwise.Declaration
Swift
@inlinable func signalHandlersBlockMatched<ClosureT>(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureT?, func: gpointer? = nil, data: gpointer? = nil) -> Int where ClosureT : ClosureProtocol
-
signalHandlersDestroy()
Extension methodDestroy all signal handlers of a type instance. This function is an implementation detail of the
GObject
dispose implementation, and should not be used outside of the type system.Declaration
Swift
@inlinable func signalHandlersDestroy()
-
Disconnects all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise.Declaration
Swift
@inlinable func signalHandlersDisconnectMatched(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureRef? = nil, func: gpointer? = nil, data: gpointer? = nil) -> Int
-
Disconnects all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise.Declaration
Swift
@inlinable func signalHandlersDisconnectMatched<ClosureT>(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureT?, func: gpointer? = nil, data: gpointer? = nil) -> Int where ClosureT : ClosureProtocol
-
Unblocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of unblocked handlers otherwise. The match criteria should not apply to any handlers that are not currently blocked.Declaration
Swift
@inlinable func signalHandlersUnblockMatched(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureRef? = nil, func: gpointer? = nil, data: gpointer? = nil) -> Int
-
Unblocks all handlers on an instance that match a certain selection criteria. The criteria mask is passed as an OR-ed combination of
GSignalMatchType
flags, and the criteria values are passed as arguments. Passing at least one of theG_SIGNAL_MATCH_CLOSURE
,G_SIGNAL_MATCH_FUNC
orG_SIGNAL_MATCH_DATA
match flags is required for successful matches. If no handlers were found, 0 is returned, the number of unblocked handlers otherwise. The match criteria should not apply to any handlers that are not currently blocked.Declaration
Swift
@inlinable func signalHandlersUnblockMatched<ClosureT>(mask: SignalMatchType, signalID: Int, detail: GQuark, closure: ClosureT?, func: gpointer? = nil, data: gpointer? = nil) -> Int where ClosureT : ClosureProtocol
-
signalHasHandlerPending(signalID:
Extension methoddetail: mayBeBlocked: ) Returns whether there are any handlers connected to
instance
for the given signal id and detail.If
detail
is 0 then it will only match handlers that were connected without detail. Ifdetail
is non-zero then it will match handlers connected both without detail and with the given detail. This is consistent with how a signal emitted withdetail
would be delivered to those handlers.Since 2.46 this also checks for a non-default class closure being installed, as this is basically always what you want.
One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments.
Declaration
Swift
@inlinable func signalHasHandlerPending(signalID: Int, detail: GQuark, mayBeBlocked: Bool) -> Bool
-
signalStopEmission(signalID:
Extension methoddetail: ) Stops a signal’s current emission.
This will prevent the default method from running, if the signal was
G_SIGNAL_RUN_LAST
and you connected normally (i.e. without the “after” flag).Prints a warning if used on a signal which isn’t being emitted.
Declaration
Swift
@inlinable func signalStopEmission(signalID: Int, detail: GQuark)
-
signalStopEmissionByName(detailedSignal:
Extension method) Stops a signal’s current emission.
This is just like
g_signal_stop_emission()
except it will look up the signal id for you.Declaration
Swift
@inlinable func signalStopEmissionByName(detailedSignal: UnsafePointer<gchar>!)
-
isFloating
Extension methodChecks whether
object
has a floating reference.Declaration
Swift
@inlinable var isFloating: Bool { get }
-
gTypeInstance
Extension methodUndocumented
Declaration
Swift
@inlinable var gTypeInstance: GTypeInstance { get }
-
freeze(context:
Extension method) Freeze notifications
Declaration
Swift
@inlinable func freeze(context: UnsafeMutablePointer<GObjectNotifyContext>?) -> UnsafeMutablePointer<GObjectNotifyQueue>?
Parameters
context
notification context to freeze
-
thaw(queue:
Extension method) Unfreeze notifications
Declaration
Swift
@inlinable func thaw(queue nq: UnsafeMutablePointer<GObjectNotifyQueue>)
Parameters
queue
notification queue to thaw
-
new(type:
Extension method) Create a new instance of a given type
Declaration
Swift
@inlinable static func new(type: GType) -> gpointer!
Parameters
type
a type registered with g_type_register_*()
Return Value
pointer to the instance of the given type
-
newReferenceTo(instanceOf:
Extension method) -
new(_:
Extension method) Create an instance of a given type
Declaration
Swift
@inlinable static func new(_ t: GType) -> Object!
Parameters
t
a type registered with g_type_register_*()
Return Value
reference-counted object, wrapping the pointer to the given type instance
-
connect(_:
Extension methodflags: handler: ) Connects a (Void) -> Void closure or function to a typed signal for the receiver object. Similar to
g_signal_connect()
, but allows to provide a Swift closure that can capture its surrounding context.Declaration
Swift
@discardableResult @inlinable func connect<S>(_ signal: S, flags f: ConnectFlags = ConnectFlags(0), handler: @escaping SignalHandler) -> Int where S : SignalNameProtocol
Parameters
signal
The signal to connect
flags
The connection flags to use
handler
A Swift closure to run whenever the given signal was emitted
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
connectSignal(_:
Extension methodflags: data: destroyData: handler: ) Type-safe wrapper for
g_signal_connect_data()
. Connects a @convention© function to a typed signal for the receiver object.Declaration
Swift
@discardableResult @inlinable func connectSignal<S>(_ signal: S, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer! = nil, destroyData destructor: GClosureNotify? = nil, handler: @escaping GCallback) -> Int where S : SignalNameProtocol
Parameters
signal
The signal to connect
flags
The connection flags to use
data
A pointer to user data to provide to the callback
destroyData
A
GClosureNotify
C function to destroy the data pointed to byuserData
handler
The C function to be called on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
bind(_:
Extension methodtarget: property: flags: ) Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property 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 #GObject instance to be updated with the same value of the “active” property of the action #GObject instance.
If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property 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 g_object_unref() on the returned
GBinding instance.
A #GObject can have multiple bindings.
Declaration
Swift
@discardableResult @inlinable func bind<P, Q, T>(_ source_property: P, target: T, property target_property: Q, flags: BindingFlags = .syncCreate) -> BindingRef! where P : PropertyNameProtocol, Q : PropertyNameProtocol, T : ObjectProtocol
-
bind(_:
Extension methodto: property: flags: transformFrom: transformTo: ) Complete version of bind().
Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding.
If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property on @source will be updated as well. The @transform_from function is only used in case of bidirectional bindings, otherwise it will be ignored
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 g_object_unref() on the returned
GBinding instance.
A #GObject can have multiple bindings.
Declaration
Swift
@discardableResult @inlinable func bind<P, Q, T>(_ source_property: P, to target: T, property target_property: Q, flags f: BindingFlags = .syncCreate, transformFrom transform_from: @escaping ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping ValueTransformer) -> BindingRef! where P : PropertyNameProtocol, Q : PropertyNameProtocol, T : ObjectProtocol
-
bind(_:
Extension methodto: property: flags: convertFrom: convertTo: ) Complete version of bind() with strongly typed transformers.
Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding.
If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property on @source will be updated as well. The @transform_from function is only used in case of bidirectional bindings, otherwise it will be ignored
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 g_object_unref() on the returned
GBinding instance.
A #GObject can have multiple bindings.
Declaration
Swift
@discardableResult @inlinable func bind<P, Q, T, U, V>(_ source_property: P, to target: T, property target_property: Q, flags fl: BindingFlags = .syncCreate, convertFrom f: @escaping (U?) -> V? = { _ in nil }, convertTo g: @escaping (V?) -> U?) -> BindingRef! where P : PropertyNameProtocol, Q : PropertyNameProtocol, T : ObjectProtocol
-
bind(_:
Extension methodto: property: flags: convertFrom: convertTo: ) Complete version of bind() with strongly typed transformers.
Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding.
If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if @target_property on @target changes then the @source_property on @source will be updated as well. The @transform_from function is only used in case of bidirectional bindings, otherwise it will be ignored
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 g_object_unref() on the returned
GBinding instance.
A #GObject can have multiple bindings.
Declaration
Swift
@discardableResult @inlinable func bind<P, Q, T, U, V>(_ source_property: P, to target: T, property target_property: Q, flags fl: BindingFlags = .syncCreate, convertFrom f: @escaping (U) -> V? = { _ in nil }, convertTo g: @escaping (V) -> U?) -> BindingRef! where P : PropertyNameProtocol, Q : PropertyNameProtocol, T : ObjectProtocol
-
emit(signal:
Extension methoddetail: arguments: ) Emit a signal with a given number and arguments.
Declaration
Swift
@inlinable func emit(signal number: Int, detail quark: GQuark = 0, arguments: [CVarArg])
Parameters
number
signal number
quark
the detail (defaults to 0)
arguments
array of arguments passed to the signal, followed by a location for the return value (if required)
-
emit(signal:
Extension methoddetail: _: ) Emit a signal with a given number and parameters.
Declaration
Swift
@inlinable func emit(signal number: Int, detail quark: GQuark = 0, _ parameters: CVarArg...)
Parameters
number
signal number
quark
the detail (defaults to 0)
parameters
list of parameters passed to the signal, followed by a location for the return value (if required)
-
emit(_:
Extension methodarguments: ) Emit a signal with a given name.
Declaration
Swift
@inlinable func emit<S>(_ signalName: S, arguments: [CVarArg]) where S : SignalNameProtocol
Parameters
signalName
name of the signal to emit
arguments
array of arguments passed to the signal, followed by a location for the return value (if required)
-
emit(_:
Extension method_: ) Emit a signal with a given name.
Declaration
Swift
@inlinable func emit<S>(_ signalName: S, _ parameters: CVarArg...) where S : SignalNameProtocol
Parameters
signalName
name of the signal to emit
parameters
list of parameters passed to the signal, followed by a location for the return value (if required)
-
type
Extension methodUnderlying type
Declaration
Swift
@inlinable var type: GType { get }
-
typeName
Extension methodName of the underlying type
Declaration
Swift
@inlinable var typeName: String { get }
-
addWeakObserver(_:
Extension method) This method registers notification which is called when underlying GObject instance is being released from memory.
- Argument handler: Handler called when instance is being destroyed.
- Argument objectBeingDestroyed: Unsafe pointer to the instance being destroyed.
Declaration
Swift
public func addWeakObserver(_ handler: @escaping (_ objectBeingDestroyed: gpointer) -> Void) -> AnyObject
Return Value
Opaque referenced token. Retain this token to keep notification alive. Releasing this token will result in deregistation of the notification.