@gtkx/runtime 1.2.2 → 1.3.0

package/src/registry.ts

@@ -1,14 +1,25 @@
 import {
     type ExternalObject,
+    getFundamentalWrapper,
     getType,
+    getTypeClass,
     getWrapper,
     type Handle,
     type RegisterClassVfunc as NativeRegisterClassVfunc,
+    setFundamentalWrapper,
     setWrapper,
 } from "@gtkx/native";
 import { type AnyClass, walkClassChain } from "@gtkx/utils";
-import type { Mixin, MixinReceiver } from "./mixin.js";
-import { TYPE_INVALID, type TypedClass, typeInterfaces, typeIsA, typeName, typeParent } from "./type.js";
+import { copyLayerMembers, type Mixin, type MixinReceiver } from "./mixin.js";
+import {
+    TYPE_INVALID,
+    TYPE_OBJECT,
+    type TypedClass,
+    typeInterfaces,
+    typeIsA,
+    typeName,
+    typeParent,
+} from "./type.js";
 
 /**
  * Static side of class `C` with its construct signature preserved but the members named `K`
@@ -58,6 +69,11 @@ type VfuncDescriptor = {
  */
 type VfuncRegistry = Record<string, VfuncDescriptor>;
 type WrapperBinding = (handle: ExternalObject<Handle>, instance: object) => void;
+/**
+ * Picks the wrapper class for one handle of a registered type, such as a subclass keyed on a tag the
+ * handle carries.
+ */
+type WrapperClassResolver = (handle: ExternalObject<Handle>) => AnyClass;
 
 /**
  * How one property an interface declares reaches the vtable, given as the interface's own accessor
@@ -88,6 +104,8 @@ type InterfaceLayout = {
 };
 
 const classRegistry: Map<bigint, AnyClass> = new Map();
+const classStructRegistry: Map<bigint, AnyClass> = new Map();
+const composedClassStructRegistry: Map<bigint, AnyClass> = new Map();
 const interfaceMixinRegistry: Map<bigint, Mixin> = new Map();
 const composedClassRegistry: Map<bigint, AnyClass> = new Map();
 const handleMap: WeakMap<object, ExternalObject<Handle>> = new WeakMap();
@@ -95,6 +113,8 @@ const vfuncRegistry: WeakMap<object, VfuncRegistry> = new WeakMap();
 const interfaceLayoutRegistry: Map<bigint, InterfaceLayout> = new Map();
 const wrapperClasses: WeakSet<AnyClass> = new WeakSet();
 const derivedClasses: WeakSet<AnyClass> = new WeakSet();
+const typeClassHandles: Map<bigint, ExternalObject<Handle>> = new Map();
+const wrapperClassResolvers: WeakMap<AnyClass, WrapperClassResolver> = new WeakMap();
 
 function setClassType(cls: AnyClass, type: bigint): void {
     (cls.prototype as { [K in keyof TypedClass]: TypedClass[K] }).__type__ = type;
@@ -127,6 +147,16 @@ function getInstanceType(instance: object): bigint {
     return handle === undefined ? TYPE_INVALID : getType(handle);
 }
 
+function coerceGType(value: unknown): unknown {
+    if (typeof value !== "function") {
+        return value;
+    }
+
+    const type = getClassType(value as AnyClass);
+
+    return type === TYPE_INVALID ? value : type;
+}
+
 function registerClassType(cls: AnyClass, type: bigint): void {
     if (type === TYPE_INVALID) {
         return;
@@ -156,10 +186,154 @@ function registerWrapperClass(cls: AnyClass, type: bigint, vfuncs?: VfuncRegistr
     }
 }
 
+/**
+ * Lets a class registered with `registerWrapperClass` pick a subclass for each handle it wraps, for
+ * types whose one GType covers several C-level subtypes, the way a cairo surface reports image or
+ * recording through `cairo_surface_get_type`. The resolver runs when a handle is wrapped as that class
+ * explicitly, the way a boxed value a binding hands back is; a wrapper resolved from a handle's runtime
+ * GType never consults it, and a subclass passed to `wrapHandle` directly is used as given.
+ * @param cls Registered wrapper class whose handles the resolver classifies.
+ * @param resolver Returns the class to instantiate for one handle, `cls` itself included.
+ * @throws If `cls` is not a registered wrapper class.
+ */
+function registerWrapperClassResolver(cls: AnyClass, resolver: WrapperClassResolver): void {
+    if (!wrapperClasses.has(cls)) {
+        throw new Error(
+            `Cannot register a wrapper class resolver for ${cls.name}: ` +
+            "register the class with registerWrapperClass first",
+        );
+    }
+
+    wrapperClassResolvers.set(cls, resolver);
+}
+
 function markDerivedClass(cls: AnyClass): void {
     derivedClasses.add(cls);
 }
 
+/**
+ * Registers the wrapper class of a type's class struct, such as `Gtk.WidgetClass` for `Gtk.Widget`,
+ * so `registerClass` can hand a `classInit` hook the new type's class struct wrapped in it.
+ * @param cls Wrapper class of the type's instances, already registered through
+ * `registerWrapperClass`.
+ * @param structClass Wrapper class of the type's class struct.
+ */
+function registerClassStruct(cls: AnyClass, structClass: AnyClass): void {
+    const type = getClassType(cls);
+
+    if (type !== TYPE_INVALID) {
+        classStructRegistry.set(type, structClass);
+    }
+}
+
+function collectClassStructClasses(type: bigint): AnyClass[] {
+    const structs: AnyClass[] = [];
+    let current = type;
+
+    while (current !== TYPE_INVALID) {
+        const structClass = classStructRegistry.get(current);
+
+        if (structClass !== undefined) {
+            structs.push(structClass);
+        }
+
+        current = typeParent(current);
+    }
+
+    return structs;
+}
+
+function composeClassStructClass(structs: AnyClass[]): AnyClass | undefined {
+    const [nearest, ...ancestors] = structs;
+
+    if (nearest === undefined || ancestors.length === 0) {
+        return nearest;
+    }
+
+    const composed: AnyClass = class extends nearest {};
+    Object.defineProperty(composed, "name", { value: nearest.name });
+
+    for (const structClass of ancestors) {
+        copyLayerMembers(composed, structClass.prototype);
+    }
+
+    return composed;
+}
+
+function getClassStructClass(type: bigint): AnyClass | undefined {
+    const cached = composedClassStructRegistry.get(type);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const composed = composeClassStructClass(collectClassStructClasses(type));
+
+    if (composed !== undefined) {
+        composedClassStructRegistry.set(type, composed);
+    }
+
+    return composed;
+}
+
+function peekedTypeLabel(type: bigint | AnyClass, gtype: bigint): string {
+    const name = typeName(gtype);
+
+    if (name !== null) {
+        return name;
+    }
+
+    return typeof type === "bigint" ? String(type) : type.name;
+}
+
+function getTypeClassHandle(gtype: bigint): ExternalObject<Handle> {
+    const cached = typeClassHandles.get(gtype);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const handle = getTypeClass(gtype);
+    typeClassHandles.set(gtype, handle);
+
+    return handle;
+}
+
+/**
+ * Returns a GObject type's class struct, wrapped in the class-struct wrapper classes registered
+ * for the type's ancestry, such as `Gtk.WidgetClass` composed with `GObject.ObjectClass` for a
+ * widget type. The class is referenced so it exists even before the type's first instance, and
+ * the reference is deliberately never released: once created, a class struct lives for the rest
+ * of the process. Backs the `peek` statics of generated GTypeStruct wrappers, such as
+ * `GObject.ObjectClass.peek` and `Gtk.WidgetClass.peek`.
+ *
+ * @param type GType to peek the class struct of, or a registered wrapper class of the type.
+ * @param base When given, wrapper class of the type the peeked type must derive from; the peek
+ * throws for a type outside that lineage. Without it any GObject type is accepted.
+ * @returns The wrapped class struct.
+ */
+function peekTypeClass(type: bigint | AnyClass, base?: AnyClass): object {
+    const gtype = typeof type === "bigint" ? type : getClassType(type);
+
+    if (!typeIsA(gtype, TYPE_OBJECT)) {
+        throw new TypeError(`peekTypeClass: '${peekedTypeLabel(type, gtype)}' is not a GObject type`);
+    }
+
+    if (base !== undefined && !typeIsA(gtype, getClassType(base))) {
+        throw new TypeError(`peekTypeClass: '${peekedTypeLabel(type, gtype)}' does not derive from '${base.name}'`);
+    }
+
+    const structClass = getClassStructClass(gtype);
+
+    if (structClass === undefined) {
+        throw new TypeError(
+            `peekTypeClass: no ancestor of '${peekedTypeLabel(type, gtype)}' registers a class struct wrapper`,
+        );
+    }
+
+    return wrapHandle(getTypeClassHandle(gtype), structClass);
+}
+
 function resolveAncestorType(ancestor: AnyClass): bigint | undefined {
     if (derivedClasses.has(ancestor) || !wrapperClasses.has(ancestor)) {
         return undefined;
@@ -204,8 +378,9 @@ function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, layout?: I
  * Wraps a native handle in a JS wrapper instance. With no class, resolves and
  * reuses the wrapper for the handle's runtime GType (composing interface mixins),
  * and hands back an instance that already carries a handle unchanged; with an
- * explicit class, creates a bare instance backed by the handle. Returns null for
- * a null or undefined handle.
+ * explicit class, creates a bare instance backed by the handle, of the subclass the
+ * class's `registerWrapperClassResolver` resolver picks when it has one. Returns null
+ * for a null or undefined handle.
  * @param handle Native handle to wrap.
  * @param cls Wrapper class to instantiate, or omitted to resolve it from the runtime type.
  */
@@ -229,8 +404,27 @@ function wrapHandle(handle: ExternalObject<Handle> | null | undefined, cls?: Any
         return getOrCreateWrapper(handle);
     }
 
+    const resolver = wrapperClassResolvers.get(cls);
+    const instance: object = Object.create((resolver === undefined ? cls : resolver(handle)).prototype) as object;
+    setHandle(instance, handle);
+
+    return instance;
+}
+
+function wrapFundamentalHandle(handle: ExternalObject<Handle> | null | undefined, cls: AnyClass): object | null {
+    if (handle === null || handle === undefined) {
+        return null;
+    }
+
+    const existing = getFundamentalWrapper(handle);
+
+    if (existing) {
+        return existing;
+    }
+
     const instance: object = Object.create(cls.prototype) as object;
     setHandle(instance, handle);
+    setFundamentalWrapper(handle, instance);
 
     return instance;
 }
@@ -378,6 +572,18 @@ function instanceClassName(instance: object): string {
     return (instance as { constructor?: { name?: string } }).constructor?.name ?? "object";
 }
 
+function describeValueKind(value: unknown): string {
+    if (value === null) {
+        return "null";
+    }
+
+    if (typeof value !== "object") {
+        return typeof value;
+    }
+
+    return instanceClassName(value);
+}
+
 /** Returns the native handle bound to a wrapper instance, throwing if none is set. */
 function getHandle(instance: object): ExternalObject<Handle> {
     const handle = handleMap.get(instance);
@@ -420,12 +626,20 @@ function getInterfaceProperties(type: bigint): Record<string, InterfaceProperty>
 }
 
 export {
+    coerceGType,
+    describeValueKind,
+    getClassStructClass,
     getClassType,
     getInstanceType,
+    getTypeClassHandle,
     markDerivedClass,
+    peekTypeClass,
+    registerClassStruct,
     registerClassType,
     registerWrapperClass,
+    registerWrapperClassResolver,
     registerInterface,
+    wrapFundamentalHandle,
     wrapHandle,
     getWrapperClass,
     resolveWrapperClass,
@@ -443,4 +657,5 @@ export {
     type InterfaceProperty,
     type StaticBase,
     type VfuncDescriptor,
+    type WrapperClassResolver,
 };

package/src/signal.ts

@@ -3,10 +3,12 @@ import type { TypedClass } from "./type.js";
 import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg } from "./arg.js";
 import { bind, createBindCache } from "./bind.js";
 import { wrapCallback } from "./callback.js";
+import { toClosure } from "./closure.js";
 import {
     arrayT,
     biguint64T,
     booleanT,
+    boxedT,
     type CallbackDescriptor,
     objectT,
     stringT,
@@ -21,7 +23,9 @@ import {
     fromValue,
     getBoxedValue,
     inoutValueForBoxedDescriptor,
+    intoValue,
     newValueForDescriptor,
+    newValueForType,
     outValueForBoxedDescriptor,
     outValueForDescriptor,
     toValue,
@@ -30,6 +34,11 @@ import {
 /** Function invoked when a connected GObject signal is emitted. */
 type SignalHandler = (...args: unknown[]) => unknown;
 
+type DeclaredSignalTypes = {
+    paramTypes: bigint[];
+    returnType?: bigint;
+};
+
 /** The marshalling and handler that make up a single signal connection. */
 type SignalConnectSpec = {
     /**
@@ -77,6 +86,21 @@ const gSignalHandlerIsConnected = bind(
 );
 
 const gSignalHandlerDisconnect = bind(LIB, "g_signal_handler_disconnect", [objectT("borrowed"), uint64T], voidT);
+const CLOSURE_T = boxedT("GClosure", { sharedLibrary: LIB, getTypeFnName: "g_closure_get_type" });
+
+const gSignalConnectClosure = bind(
+    LIB,
+    "g_signal_connect_closure",
+    [objectT("borrowed"), stringT("borrowed"), CLOSURE_T, booleanT],
+    uint64T,
+);
+
+const gSignalOverrideClassClosure = bind(
+    LIB,
+    "g_signal_override_class_closure",
+    [uint32T, biguint64T, CLOSURE_T],
+    voidT,
+);
 
 /** Returns the signal name without its detail suffix (the part after `::`). */
 const getSignalBaseName = (signal: string): string => {
@@ -208,6 +232,55 @@ function connectSignal(instance: object, signal: string, spec: SignalConnectSpec
     return handlerId;
 }
 
+function overrideSignalClassClosure(type: bigint, signal: string, handler: SignalHandler): void {
+    const signalId = gSignalLookup(signal, type) as number;
+
+    if (signalId === 0) {
+        return;
+    }
+
+    gSignalOverrideClassClosure(signalId, type, toClosure(handler));
+}
+
+function connectClosureSignal(instance: object, signal: string, handler: SignalHandler, isAfter: boolean): number {
+    const closure = toClosure((...args: unknown[]) => Reflect.apply(handler, null, args.slice(1)));
+    const handlerId = gSignalConnectClosure(getHandle(instance), signal, closure, isAfter) as number;
+    trackConnection(instance, getSignalBaseName(signal), handlerId);
+
+    return handlerId;
+}
+
+function emitDeclaredSignal(instance: object, signal: string, types: DeclaredSignalTypes, args: unknown[]): unknown {
+    const { paramTypes, returnType } = types;
+
+    if (args.length !== paramTypes.length) {
+        throw new TypeError(
+            `emit: signal '${signal}' takes ${String(paramTypes.length)} arguments, got ${String(args.length)}`,
+        );
+    }
+
+    const signalId = getSignalId(instance, signal);
+    const detail = getSignalDetailQuark(signal);
+    const values = [toValue(objectT("full"), instance)];
+
+    for (const [index, paramType] of paramTypes.entries()) {
+        const value = newValueForType(paramType);
+        intoValue(value, args[index]);
+        values.push(value);
+    }
+
+    if (returnType === undefined) {
+        gSignalEmitv(values, signalId, detail, undefined);
+
+        return undefined;
+    }
+
+    const returnValue = newValueForType(returnType);
+    gSignalEmitv(values, signalId, detail, returnValue);
+
+    return fromValue(returnValue);
+}
+
 const createEmitValue = (arg: EmitArg): { value: ExternalObject<Handle>; read?: () => unknown } => {
     if (!isOutputArg(arg)) {
         return { value: toValue(arg.type, arg.value) };
@@ -270,11 +343,15 @@ function emitSignal(instance: object, signal: string, args: EmitArg[], returns?:
 
 export {
     getSignalBaseName,
+    connectClosureSignal,
     connectSignal,
+    type DeclaredSignalTypes,
     disconnectSignal,
+    emitDeclaredSignal,
     emitSignal,
     hasSignalListener,
     isSignalHandlerConnected,
+    overrideSignalClassClosure,
     untrackConnection,
     type SignalHandler,
 };

package/src/type.ts

@@ -203,11 +203,17 @@ const resolveFundamentalType = (descriptor: FundamentalDescriptor): bigint => {
     throw new Error("Cannot resolve gtype for fundamental type without a typeName");
 };
 
+const getByteArrayType = (): bigint => resolveType(LIB, "g_byte_array_get_type");
+
 function resolveArrayType(descriptor: ArrayDescriptor): bigint {
     if (descriptor.itemDescriptor.kind === "string" && descriptor.arrayKind === "array") {
         return getStrvType();
     }
 
+    if (descriptor.arrayKind === "gbytearray") {
+        return getByteArrayType();
+    }
+
     throw new Error(`Unsupported array type ${descriptor.arrayKind} of ${descriptor.itemDescriptor.kind}`);
 }
 
@@ -272,6 +278,7 @@ export {
     TYPE_GTYPE,
     TYPE_VARIANT,
     TYPE_UNICHAR,
+    getByteArrayType,
     getErrorType,
     getStrvType,
     isResolvableDescriptor,