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.

  • ptr

    Untyped pointer to the underlying GObject instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
  • object_ptr Default implementation

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

Object signals

  • Connect a Swift signal handler to the given, typed ObjectSignalName signal

    Declaration

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

    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 a C signal handler to the given, typed ObjectSignalName signal

    Declaration

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

    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:handler:) Extension method

    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 to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_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 underlying notify signal

    Declaration

    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 method

    Typed notify signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifySignal: ObjectSignalName { get }

Object Class: ObjectProtocol extension (methods and fields)

  • addToggleRef(notify:data:) Extension method

    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 by g_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 from object to the proxy object, but when there are other references held to object, a strong reference is held. The notify callback is called when the reference from object 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)
  • Adds a weak reference from weak_pointer to object to indicate that the pointer located at weak_pointer_location is only valid during the lifetime of object. When the object is finalized, weak_pointer will be set to nil.

    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 last g_object_unref() might happen in another thread. Use GWeakRef if thread-safety is required.

    Declaration

    Swift

    @inlinable
    func addWeakPointer(weakPointerLocation: UnsafeMutablePointer<gpointer?>!)
  • 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:

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

    Removing the binding by calling g_object_unref() 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 g_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
  • Complete version of g_object_bind_property().

    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. This will release the reference that is being held on the GBinding instance; if you want to hold on to the GBinding 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 both transform_to and transform_from transformation functions; the notify function will be called once, when the binding is removed. If you need different data for each transformation function, please use g_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
  • 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.

    This function is the language bindings friendly version of g_object_bind_property_full(), using GClosures 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
  • 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 then dup_func will be called with a nil argument.

    Note that dup_func is called while user data of object 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?
  • 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 then dup_func will be called with a nil argument.

    Note that dup_func is called while user data of object 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 method

    This function is intended for GObject implementations to re-enforce a floating object reference. Doing this is seldom required: all GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().

    Declaration

    Swift

    @inlinable
    func forceFloating()
  • freezeNotify() Extension method

    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 GObject::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?
  • Gets a property of an object.

    The value can be:

    • an empty GValue initialized by G_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
  • 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?
  • 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() or g_object_unref().

    See g_object_get().

    Declaration

    Swift

    @inlinable
    func getValist(firstPropertyName: UnsafePointer<gchar>!, varArgs: CVaListPointer)
  • Gets n_properties 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.

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

    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) when g_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 on object.

    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 using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_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 method

    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.

    Declaration

    Swift

    @discardableResult
    @inlinable
    func ref() -> GLibObject.ObjectRef!
  • refSink() Extension method

    Increase the reference count of object, and possibly remove the floating 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 g_object_ref().

    Declaration

    Swift

    @discardableResult
    @inlinable
    func refSink() -> GLibObject.ObjectRef!
  • 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)
  • Removes a weak reference from object that was previously added using g_object_add_weak_pointer(). The weak_pointer_location has to match the one used with g_object_add_weak_pointer().

    Declaration

    Swift

    @inlinable
    func removeWeakPointer(weakPointerLocation: UnsafeMutablePointer<gpointer?>!)
  • 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 old_destroy). It’s up to the caller to free this as needed, which may or may not include using old_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 for key.

    Declaration

    Swift

    @inlinable
    func replaceData(key: UnsafePointer<gchar>!, oldval: gpointer? = nil, newval: gpointer? = nil, destroy: GDestroyNotify? = nil, oldDestroy: UnsafeMutablePointer<GDestroyNotify?>! = nil) -> Bool
  • 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 old_destroy). It’s up to the caller to free this as needed, which may or may not include using old_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 method

    Releases 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:data:) Extension method

    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 g_quark_from_string(). 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.

    Declaration

    Swift

    @inlinable
    func setData(key: UnsafePointer<gchar>!, data: gpointer? = nil)
  • 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 if data is nil.

    Declaration

    Swift

    @inlinable
    func setDataFull(key: UnsafePointer<gchar>!, data: gpointer? = nil, destroy: GDestroyNotify? = nil)
  • Sets a property on an object.

    Declaration

    Swift

    @inlinable
    func setProperty<ValueT>(propertyName: UnsafePointer<gchar>!, value: ValueT) where ValueT : ValueProtocol
  • setQdata(quark:data:) Extension method

    This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the object with g_object_get_qdata() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using NULL as pointer essentially removes the data stored.

    Declaration

    Swift

    @inlinable
    func setQdata(quark: GQuark, data: gpointer? = nil)
  • This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.

    Declaration

    Swift

    @inlinable
    func setQdataFull(quark: GQuark, data: gpointer? = nil, destroy: GDestroyNotify? = nil)
  • Sets properties on an object.

    Declaration

    Swift

    @inlinable
    func setValist(firstPropertyName: UnsafePointer<gchar>!, varArgs: CVaListPointer)
  • Sets n_properties properties for an object. Properties to be set will be taken from values. 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 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 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 of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

    Declaration

    Swift

    @inlinable
    func stealQdata(quark: GQuark) -> gpointer?
  • takeRef() Extension method

    If 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 same GObject instance. If g_object_ref_sink() runs first then the result will be that the floating reference is converted to a hard reference. If g_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 method

    Reverts the effect of a previous call to g_object_freeze_notify(). 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 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 method

    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 GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to nil rather than retain a dangling pointer to a potentially invalid GObject instance. Use g_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, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() 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.

    Declaration

    Swift

    @inlinable
    func watch<ClosureT>(closure: ClosureT) where ClosureT : ClosureProtocol
  • weakRef(notify:data:) Extension method

    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. Use GWeakRef if thread-safety is required.

    Declaration

    Swift

    @inlinable
    func weakRef(notify: GWeakNotify?, data: gpointer? = nil)
  • weakUnref(notify:data:) Extension method

    Removes a weak reference callback to an object.

    Declaration

    Swift

    @inlinable
    func weakUnref(notify: GWeakNotify?, data: gpointer? = nil)
  • A variant of g_cclosure_new() which uses object as user_data and calls g_object_watch_closure() on object and the created closure. This function is useful when you have a callback closely associated with a GObject, and want the callback to no longer run after the object is is freed.

    Declaration

    Swift

    @inlinable
    func cclosureNewObject(callbackFunc: @escaping GCallback) -> GLibObject.ClosureRef!
  • A variant of g_cclosure_new_swap() which uses object as user_data and calls g_object_watch_closure() on object and the created closure. This function is useful when you have a callback closely associated with a GObject, and want the callback to no longer run after the object is is freed.

    Declaration

    Swift

    @inlinable
    func cclosureNewObjectSwap(callbackFunc: @escaping GCallback) -> GLibObject.ClosureRef!
  • 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. The handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_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>!)
  • 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
  • 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 to g_signal_connect(), but allows to provide a GClosureNotify for the data which will be called when the signal handler is disconnected and no longer used. Specify connect_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
  • This is similar to g_signal_connect_data(), but uses a closure which ensures that the gobject stays alive during the call to c_handler by temporarily adding a reference count to gobject.

    When the gobject is destroyed the signal handler will be automatically disconnected. Note that this is not currently threadsafe (ie: emitting a signal while gobject 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 method

    Returns the invocation hint of the innermost signal emission of instance.

    Declaration

    Swift

    @inlinable
    func signalGetInvocationHint() -> GLibObject.SignalInvocationHintRef!
  • 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 of instance.

    Declaration

    Swift

    @inlinable
    func signalHandlerBlock(handlerID: Int)
  • 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 of instance.

    Declaration

    Swift

    @inlinable
    func signalHandlerDisconnect(handlerID: Int)
  • 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 match mask 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
  • 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 match mask 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
  • Returns whether handler_id is the ID of a handler connected to instance.

    Declaration

    Swift

    @inlinable
    func signalHandlerIsConnected(handlerID: Int) -> Bool
  • 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 of instance and is currently blocked.

    Declaration

    Swift

    @inlinable
    func signalHandlerUnblock(handlerID: Int)
  • 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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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
  • 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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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 method

    Destroy 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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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 the G_SIGNAL_MATCH_CLOSURE, G_SIGNAL_MATCH_FUNC or G_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
  • 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. If detail 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 with detail 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
  • 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)
  • 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 method

    Checks whether object has a floating reference.

    Declaration

    Swift

    @inlinable
    var isFloating: Bool { get }
  • gTypeInstance Extension method

    Undocumented

    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

    Create a reference to an instance of a given type

    Declaration

    Swift

    @inlinable
    static func newReferenceTo(instanceOf t: GType) -> ObjectRef!

    Parameters

    t

    a type registered with g_type_register_*()

    Return Value

    ObjectRef wrapping the pointer to the given type instance

  • 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(_:flags:handler:) Extension method

    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)

  • 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 by userData

    handler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

  • 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
  • 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
  • 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
  • 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 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:detail:_:) Extension method

    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(_:arguments:) Extension method

    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 method

    Underlying type

    Declaration

    Swift

    @inlinable
    var type: GType { get }
  • typeName Extension method

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