Package org.gnome.gobject

Class GObject

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

Accessible.AccessibleImpl, AccessibleRange.AccessibleRangeImpl, AccessibleText.AccessibleTextImpl, Action.ActionImpl, ActionGroup.ActionGroupImpl, ActionMap.ActionMapImpl, Adapter, AlertDialog, Animation, AnimationTarget, AppInfo.AppInfoImpl, AppInfoMonitor, AppLaunchContext, Application, ApplicationCommandLine, AssistantPage, AsyncInitable.AsyncInitableImpl, AsyncResult.AsyncResultImpl, ATContext, Auth, AuthDomain, AuthenticationRequest, AuthManager, AutomationSession, BackForwardList, Binding, BindingGroup, BookmarkList, Breakpoint, Buildable.BuildableImpl, BuilderCScope, BuilderScope.BuilderScopeImpl, BytesIcon, Cache, Cancellable, CellAreaContext, CellLayout.CellLayoutImpl, CharsetConverter, ChildProxy.ChildProxyImpl, CicpParams, Class, Clipboard, ClipboardPermissionRequest, ColorBalance.ColorBalanceImpl, ColorBalanceChannel, ColorChooser.ColorChooserImpl, ColorChooserRequest, ColorDialog, ColumnViewColumn, ColumnViewRow, Completion, CompletionContext, CompletionProposal.CompletionProposalImpl, CompletionProvider.CompletionProviderImpl, CompletionSnippets, CompletionWords, Constraint, ConstraintGuide, ConstraintTarget.ConstraintTargetImpl, ContentDecoder, ContentDeserializer, ContentProvider, ContentSerializer, ContentSniffer, Context, Context, ContextMenu, ContextMenu, Converter.ConverterImpl, CookieJar, CookieManager, Coverage, Credentials, CssProvider, Cursor, DatagramBased.DatagramBasedImpl, DataQueue, DBusActionGroup, DBusAuthObserver, DBusConnection, DBusInterface.DBusInterfaceImpl, DBusInterfaceSkeleton, DBusMessage, DBusMethodInvocation, DBusObject.DBusObjectImpl, DBusObjectManager.DBusObjectManagerImpl, DBusObjectManagerClient, DBusObjectManagerServer, DBusObjectProxy, DBusObjectSkeleton, DBusProxy, DBusServer, DebugController.DebugControllerImpl, DebugControllerDBus, DesktopAppInfo, DesktopAppInfoLookup.DesktopAppInfoLookupImpl, Device, DeviceInfoPermissionRequest, DeviceTool, DirectoryList, Discoverer, DiscovererInfo, DiscovererStreamInfo, Display, DisplayManager, DmabufTextureBuilder, Download, Drag, DrawContext, Drive.DriveImpl, Drop, DtlsClientConnection.DtlsClientConnectionImpl, DtlsConnection.DtlsConnectionImpl, DtlsServerConnection.DtlsServerConnectionImpl, EditorState, Emblem, EmblemedIcon, EncodingProfile, EncodingTarget, EntryBuffer, EntryCompletion, EnumListItem, EnumListModel, EventController, Exception, FaviconDatabase, File, File.FileImpl, FileChooser.FileChooserImpl, FileChooserRequest, FileDescriptorBased.FileDescriptorBasedImpl, FileDialog, FileEnumerator, FileIcon, FileInfo, FileLauncher, FileLoader, FileMonitor, FilenameCompleter, FileSaver, Filter, FilterListModel, FindController, FlattenListModel, Font, FontChooser.FontChooserImpl, FontDialog, FontFace, FontFamily, FontMap, Fontset, FormSubmissionRequest, Frame, FrameClock, GeolocationManager, GeolocationPermissionRequest, GLShader, GLTextureBuilder, GtkBuilder, GutterLines, HitTestResult, HitTestResult, Hover, HoverContext, HoverProvider.HoverProviderImpl, HSTSEnforcer, Icon.IconImpl, IconPaintable, IconTheme, IMContext, Indenter.IndenterImpl, InetAddress, InetAddressMask, Initable.InitableImpl, InitiallyUnowned, InputMethodContext, InputStream, IOStream, Language, LanguageManager, Layout, Layout, LayoutChild, LayoutManager, LeafletPage, ListHeader, ListIndexModel, ListIndexModel.ListIndex, ListItem, ListItemFactory, ListModel.ListModelImpl, ListStore, ListStore, LoadableIcon.LoadableIconImpl, Logger, MapListModel, MarkAttributes, MediaKeySystemPermissionRequest, MediaStream, MemoryMonitor.MemoryMonitorImpl, MemoryTextureBuilder, MenuAttributeIter, MenuItem, MenuLinkIter, MenuModel, Message, Monitor, Mount.MountImpl, MountOperation, MultiSelection, NativeDialog, Navigation.NavigationImpl, NetworkAddress, NetworkMonitor.NetworkMonitorImpl, NetworkService, NetworkSession, NoSelection, NotebookPage, Notification, Notification, NotificationPermissionRequest, OptionMenu, Orientable.OrientableImpl, OsxAppInfo, OutputStream, PageSetup, Paintable.PaintableImpl, Permission, PermissionRequest.PermissionRequestImpl, Pixbuf, PixbufAnimation, PixbufAnimationIter, PixbufLoader, PointerLockPermissionRequest, PolicyDecision, PowerProfileMonitor.PowerProfileMonitorImpl, Preset.PresetImpl, PrintCompositor, PrintContext, PrintDialog, Printer, PrintJob, PrintOperation, PrintOperation, PrintOperationPreview.PrintOperationPreviewImpl, PrintSettings, PropertyAction, Proxy.ProxyImpl, ProxyResolver.ProxyResolverImpl, RecentManager, Region, RemoteActionGroup.RemoteActionGroupImpl, Renderer, Renderer, Resolver, ScriptWorld, Scrollable.ScrollableImpl, SearchContext, SearchSettings, Seat, SectionModel.SectionModelImpl, SecurityManager, Seekable.SeekableImpl, SelectionFilterModel, SelectionModel.SelectionModelImpl, Server, ServerMessage, Session, SessionFeature.SessionFeatureImpl, Settings, Settings, Settings, SettingsBackend, Shortcut, ShortcutAction, ShortcutManager.ShortcutManagerImpl, ShortcutTrigger, SignalGroup, SimpleAction, SimpleActionGroup, SimpleAsyncResult, SimpleProxyResolver, SingleSelection, SizeGroup, SliceListModel, Snapshot, Snippet, SnippetContext, SnippetManager, Socket, SocketAddress, SocketAddressEnumerator, SocketClient, SocketConnectable.SocketConnectableImpl, SocketControlMessage, SocketListener, Sorter, SortListModel, SpaceDrawer, SpinnerPaintable, SqueezerPage, StackPage, StreamVolume.StreamVolumeImpl, StringList, StringObject, Style, StyleContext, StyleManager, StyleProvider.StyleProviderImpl, StyleScheme, StyleSchemeChooser.StyleSchemeChooserImpl, StyleSchemeManager, Subprocess, SubprocessLauncher, Surface, SwipeTracker, SymbolicPaintable.SymbolicPaintableImpl, TabPage, Task, TestDBus, TextBuffer, TextChildAnchor, TextMark, TextTag, TextTagTable, Texture, ThemedIcon, TlsBackend.TlsBackendImpl, TlsCertificate, TlsDatabase, TlsInteraction, TlsPassword, Toast, Tooltip, TreeDragDest.TreeDragDestImpl, TreeDragSource.TreeDragSourceImpl, TreeListModel, TreeListRow, TreeModel.TreeModelImpl, TreeModelFilter, TreeModelSort, TreeSelection, TreeSortable.TreeSortableImpl, TreeStore, TypeModule, TypePlugin.TypePluginImpl, UnixFDList, UnixMountMonitor, URIHandler.URIHandlerImpl, UriLauncher, URIRequest, URIRequest, URIResponse, URIResponse, URISchemeRequest, URISchemeResponse, UserContentFilterStore, UserContentManager, UserMediaPermissionRequest, Value, Vfs, VideoDirection.VideoDirectionImpl, VideoOrientation.VideoOrientationImpl, VideoOverlay.VideoOverlayImpl, ViewStackPage, ViewStackPages, VirtualMachine, Volume.VolumeImpl, VolumeMonitor, WeakValue, WebContext, WebEditor, WebFormManager, WebHitTestResult, WebInspector, WebPage, WebProcessExtension, WebResource, WebsiteDataAccessPermissionRequest, WebsiteDataManager, WebsitePolicies, WebsocketConnection, WebsocketExtension, WebsocketExtensionManager, WidgetPaintable, WindowGroup, WindowProperties, ZlibCompressor, ZlibDecompressor

@Generated("io.github.jwharm.JavaGI")
public class GObject
extends TypeInstance

The base object type.

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

For a tutorial on implementing a new GObject class, see [How to define and implement a new GObject](tutorial.htmlhow-to-define-and-implement-a-new-gobject). For a list of naming conventions for GObjects and their methods, see the GType conventions. For the high-level concepts behind GObject, read Instantiatable classed types: Objects.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GObject.Builder<B extends GObject.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	GObject.NotifyCallback	Functional interface declaration of the NotifyCallback callback.
static class	GObject.ObjectClass	The class structure for the GObject type.

Constructor Summary

Constructors

Constructor	Description
GObject(MemorySegment address)	Create a GObject proxy instance for the provided memory address.
GObject(Type objectType, String firstPropertyName, Object... varargs)	Creates a new instance of a GObject subtype and sets its properties.

Method Summary

Modifier and Type	Method	Description
void	addToggleRef(ToggleNotify notify)	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.
void	addWeakPointer(Out<MemorySegment> weakPointerLocation)	Adds a weak reference from weak_pointer to this Object to indicate that the pointer located at weakPointerLocation is only valid during the lifetime of this Object.
protected GObject	asParent()	Returns this instance as if it were its parent type.
<S, T> BindingBuilder<S,T>	bindProperty(String sourceProperty, GObject target, String targetProperty)	Creates a binding between sourceProperty on this Object and targetProperty on target.
Binding	bindProperty(String sourceProperty, GObject target, String targetProperty, Set<BindingFlags> flags)	Creates a binding between sourceProperty on this Object and targetProperty on target.
Binding	bindProperty(String sourceProperty, GObject target, String targetProperty, BindingFlags... flags)	Creates a binding between sourceProperty on this Object and targetProperty on target.
Binding	bindPropertyFull(String sourceProperty, GObject target, String targetProperty, Set<BindingFlags> flags, @Nullable BindingTransformFunc transformTo, @Nullable BindingTransformFunc transformFrom)	Complete version of g_object_bind_property().
Binding	bindPropertyFull(String sourceProperty, GObject target, String targetProperty, BindingFlags flags, @Nullable BindingTransformFunc transformTo, @Nullable BindingTransformFunc transformFrom)	Complete version of g_object_bind_property().
Binding	bindPropertyWithClosures(String sourceProperty, GObject target, String targetProperty, Set<BindingFlags> flags, Closure transformTo, Closure transformFrom)	Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.
Binding	bindPropertyWithClosures(String sourceProperty, GObject target, String targetProperty, BindingFlags flags, Closure transformTo, Closure transformFrom)	Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.
static GObject.Builder<? extends GObject.Builder>	builder()	A GObject.Builder object constructs a GObject with the specified properties.
static long	compatControl(long what, @Nullable MemorySegment data)
GObject	connect(String signalSpec, Object... varargs)	A convenience function to connect multiple signals at once.
<T> SignalConnection	connect(String detailedSignal, T callback)	Connect a callback to a signal for this object.
<T> SignalConnection	connect(String detailedSignal, T callback, boolean after)	Connect a callback to a signal for this object.
protected void	constructed()	the constructed function is called by g_object_new() as the final step of the object creation process.
void	disconnect(String signalSpec, Object... varargs)	A convenience function to disconnect multiple signals at once.
protected void	dispatchPropertiesChanged(int nPspecs, ParamSpec[] pspecs)	emits property change notification for a bunch of properties.
protected void	dispose()	the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work.
MemorySegment	dupData(String key, @Nullable DuplicateFunc dupFunc)	This is a variant of g_object_get_data() which returns a 'duplicate' of the value.
MemorySegment	dupQdata(Quark quark, @Nullable DuplicateFunc dupFunc)	This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value.
Object	emit(String detailedSignal, Object... params)	Emits a signal from this object.
void	emitNotify(@Nullable String detail, ParamSpec pspec)	Emits the "notify" signal.
protected void	finalize_()	instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize_ method of the parent class.
void	forceFloating()	This function is intended for GObject implementations to re-enforce a [floating][floating-ref] object reference.
void	freezeNotify()	Increases the freeze count on this Object.
void	get(String firstPropertyName, Object... varargs)	Gets properties of an object.
MemorySegment	getData(String key)	Gets a named field from the objects table of associations (see g_object_set_data()).
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
protected void	getProperty(int propertyId, Value value, ParamSpec pspec)	the generic getter for all properties of this type.
Object	getProperty(String propertyName)	Get a property of an object.
void	getProperty(String propertyName, Value value)	Gets a property of an object.
MemorySegment	getQdata(Quark quark)	This function gets back user data pointers stored via g_object_set_qdata().
static Type	getType()	Get the GType of the GObject class
void	getv(String[] names, Value[] values)	Gets nProperties properties for an this Object.
static ParamSpec	interfaceFindProperty(TypeInterface gIface, String propertyName)	Find the GParamSpec with the given name for an interface.
static void	interfaceInstallProperty(TypeInterface gIface, ParamSpec pspec)	Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types.
static ParamSpec[]	interfaceListProperties(TypeInterface gIface)	Lists the properties of an interface.Generally, the interface vtable passed in as gIface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().
boolean	isFloating()	Checks whether this Object has a [floating][floating-ref] reference.
static <T extends GObject> T	newInstance(Type objectType)	Creates a new GObject instance of the provided GType.
static <T extends GObject> T	newInstance(Type objectType, Object... propertyNamesAndValues)	Creates a new GObject instance of the provided GType and with the provided property values.
static GObject	newv(Type objectType, Parameter[] parameters)	Deprecated. Use g_object_new_with_properties() instead.
void	notify(String propertyName)	Emits a "notify" signal for the property propertyName on this Object.
protected void	notify(ParamSpec pspec)	Emits a "notify" signal for the property propertyName on this Object.
void	notifyByPspec(ParamSpec pspec)	Emits a "notify" signal for the property specified by pspec on this Object.
SignalConnection<GObject.NotifyCallback>	onNotify(@Nullable String detail, GObject.NotifyCallback handler)	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.
GObject	ref()	Increases the reference count of this Object.
GObject	refSink()	Increase the reference count of this Object, and possibly remove the [floating][floating-ref] reference, if this Object has a floating reference.
void	removeToggleRef(ToggleNotify notify)	Removes a reference added with g_object_add_toggle_ref().
void	removeWeakPointer(Out<MemorySegment> weakPointerLocation)	Removes a weak reference from this Object that was previously added using g_object_add_weak_pointer().
boolean	replaceData(String key, @Nullable MemorySegment oldval, @Nullable MemorySegment newval, @Nullable Out<DestroyNotify> oldDestroy)	Compares the user data for the key key on this Object with oldval, and if they are the same, replaces oldval with newval.
boolean	replaceQdata(Quark quark, @Nullable MemorySegment oldval, @Nullable MemorySegment newval, @Nullable Out<DestroyNotify> oldDestroy)	Compares the user data for the key quark on this Object with oldval, and if they are the same, replaces oldval with newval.
void	runDispose()	Releases all references to other objects.
void	set(String firstPropertyName, Object... varargs)	Sets properties on an object.
void	setData(String key, @Nullable MemorySegment data)	Each object carries around a table of associations from strings to pointers.
void	setDataFull(String key, @Nullable MemorySegment data)	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.
protected void	setProperty(int propertyId, Value value, ParamSpec pspec)	the generic setter for all properties of this type.
void	setProperty(String propertyName, Object value)	Set a property of an object.
void	setProperty(String propertyName, Value value)	Sets a property on an object.
void	setQdata(Quark quark, @Nullable MemorySegment data)	This sets an opaque, named pointer on an object.
void	setQdataFull(Quark quark, @Nullable MemorySegment data)	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 this Object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.
void	setv(String[] names, Value[] values)	Sets nProperties properties for an this Object.
MemorySegment	stealData(String key)	Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
MemorySegment	stealQdata(Quark quark)	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).
GObject	takeRef()	If this Object is floating, sink it.
void	thawNotify()	Reverts the effect of a previous call to g_object_freeze_notify().
void	unref()	Decreases the reference count of this Object.
void	watchClosure(Closure closure)	This function essentially limits the life time of the closure to the life time of the object.
void	weakRef(WeakNotify notify)	Adds a weak reference callback to an object.
void	weakUnref(WeakNotify notify)	Removes a weak reference callback to an object.
static GObject	withProperties(Type objectType, String[] names, Value[] values)	Creates a new instance of a GObject subtype and sets its properties using the provided arrays.

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GObject

public GObject(MemorySegment address)

Create a GObject proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

GObject

public GObject(Type objectType,
 String firstPropertyName,
 Object... varargs)

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

Construction parameters (see ParamFlags.CONSTRUCT, ParamFlags.CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. Any private data for the object is guaranteed to be initialized with zeros, as per g_type_create_instance().

Note that in C, small integer types in variable argument lists are promoted up to gint or guint as appropriate, and read back accordingly. gint is 32 bits on every platform on which GLib is currently supported. This means that you can use C expressions of type gint with g_object_new() and properties of type gint or guint or smaller. Specifically, you can use integer literals with these property types.

When using property types of gint64 or guint64, you must ensure that the value that you provide is 64 bit. This means that you should use a cast or make use of the G_GINT64_CONSTANT or G_GUINT64_CONSTANT macros.

Similarly, gfloat is promoted to gdouble, so you must ensure that the value you provide is a gdouble, even for a property of type gfloat.

Since GLib 2.72, all GObjects are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is guint64 or gdouble). If you need larger alignment for an element in a GObject, you should allocate it on the heap (aligned), or arrange for your GObject to be appropriately padded.

Parameters:

objectType - the type id of the GObject subtype to instantiate

firstPropertyName - the name of the first property

varargs - the value of the first property, followed optionally by more name/value pairs, followed by null

Method Details

getType

public static Type getType()

Get the GType of the GObject class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected GObject asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

withProperties

public static GObject withProperties(Type objectType,
 String[] names,
 Value[] values)

Creates a new instance of a GObject subtype and sets its properties using the provided arrays. Both arrays must have exactly nProperties elements, and the names and values correspond by index.

Construction parameters (see ParamFlags.CONSTRUCT, ParamFlags.CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.

Parameters:

objectType - the object type to instantiate

names - the names of each property to be set

values - the values of each property to be set

Returns:

a new instance of objectType

newv

@Deprecated
public static GObject newv(Type objectType,
 Parameter[] parameters)

Deprecated.

Use g_object_new_with_properties() instead. deprecated. See GParameter for more information.

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

Construction parameters (see ParamFlags.CONSTRUCT, ParamFlags.CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.

Parameters:

objectType - the type id of the GObject subtype to instantiate

parameters - an array of GParameter

Returns:

a new instance of objectType

compatControl

public static long compatControl(long what,
 @Nullable
 @Nullable MemorySegment data)

interfaceFindProperty

public static ParamSpec interfaceFindProperty(TypeInterface gIface,
 String propertyName)

Find the GParamSpec with the given name for an interface. Generally, the interface vtable passed in as gIface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

Parameters:

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

propertyName - name of a property to look up.

Returns:

the GParamSpec for the property of the interface with the name propertyName, or null if no such property exists.

interfaceInstallProperty

public static void interfaceInstallProperty(TypeInterface gIface,
 ParamSpec pspec)

Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

This function is meant to be called from the interface's default vtable initialization function (the classInit member of GTypeInfo.) It must not be called after after classInit has been called for any object types implementing this interface.

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

Parameters:

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

pspec - the GParamSpec for the new property

interfaceListProperties

public static ParamSpec[] interfaceListProperties(TypeInterface gIface)

Lists the properties of an interface.Generally, the interface vtable passed in as gIface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

Parameters:

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

Returns:

a pointer to an array of pointers to GParamSpec structures. The paramspecs are owned by GLib, but the array should be freed with g_free() when you are done with it.

addToggleRef

public void addToggleRef(ToggleNotify notify)

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 this 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 this Object, only a weak reference is held in the reverse direction from this Object to the proxy object, but when there are other references held to this Object, a strong reference is held. The notify callback is called when the reference from this Object to the proxy object should be "toggled" from strong to weak (isLastRef true) or weak to strong (isLastRef 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.

Note that if you unref the object on another thread, then notify might still be invoked after g_object_remove_toggle_ref(), and the object argument might be a dangling pointer. If the object is destroyed on other threads, you must take care of that yourself.

A g_object_add_toggle_ref() must be released with g_object_remove_toggle_ref().

Parameters:

notify - a function to call when this reference is the last reference to the object, or is no longer the last reference.

addWeakPointer

public void addWeakPointer(Out<MemorySegment> weakPointerLocation)

Adds a weak reference from weak_pointer to this Object to indicate that the pointer located at weakPointerLocation is only valid during the lifetime of this Object. When the this Object is finalized, weakPointer will be set to null.

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.

Parameters:

weakPointerLocation - The memory address of a pointer.

bindProperty

public Binding bindProperty(String sourceProperty,
 GObject target,
 String targetProperty,
 Set<BindingFlags> flags)

Creates a binding between sourceProperty on this Object and targetProperty on target.

Whenever the sourceProperty is changed the targetProperty is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);
 

Will result in the "sensitive" property of the widget GObject instance to be updated with the same value of the "active" property of the action GObject instance.

If flags contains BindingFlags.BIDIRECTIONAL then the binding will be mutual: if targetProperty on target changes then the sourceProperty on this Object will be updated as well.

The binding will automatically be removed when either the this Object or the target instances are finalized. To remove the binding without affecting the this Object 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, this Object and target are only used from a single thread and it is clear that both this Object and target outlive the binding. Especially it is not safe to rely on this if the binding, this Object 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.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

bindProperty

public Binding bindProperty(String sourceProperty,
 GObject target,
 String targetProperty,
 BindingFlags... flags)

Creates a binding between sourceProperty on this Object and targetProperty on target.

Whenever the sourceProperty is changed the targetProperty is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);
 

Will result in the "sensitive" property of the widget GObject instance to be updated with the same value of the "active" property of the action GObject instance.

If flags contains BindingFlags.BIDIRECTIONAL then the binding will be mutual: if targetProperty on target changes then the sourceProperty on this Object will be updated as well.

The binding will automatically be removed when either the this Object or the target instances are finalized. To remove the binding without affecting the this Object 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, this Object and target are only used from a single thread and it is clear that both this Object and target outlive the binding. Especially it is not safe to rely on this if the binding, this Object 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.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

bindPropertyFull

public Binding bindPropertyFull(String sourceProperty,
 GObject target,
 String targetProperty,
 Set<BindingFlags> flags,
 @Nullable
 @Nullable BindingTransformFunc transformTo,
 @Nullable
 @Nullable BindingTransformFunc transformFrom)

Complete version of g_object_bind_property().

Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.

If flags contains BindingFlags.BIDIRECTIONAL then the binding will be mutual: if targetProperty on target changes then the sourceProperty on this Object will be updated as well. The transformFrom function is only used in case of bidirectional bindings, otherwise it will be ignored

The binding will automatically be removed when either the this Object 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 userData parameter will be used for both transformTo and transformFrom 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.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

transformTo - the transformation function from the this Object to the target, or null to use the default

transformFrom - the transformation function from the target to the this Object, or null to use the default

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

bindPropertyFull

public Binding bindPropertyFull(String sourceProperty,
 GObject target,
 String targetProperty,
 BindingFlags flags,
 @Nullable
 @Nullable BindingTransformFunc transformTo,
 @Nullable
 @Nullable BindingTransformFunc transformFrom)

Complete version of g_object_bind_property().

Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.

If flags contains BindingFlags.BIDIRECTIONAL then the binding will be mutual: if targetProperty on target changes then the sourceProperty on this Object will be updated as well. The transformFrom function is only used in case of bidirectional bindings, otherwise it will be ignored

The binding will automatically be removed when either the this Object 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 userData parameter will be used for both transformTo and transformFrom 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.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

transformTo - the transformation function from the this Object to the target, or null to use the default

transformFrom - the transformation function from the target to the this Object, or null to use the default

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

bindPropertyWithClosures

public Binding bindPropertyWithClosures(String sourceProperty,
 GObject target,
 String targetProperty,
 Set<BindingFlags> flags,
 Closure transformTo,
 Closure transformFrom)

Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.

This function is the language bindings friendly version of g_object_bind_property_full(), using GClosures instead of function pointers.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

transformTo - a GClosure wrapping the transformation function from the this Object to the target, or null to use the default

transformFrom - a GClosure wrapping the transformation function from the target to the this Object, or null to use the default

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

bindPropertyWithClosures

public Binding bindPropertyWithClosures(String sourceProperty,
 GObject target,
 String targetProperty,
 BindingFlags flags,
 Closure transformTo,
 Closure transformFrom)

Creates a binding between sourceProperty on this Object and targetProperty on target, allowing you to set the transformation functions to be used by the binding.

This function is the language bindings friendly version of g_object_bind_property_full(), using GClosures instead of function pointers.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

transformTo - a GClosure wrapping the transformation function from the this Object to the target, or null to use the default

transformFrom - a GClosure wrapping the transformation function from the target to the this Object, or null to use the default

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

connect

public GObject connect(String signalSpec,
 Object... varargs)

A convenience function to connect multiple signals at once.

The signal specs expected by this function have the form modifier::signal_name, where modifier can be one of the following:

• signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)
• object-signal, object_signal: equivalent to g_signal_connect_object (..., G_CONNECT_DEFAULT)
• swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)
• swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED)
• signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER)
• object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER)
• swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)
• swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)

menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
                                                  "type", GTK_WINDOW_POPUP,
                                                  "child", menu,
                                                  NULL),
                                    "signal::event", gtk_menu_window_event, menu,
                                    "signal::size_request", gtk_menu_window_size_request, menu,
                                    "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
                                    NULL);
 

Parameters:

signalSpec - the spec for the first signal

varargs - GObject.Callback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by NULL

Returns:

the object

disconnect

public void disconnect(String signalSpec,
 Object... varargs)

A convenience function to disconnect multiple signals at once.

The signal specs expected by this function have the form "any_signal", which means to disconnect any signal with matching callback and data, or "any_signal::signal_name", which only disconnects the signal named "signal_name".

Parameters:

signalSpec - the spec for the first signal

varargs - GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by null

dupData

public MemorySegment dupData(String key,
 @Nullable
 @Nullable DuplicateFunc dupFunc)

This is a variant of g_object_get_data() which returns a 'duplicate' of the value. dupFunc 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 dupFunc will be called with a null argument.

Note that dupFunc is called while user data of this 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.

Parameters:

key - a string, naming the user data pointer

dupFunc - function to dup the value

Returns:

the result of calling dupFunc on the value associated with key on this Object, or null if not set. If dupFunc is null, the value is returned unmodified.

dupQdata

public MemorySegment dupQdata(Quark quark,
 @Nullable
 @Nullable DuplicateFunc dupFunc)

This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. dupFunc 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 dupFunc will be called with a null argument.

Note that dupFunc is called while user data of this 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.

Parameters:

quark - a GQuark, naming the user data pointer

dupFunc - function to dup the value

Returns:

the result of calling dupFunc on the value associated with quark on this Object, or null if not set. If dupFunc is null, the value is returned unmodified.

forceFloating

public void forceFloating()

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

freezeNotify

public void freezeNotify()

Increases the freeze count on this Object. If the freeze count is non-zero, the emission of "notify" signals on this 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.

get

public void get(String firstPropertyName,
 Object... varargs)

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

Here is an example of using g_object_get() to get the contents of three properties: an integer, a string and an object:

 gint intval;
  guint64 uint64val;
  gchar *strval;
  GObject *objval;

  g_object_get (my_object,
                "int-property", &intval,
                "uint64-property", &uint64val,
                "str-property", &strval,
                "obj-property", &objval,
                NULL);

  // Do something with intval, uint64val, strval, objval

  g_free (strval);
  g_object_unref (objval);
 

Parameters:

firstPropertyName - name of the first property to get

varargs - return location for the first property, followed optionally by more name/return location pairs, followed by null

getData

public MemorySegment getData(String key)

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

Parameters:

key - name of the key for that association

Returns:

the data if found, or null if no such data exists.

getProperty

public void getProperty(String propertyName,
 Value value)

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.

Parameters:

propertyName - the name of the property to get

value - return location for the property value

getQdata

public MemorySegment getQdata(Quark quark)

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

Parameters:

quark - A GQuark, naming the user data pointer

Returns:

The user data pointer set, or null

getv

public void getv(String[] names,
 Value[] values)

Gets nProperties properties for an this 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.

Parameters:

names - the names of each property to get

values - the values of each property to get

isFloating

public boolean isFloating()

Checks whether this Object has a [floating][floating-ref] reference.

Returns:

true if this Object has a floating reference

notify

public void notify(String propertyName)

Emits a "notify" signal for the property propertyName on this 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.

Parameters:

propertyName - the name of a property installed on the class of this Object.

notifyByPspec

public void notifyByPspec(ParamSpec pspec)

Emits a "notify" signal for the property specified by pspec on this 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.:

  typedef enum
   {
     PROP_FOO = 1,
     PROP_LAST
   } MyObjectProperty;

   static GParamSpec *properties[PROP_LAST];

   static void
   my_object_class_init (MyObjectClass *klass)
   {
     properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                              0, 100,
                                              50,
                                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
     g_object_class_install_property (gobject_class,
                                      PROP_FOO,
                                      properties[PROP_FOO]);
   }
 

and then notify a change on the "foo" property with:

  g_object_notify_by_pspec (self, properties[PROP_FOO]);
 

Parameters:

pspec - the GParamSpec of a property installed on the class of this Object.

ref

public GObject ref()

Increases the reference count of this Object.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of this 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.

Returns:

the same this Object

refSink

public GObject refSink()

Increase the reference count of this Object, and possibly remove the [floating][floating-ref] reference, if this 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 this Object will be propagated to the return type under the same conditions as for g_object_ref().

Returns:

this Object

removeToggleRef

public void removeToggleRef(ToggleNotify notify)

Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one.

Note that if you unref the object on another thread, then notify might still be invoked after g_object_remove_toggle_ref(), and the object argument might be a dangling pointer. If the object is destroyed on other threads, you must take care of that yourself.

Parameters:

notify - a function to call when this reference is the last reference to the object, or is no longer the last reference.

removeWeakPointer

public void removeWeakPointer(Out<MemorySegment> weakPointerLocation)

Removes a weak reference from this Object that was previously added using g_object_add_weak_pointer(). The weakPointerLocation has to match the one used with g_object_add_weak_pointer().

Parameters:

weakPointerLocation - The memory address of a pointer.

replaceData

public boolean replaceData(String key,
 @Nullable
 @Nullable MemorySegment oldval,
 @Nullable
 @Nullable MemorySegment newval,
 @Nullable
 @Nullable Out<DestroyNotify> oldDestroy)

Compares the user data for the key key on this Object with oldval, and if they are the same, replaces oldval with newval.

This is like a typical atomic compare-and-exchange operation, for user data on an object.

If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in oldDestroy). It’s up to the caller to free this as needed, which may or may not include using oldDestroy 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.

Parameters:

key - a string, naming the user data pointer

oldval - the old value to compare against

newval - the new value

oldDestroy - destroy notify for the existing value

Returns:

true if the existing value for key was replaced by newval, false otherwise.

replaceQdata

public boolean replaceQdata(Quark quark,
 @Nullable
 @Nullable MemorySegment oldval,
 @Nullable
 @Nullable MemorySegment newval,
 @Nullable
 @Nullable Out<DestroyNotify> oldDestroy)

Compares the user data for the key quark on this Object with oldval, and if they are the same, replaces oldval with newval.

This is like a typical atomic compare-and-exchange operation, for user data on an object.

If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in oldDestroy). It’s up to the caller to free this as needed, which may or may not include using oldDestroy as sometimes replacement should not destroy the object in the normal way.

Parameters:

quark - a GQuark, naming the user data pointer

oldval - the old value to compare against

newval - the new value

oldDestroy - destroy notify for the existing value

Returns:

true if the existing value for quark was replaced by newval, false otherwise.

runDispose

public void runDispose()

Releases all references to other objects. This can be used to break reference cycles.

This function should only be called from object system implementations.

set

public void set(String firstPropertyName,
 Object... varargs)

Sets properties on an object.

The same caveats about passing integer literals as varargs apply as with g_object_new(). In particular, any integer literals set as the values for properties of type gint64 or guint64 must be 64 bits wide, using the G_GINT64_CONSTANT or G_GUINT64_CONSTANT macros.

Note that the "notify" signals are queued and only emitted (in reverse order) after all properties have been set. See g_object_freeze_notify().

Parameters:

firstPropertyName - name of the first property to set

varargs - value for the first property, followed optionally by more name/value pairs, followed by null

setData

public void setData(String key,
 @Nullable
 @Nullable MemorySegment data)

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

Parameters:

key - name of the key

data - data to associate with that key

setDataFull

public void setDataFull(String key,
 @Nullable
 @Nullable MemorySegment data)

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

Parameters:

key - name of the key

data - data to associate with that key

setProperty

public void setProperty(String propertyName,
 Value value)

Sets a property on an object.

Parameters:

propertyName - the name of the property to set

value - the value

setQdata

public void setQdata(Quark quark,
 @Nullable
 @Nullable MemorySegment data)

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 this Object with g_object_get_qdata() until the this 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.

Parameters:

quark - A GQuark, naming the user data pointer

data - An opaque user data pointer

setQdataFull

public void setQdataFull(Quark quark,
 @Nullable
 @Nullable MemorySegment data)

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 this Object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.

Parameters:

quark - A GQuark, naming the user data pointer

data - An opaque user data pointer

setv

public void setv(String[] names,
 Value[] values)

Sets nProperties properties for an this 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.

Parameters:

names - the names of each property to be set

values - the values of each property to be set

stealData

public MemorySegment stealData(String key)

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

Parameters:

key - name of the key

Returns:

the data if found, or null if no such data exists.

stealQdata

public MemorySegment stealQdata(Quark quark)

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:

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

Parameters:

quark - A GQuark, naming the user data pointer

Returns:

The user data pointer set, or null

takeRef

public GObject takeRef()

If this 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 always 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.

Returns:

this Object

thawNotify

public void thawNotify()

Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on this 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.

unref

public void unref()

Decreases the reference count of this 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 null rather than retain a dangling pointer to a potentially invalid GObject instance. Use g_clear_object() for this.

watchClosure

public void watchClosure(Closure closure)

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 this Object during invocation of the closure. Usually, this function will be called on closures that use this this Object as closure data.

Parameters:

closure - GClosure to watch

weakRef

public void weakRef(WeakNotify notify)

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.

Parameters:

notify - callback to invoke before the object is freed

weakUnref

public void weakUnref(WeakNotify notify)

Removes a weak reference callback to an object.

Parameters:

notify - callback to search for

constructed

protected void constructed()

the constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. constructed implementors should chain up to the constructed call of their parent class to allow it to complete its initialisation.

dispatchPropertiesChanged

protected void dispatchPropertiesChanged(int nPspecs,
 ParamSpec[] pspecs)

emits property change notification for a bunch of properties. Overriding dispatchPropertiesChanged should be rarely needed.

dispose

protected void dispose()

the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, dispose should chain up to the dispose method of the parent class.

finalize_

protected void finalize_()

instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize_ method of the parent class.

getProperty

protected void getProperty(int propertyId,
 Value value,
 ParamSpec pspec)

the generic getter for all properties of this type. Should be overridden for every type with properties.

notify

protected void notify(ParamSpec pspec)

Emits a "notify" signal for the property propertyName on this 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.

setProperty

protected void setProperty(int propertyId,
 Value value,
 ParamSpec pspec)

the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of setProperty don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

onNotify

public SignalConnection<GObject.NotifyCallback> onNotify(@Nullable
 @Nullable String detail,
 GObject.NotifyCallback handler)

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

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 GObject.ParamSpec#parameter-names as detail strings for the notify signal.

Parameters:

detail - the signal detail

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• GObject.NotifyCallback.run(org.gnome.gobject.ParamSpec)

emitNotify

public void emitNotify(@Nullable
 @Nullable String detail,
 ParamSpec pspec)

Emits the "notify" signal. See onNotify(java.lang.String, org.gnome.gobject.GObject.NotifyCallback).

builder

public static GObject.Builder<? extends GObject.Builder> builder()

A GObject.Builder object constructs a GObject with the specified properties. Use the various set...() methods to set properties, and finish construction with GObject.Builder.build().

newInstance

public static <T extends GObject> T newInstance(Type objectType)

Creates a new GObject instance of the provided GType.

Parameters:

objectType - the GType of the new GObject

Returns:

the newly created GObject instance

newInstance

public static <T extends GObject> T newInstance(Type objectType,
 Object... propertyNamesAndValues)

Creates a new GObject instance of the provided GType and with the provided property values.

Parameters:

objectType - the GType of the new GObject

propertyNamesAndValues - pairs of property names and values (Strings and Objects)

Returns:

the newly created GObject instance

Throws:

IllegalArgumentException - invalid property name

getProperty

public Object getProperty(String propertyName)

Get a property of an object.

Parameters:

propertyName - the name of the property to get

Returns:

the property value

Throws:

IllegalArgumentException - invalid property name

setProperty

public void setProperty(String propertyName,
 Object value)

Set a property of an object.

Parameters:

propertyName - the name of the property to set

value - the new property value

Throws:

IllegalArgumentException - invalid property name

bindProperty

public <S,
T> BindingBuilder<S,T> bindProperty(String sourceProperty,
 GObject target,
 String targetProperty)

Creates a binding between sourceProperty on this Object and targetProperty on target.

Whenever the sourceProperty is changed the targetProperty is updated using the same value. For instance:

  action.bindProperty ("active", widget, "sensitive").build();
 

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 BindingBuilder.bidirectional() is set then the binding will be mutual: if targetProperty on target changes then the sourceProperty on this Object will be updated as well.

The binding will automatically be removed when either the this Object or the target instances are finalized. To remove the binding without affecting the this Object and the target you can just call unref() on the returned Binding instance.

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

A GObject can have multiple bindings.

Parameters:

sourceProperty - the property on this Object to bind

target - the target GObject

targetProperty - the property on target to bind

flags - flags to pass to GBinding

Returns:

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

connect

public <T> SignalConnection connect(String detailedSignal,
 T callback)

Connect a callback to a signal for this object. The handler will be called before the default handler of the signal.

Parameters:

detailedSignal - a string of the form "signal-name::detail"

callback - the callback to connect

Returns:

a SignalConnection object to track, block and disconnect the signal connection

connect

public <T> SignalConnection connect(String detailedSignal,
 T callback,
 boolean after)

Connect a callback to a signal for this object.

Parameters:

detailedSignal - a string of the form "signal-name::detail"

callback - the callback to connect

after - whether the handler should be called before or after the default handler of the signal

Returns:

a SignalConnection object to track, block and disconnect the signal connection

emit

public Object emit(String detailedSignal,
 Object... params)

Emits a signal from this object.

Parameters:

detailedSignal - a string of the form "signal-name::detail"

params - the parameters to emit for this signal

Returns:

the return value of the signal, or null if the signal has no return value

Throws:

IllegalArgumentException - if a signal with this name is not found for the object