class: GObjectRef

[544:7] extends: object

GObjectRef is a low-level reusable wrapper for one GObject-derived handle. Generated wrappers can extend this to share explicit ref and unref behavior without tying native cleanup to GC.

Members

• handleObj

Methods

• GObjectRef (Handle)

  Wraps one GObject-derived native handle.

  • @p Handle is a NativeHandle or compatible pointer-shaped object.

• handle ()

  Returns the wrapped NativeHandle.

  • @r A NativeHandle object.

• isNull ()

  Returns true when the wrapped handle is null.

  • @r A bool with true when the handle is null.

• ref ()

  Returns a retained wrapper for the same native object.

  • @r A GObjectRef object.

• unref ()

  Decrements the reference count on the wrapped native object.

  • @r null

• unrefIfOwned ()

  Decrements the reference count only when the wrapped handle is owned.

  • @r null

• clearOwnedHandle ()

  Clears the wrapped handle when it is explicitly owned.

  • @r A NativeHandle object pointing at null.

• typeName ()

  Returns the runtime GType name for the wrapped pointer. Useful when iterating a container whose element type is unknown at emit time, so callers can branch on the concrete wrapper class to downcast to.

  • @r The GType name string, or null when the wrapped handle is null.

• as (Class)

  Downcasts this reference to the provided generated wrapper class by calling its wrap constructor with the same native handle.

  • @p Class is the generated wrapper class to instantiate.
  • @r A new instance of Class that wraps the same native handle.

class: glib

[13:21] static (extern: com.lehman.aussom.stdlib.AussomGLib) extends: object

The glib static class provides GLib-specific helpers built on top of the generic panama FFM layer. Use it for GError** allocation and translation, explicit GObject lifetime calls, and low-level GObject signal or property helpers that should not live in the generic panama API.

Methods

• gerror (object ArenaObj)

  Allocates a GError** out slot in the provided arena. Pass the returned object directly to native functions that expect a GError** parameter.

  • @p ArenaObj is a NativeArena object that owns the out slot allocation.
  • @r A NativeGErrorOut object.

• ref (object HandleObj, string TypeName = "GObject*")

  Increments the reference count on a GObject-derived handle and returns a handle to the same native object.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @p TypeName is an optional display name for the returned handle.
  • @r A NativeHandle object for the retained native object.

• unref (object HandleObj)

  Decrements the reference count on a GObject-derived handle.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @r null

• unrefOwned (object HandleObj)

  Decrements the reference count on an owned GObject-derived handle. This fails when the provided handle is not marked as owned.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @r null

• unrefIfOwned (object HandleObj)

  Decrements the reference count only when the handle is explicitly marked as owned. Borrowed and unknown handles are left untouched.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @r null

• clearOwnedHandle (object HandleObj)

  Clears an owned GObject-derived handle and returns a null handle of the same display type. Borrowed or unknown handles fail clearly.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @r A NativeHandle object pointing at null.

• throwIfGError (object GErrorOutObj, string Prefix = null)

  Throws an Aussom exception when the provided GError** slot contains an error object. On translation, the native GError is freed and the slot is reset to null.

  • @p GErrorOutObj is a NativeGErrorOut object.
  • @p Prefix is an optional call-site description to prepend to the message.
  • @r null when no error is present.

• signalConnect (object HandleObj, string SignalName, object CallbackHandleObj, UserData = null, int ConnectFlags = 0)

  Connects a native signal handler to a GObject-derived instance. The callback handle should usually come from a NativeCallback wrapper.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @p SignalName is the detailed signal name such as notify::title.
  • @p CallbackHandleObj is a NativeCallback, NativeHandle, or compatible pointer-shaped object.
  • @p UserData is an optional pointer-shaped user-data value.
  • @p ConnectFlags is an optional int with GConnectFlags bits.
  • @r An int with the native handler id.

• signalDisconnect (object HandleObj, int HandlerId)

  Disconnects one native signal handler from a GObject-derived instance.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @p HandlerId is the native handler id returned by signalConnect.
  • @r null

• getProperty (object HandleObj, string PropertyName, string TypeName = "pointer", string WrapTypeName = "GObject*")

  Reads one property from a GObject-derived instance using a low-level type token. Supported type tokens are intentionally narrow in v1: string, bool, int, double, object, and pointer.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @p PropertyName is the canonical property name.
  • @p TypeName is the low-level property conversion token.
  • @p WrapTypeName is the display type name used when returning object-like handles.
  • @r A converted scalar, string, NativeHandle, or null.

• setProperty (object HandleObj, string PropertyName, Value, string TypeName = "pointer")

  Writes one property on a GObject-derived instance using a low-level type token. Supported type tokens are intentionally narrow in v1: string, bool, int, double, object, and pointer.

  • @p HandleObj is a NativeHandle or compatible pointer-shaped object.
  • @p PropertyName is the canonical property name.
  • @p Value is the value to store.
  • @p TypeName is the low-level property conversion token.
  • @r null

• bindProperty (object SourceObj, string SourceProperty, object TargetObj, string TargetProperty, int Flags = 0)

  Creates a low-level GObject property binding.

  • @p SourceObj is the source NativeHandle or compatible pointer-shaped object.
  • @p SourceProperty is the readable source property name.
  • @p TargetObj is the target NativeHandle or compatible pointer-shaped object.
  • @p TargetProperty is the writable target property name.
  • @p Flags is an optional int with GBindingFlags bits.
  • @r A NativeHandle wrapping the returned GBinding*, or null on failure.

• iterate (bool MayBlock = false)

  Iterates the default GLib main context once. Returns true when a source dispatched during the iteration.

  • @p MayBlock is true to block until work is available.
  • @r A bool indicating whether a source ran.

• pending ()

  Returns true when the default GLib main context has sources ready to dispatch.

  • @r A bool.

• typeName (object HandleObj)

  Returns the GType name of a GObject instance. Wraps g_type_name_from_instance.

  • @p HandleObj is a NativeHandle or wrapper with handle().
  • @r A string with the GType name, or null when the instance is untyped.

• timeoutAdd (int IntervalMs, object CallbackObj, int Priority = null)

  Adds a main-loop timeout source.

  • @p IntervalMs is how often the callback fires, in milliseconds.
  • @p CallbackObj is a NativeCallback whose C signature is int(void*) returning 0 to remove.
  • @p Priority is optional; defaults to G_PRIORITY_DEFAULT (0).
  • @r An int source id; pass to sourceRemove to cancel.

• idleAdd (object CallbackObj, int Priority = null)

  Adds a main-loop idle source.

  • @p CallbackObj is a NativeCallback whose C signature is int(void*) returning 0 to remove.
  • @p Priority is optional; defaults to G_PRIORITY_DEFAULT_IDLE (200).
  • @r An int source id; pass to sourceRemove to cancel.

• sourceRemove (int SourceId)

  Cancels a main-loop source by id.

  • @p SourceId is the id returned by timeoutAdd or idleAdd.
  • @r A bool with true when the source existed and was removed.

• retainedSourceCount ()

  Returns the number of currently-retained main-loop source callbacks. Used by tests to verify sources are being released.

  • @r An int count.

• valueNew (string Token)

  Creates a standalone GValue for the provided property type token. Pass the returned NativeGValue directly where a GValue pointer is expected, or use .set() / .get() to read and write values through the same token system as getProperty.

  • @p Token is a GLib property type token (string, bool, int, int64, uint, uint64, double, float, char, uchar, long, ulong, object, pointer, enum, flags, gtype, strv).
  • @r A NativeGValue object.

• variantNewBool (bool Value)

  Creates a GVariant holding a bool. The returned handle is marked owned; call variantUnref to release it.

• variantNewInt32 (int Value)

  Creates a GVariant holding an int32.

• variantNewInt64 (int Value)

  Creates a GVariant holding an int64.

• variantNewUint32 (int Value)

  Creates a GVariant holding a uint32 (non-negative, <= 2^32-1).

• variantNewUint64 (int Value)

  Creates a GVariant holding a uint64.

• variantNewDouble (Value)

  Creates a GVariant holding a double.

• variantNewString (string Value)

  Creates a GVariant holding a UTF-8 string.

• variantNewTuple (list Children)

  Creates a GVariant tuple from a list of GVariant children.

• variantNewStringArray (list Values)

  Creates a GVariant holding an array of strings (GVariant "as").

• variantParse (TypeString, string Text)

  Parses a GVariant from its textual form, optionally typed.

  • @p TypeString is a GVariant type string (for example "(si)") or null.
  • @p Text is the textual GVariant value, for example "('hi', 5)".

• variantGetType (object VariantObj)

  Returns the GVariant type string (for example "i", "s", "(si)").

• variantGetBool (object VariantObj)

  Reads the value of a boolean GVariant.

• variantGetInt32 (object VariantObj)

  Reads the value of an int32 GVariant.

• variantGetInt64 (object VariantObj)

  Reads the value of an int64 GVariant.

• variantGetUint32 (object VariantObj)

  Reads the value of a uint32 GVariant as a non-negative int.

• variantGetUint64 (object VariantObj)

  Reads the value of a uint64 GVariant.

• variantGetDouble (object VariantObj)

  Reads the value of a double GVariant.

• variantGetString (object VariantObj)

  Reads the value of a string GVariant.

• variantNChildren (object VariantObj)

  Returns the number of children in a tuple or array GVariant.

• variantGetChildValue (object VariantObj, int Index)

  Returns the child GVariant at Index. The returned handle is owned; unref when done.

• variantRef (object VariantObj)

  Increments the reference count on a GVariant.

• variantUnref (object VariantObj)

  Decrements the reference count on a GVariant.

• signalEmitv (object InstanceObj, string SignalName, list ArgValues, ReturnToken = null)

  Emits a signal on a GObject instance using explicit NativeGValue arguments. The signal name may include a "::" detail suffix. This is the non-variadic form; use signalEmitByName for a more ergonomic surface that accepts token/value pairs.

  • @p InstanceObj is a NativeHandle for the GObject instance.
  • @p SignalName is the signal name, optionally "name::detail".
  • @p ArgValues is a list of NativeGValue objects (signal args).
  • @p ReturnToken is an optional token for the signal's return type.
  • @r The decoded return value or null for VOID-return signals.

• signalEmitByName (object InstanceObj, string SignalName, list ArgPairs, ReturnToken = null)

  Emits a signal on a GObject instance with Aussom-native args. Each entry in ArgPairs is a two-element [token, value] list parallel to the signal's declared argument types.

  • @p InstanceObj is a NativeHandle for the GObject instance.
  • @p SignalName is the signal name, optionally "name::detail".
  • @p ArgPairs is a list of [token, value] pairs.
  • @p ReturnToken is an optional token for the signal's return type.
  • @r The decoded return value or null for VOID-return signals.

• objectNewWithProperties (string TypeName, Properties = null)

  Constructs a new GObject of the given type with optional initial property values. Uses g_object_new_with_properties (non-variadic) so no Panama variadic support is required.

  • @p TypeName is the GLib type name such as "GtkLabel".
  • @p Properties is an optional map of property-name -> [token, value].
  • @r An owned NativeHandle for the new GObject.

• filePath (object FileObj)

  Returns the filesystem path of a GFile, or null when the GFile has no path (for example remote URIs). Uses g_file_peek_path so no free is required.

  • @p FileObj is a NativeHandle for a GFile.
  • @r A string path or null.

• fileOwnedPath (object FileObj)

  Returns the filesystem path of a GFile as a freshly-allocated string that is freed on the native side after decoding.

  • @p FileObj is a NativeHandle for a GFile.
  • @r A string path or null.

• fileNewForPath (string Path)

  Creates a new GFile for the provided local path.

  • @p Path is a filesystem path string.
  • @r An owned NativeHandle (GFile*).

• free (HandleObj)

  Frees memory returned by a GLib function that expects the caller to call g_free on its result. Accepts null as a no-op.

  • @p HandleObj is a NativeHandle, NativeBuffer, or null.
  • @r null

• cancellableNew ()

  Creates a new GCancellable. Release with glib.unref.

  • @r An owned NativeHandle (GCancellable*).

• cancellableCancel (object CancellableObj)

  Requests cancellation of any operation bound to the given GCancellable. Subsequent calls to isCancelled return true.

  • @p CancellableObj is a NativeHandle for a GCancellable.
  • @r null

• cancellableIsCancelled (object CancellableObj)

  Returns true when the GCancellable has been cancelled.

  • @p CancellableObj is a NativeHandle for a GCancellable.
  • @r A bool.

• hashTableSize (object TableObj)

  Returns the number of entries in a GHashTable.

  • @p TableObj is a NativeHandle for a GHashTable.
  • @r An int count.

• hashTableLookup (object TableObj, KeyObj, string ValueTypeName = "pointer")

  Looks up one value in a GHashTable. Returns a null handle when the key is not present.

  • @p TableObj is a NativeHandle for a GHashTable.
  • @p KeyObj is the lookup key as a NativeHandle or null.
  • @p ValueTypeName is an optional display name for the value.
  • @r A NativeHandle for the value.

• hashTableKeys (object TableObj, string KeyTypeName = "pointer")

  Returns the keys of a GHashTable as a list of NativeHandles.

  • @p TableObj is a NativeHandle for a GHashTable.
  • @p KeyTypeName is an optional display name for the keys.
  • @r A list of NativeHandle objects.

• hashTableUnref (object TableObj)

  Releases one reference on a GHashTable.

  • @p TableObj is a NativeHandle for a GHashTable.
  • @r null

• ptrArrayLength (object ArrayObj)

  Returns the number of elements in a GPtrArray.

  • @p ArrayObj is a NativeHandle for a GPtrArray.
  • @r An int length.

• ptrArrayIndex (object ArrayObj, int Index, string ElementTypeName = "pointer")

  Returns the element at Index in a GPtrArray as a NativeHandle.

  • @p ArrayObj is a NativeHandle for a GPtrArray.
  • @p Index is the zero-based index.
  • @p ElementTypeName is an optional display name for the element.
  • @r A NativeHandle for the element.

• ptrArrayUnref (object ArrayObj)

  Releases one reference on a GPtrArray.

  • @p ArrayObj is a NativeHandle for a GPtrArray.
  • @r null

• themedIconNew (string IconName)

  Creates a new GThemedIcon for a named icon. Release with glib.unref.

  • @p IconName is a string name such as "document-save".
  • @r An owned NativeHandle (GThemedIcon*).

• fileIconNew (object FileObj)

  Creates a new GFileIcon for the provided GFile. Release with glib.unref.

  • @p FileObj is a NativeHandle for a GFile.
  • @r An owned NativeHandle (GFileIcon*).

• errorDomainName (int Domain)

  Resolves a GLib error-domain quark to its registered name. Use after throwIfGError or readGError to branch on a readable name rather than a numeric quark id.

  • @p Domain is the numeric quark returned by throwIfGError.
  • @r A string name or null when the quark is unknown.

• bytesToBuffer (object BytesObj)

  Copies the contents of a GBytes* object into an Aussom Buffer.

  • @p BytesObj is a NativeHandle or compatible pointer-shaped object.
  • @r A Buffer object.

• bytesUnref (object BytesObj)

  Releases one GBytes* object.

  • @p BytesObj is a NativeHandle or compatible pointer-shaped object.
  • @r null

• listLength (object ListObj)

  Returns the number of nodes in one GList*.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @r An int with the node count.

• listNth (object ListObj, int Index, string TypeName = "pointer")

  Returns the data pointer stored at the provided GList* index.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @p Index is the zero-based index.
  • @p TypeName is an optional display type name for the returned handle.
  • @r A NativeHandle object.

• listFree (object ListObj)

  Frees the node structure of one GList*. The list item data is not destroyed.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @r null

• slistLength (object ListObj)

  Returns the number of nodes in one GSList*.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @r An int with the node count.

• slistNth (object ListObj, int Index, string TypeName = "pointer")

  Returns the data pointer stored at the provided GSList* index.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @p Index is the zero-based index.
  • @p TypeName is an optional display type name for the returned handle.
  • @r A NativeHandle object.

• slistFree (object ListObj)

  Frees the node structure of one GSList*. The list item data is not destroyed.

  • @p ListObj is a NativeHandle or compatible pointer-shaped object.
  • @r null