@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gdk/content-formats.d.ts

@@ -1,26 +1,170 @@
 import { Ref } from "@gtkx/native";
 import * as GLib from "../glib/index.js";
+/**
+ * Used to advertise and negotiate the format of content.
+ *
+ * You will encounter `GdkContentFormats` when interacting with objects
+ * controlling operations that pass data between different widgets, window
+ * or application, like [class@Gdk.Drag], [class@Gdk.Drop],
+ * [class@Gdk.Clipboard] or [class@Gdk.ContentProvider].
+ *
+ * GDK supports content in 2 forms: `GType` and mime type.
+ * Using `GTypes` is meant only for in-process content transfers. Mime types
+ * are meant to be used for data passing both in-process and out-of-process.
+ * The details of how data is passed is described in the documentation of
+ * the actual implementations. To transform between the two forms,
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used.
+ *
+ * A `GdkContentFormats` describes a set of possible formats content can be
+ * exchanged in. It is assumed that this set is ordered. `GTypes` are more
+ * important than mime types. Order between different `GTypes` or mime types
+ * is the order they were added in, most important first. Functions that
+ * care about order, such as [method@Gdk.ContentFormats.union], will describe
+ * in their documentation how they interpret that order, though in general the
+ * order of the first argument is considered the primary order of the result,
+ * followed by the order of further arguments.
+ *
+ * For debugging purposes, the function [method@Gdk.ContentFormats.to_string]
+ * exists. It will print a comma-separated list of formats from most important
+ * to least important.
+ *
+ * `GdkContentFormats` is an immutable struct. After creation, you cannot change
+ * the types it represents. Instead, new `GdkContentFormats` have to be created.
+ * The [struct@Gdk.ContentFormatsBuilder] structure is meant to help in this
+ * endeavor.
+ */
 export declare class ContentFormats {
     ptr: unknown;
+    /**
+     * Creates a new `GdkContentFormats` from an array of mime types.
+     *
+     * The mime types must be valid and different from each other or the
+     * behavior of the return value is undefined. If you cannot guarantee
+     * this, use [struct@Gdk.ContentFormatsBuilder] instead.
+     * @param mimeTypes - Pointer to an
+     * @param nMimeTypes - number of entries in @mime_types.
+     */
     constructor(nMimeTypes: number, mimeTypes?: string[] | null);
+    /**
+     * Creates a new `GdkContentFormats` for a given `GType`.
+     * @param type - a `GType`
+     */
     static formatsNewForGtype(type: number): ContentFormats;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Parses the given `string` into `GdkContentFormats` and
+     * returns the formats.
+     *
+     * Strings printed via [method@Gdk.ContentFormats.to_string]
+     * can be read in again successfully using this function.
+     *
+     * If `string` does not describe valid content formats, %NULL
+     * is returned.
+     * @param string - the string to parse
+     */
     static parse(string: string): ContentFormats;
+    /**
+     * Checks if a given `GType` is part of the given @formats.
+     * @param type - the `GType` to search for
+     */
     containGtype(type: number): boolean;
+    /**
+     * Checks if a given mime type is part of the given @formats.
+     * @param mimeType - the mime type to search for
+     */
     containMimeType(mimeType: string): boolean;
+    /**
+     * Gets the `GType`s included in @formats.
+     *
+     * Note that `formats` may not contain any `GType`s, in particular when
+     * they are empty. In that case %NULL will be returned.
+     * @param nGtypes - optional pointer to take the
+     */
     getGtypes(nGtypes?: Ref<number> | null): number[] | null;
+    /**
+     * Gets the mime types included in @formats.
+     *
+     * Note that `formats` may not contain any mime types, in particular
+     * when they are empty. In that case %NULL will be returned.
+     * @param nMimeTypes - optional pointer to take the
+     */
     getMimeTypes(nMimeTypes?: Ref<number> | null): string[] | null;
+    /**
+     * Returns whether the content formats contain any formats.
+     */
     isEmpty(): boolean;
+    /**
+     * Checks if `first` and `second` have any matching formats.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     match(second: ContentFormats): boolean;
+    /**
+     * Finds the first `GType` from `first` that is also contained
+     * in @second.
+     *
+     * If no matching `GType` is found, %G_TYPE_INVALID is returned.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     matchGtype(second: ContentFormats): number;
+    /**
+     * Finds the first mime type from `first` that is also contained
+     * in @second.
+     *
+     * If no matching mime type is found, %NULL is returned.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     matchMimeType(second: ContentFormats): string | null;
+    /**
+     * Prints the given `formats` into a string for human consumption.
+     *
+     * The result of this function can later be parsed with
+     * [func@Gdk.ContentFormats.parse].
+     * @param string - a `GString` to print into
+     */
     print(string: GLib.String): void;
+    /**
+     * Increases the reference count of a `GdkContentFormats` by one.
+     */
     ref(): ContentFormats;
+    /**
+     * Prints the given `formats` into a human-readable string.
+     *
+     * The resulting string can be parsed with [func@Gdk.ContentFormats.parse].
+     *
+     * This is a small wrapper around [method@Gdk.ContentFormats.print]
+     * to help when debugging.
+     */
     toString(): string;
+    /**
+     * Append all missing types from `second` to @first, in the order
+     * they had in @second.
+     * @param second - the `GdkContentFormats` to merge from
+     */
     union(second: ContentFormats): ContentFormats;
+    /**
+     * Add GTypes for mime types in `formats` for which deserializers are
+     * registered.
+     */
     unionDeserializeGtypes(): ContentFormats;
+    /**
+     * Add mime types for GTypes in `formats` for which deserializers are
+     * registered.
+     */
     unionDeserializeMimeTypes(): ContentFormats;
+    /**
+     * Add GTypes for the mime types in `formats` for which serializers are
+     * registered.
+     */
     unionSerializeGtypes(): ContentFormats;
+    /**
+     * Add mime types for GTypes in `formats` for which serializers are
+     * registered.
+     */
     unionSerializeMimeTypes(): ContentFormats;
+    /**
+     * Decreases the reference count of a `GdkContentFormats` by one.
+     *
+     * If the resulting reference count is zero, frees the formats.
+     */
     unref(): void;
 }

package/dist/generated/gdk/content-formats.js

@@ -1,11 +1,57 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * Used to advertise and negotiate the format of content.
+ *
+ * You will encounter `GdkContentFormats` when interacting with objects
+ * controlling operations that pass data between different widgets, window
+ * or application, like [class@Gdk.Drag], [class@Gdk.Drop],
+ * [class@Gdk.Clipboard] or [class@Gdk.ContentProvider].
+ *
+ * GDK supports content in 2 forms: `GType` and mime type.
+ * Using `GTypes` is meant only for in-process content transfers. Mime types
+ * are meant to be used for data passing both in-process and out-of-process.
+ * The details of how data is passed is described in the documentation of
+ * the actual implementations. To transform between the two forms,
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used.
+ *
+ * A `GdkContentFormats` describes a set of possible formats content can be
+ * exchanged in. It is assumed that this set is ordered. `GTypes` are more
+ * important than mime types. Order between different `GTypes` or mime types
+ * is the order they were added in, most important first. Functions that
+ * care about order, such as [method@Gdk.ContentFormats.union], will describe
+ * in their documentation how they interpret that order, though in general the
+ * order of the first argument is considered the primary order of the result,
+ * followed by the order of further arguments.
+ *
+ * For debugging purposes, the function [method@Gdk.ContentFormats.to_string]
+ * exists. It will print a comma-separated list of formats from most important
+ * to least important.
+ *
+ * `GdkContentFormats` is an immutable struct. After creation, you cannot change
+ * the types it represents. Instead, new `GdkContentFormats` have to be created.
+ * The [struct@Gdk.ContentFormatsBuilder] structure is meant to help in this
+ * endeavor.
+ */
 export class ContentFormats {
     ptr;
+    /**
+     * Creates a new `GdkContentFormats` from an array of mime types.
+     *
+     * The mime types must be valid and different from each other or the
+     * behavior of the return value is undefined. If you cannot guarantee
+     * this, use [struct@Gdk.ContentFormatsBuilder] instead.
+     * @param mimeTypes - Pointer to an
+     * @param nMimeTypes - number of entries in @mime_types.
+     */
     constructor(nMimeTypes, mimeTypes) {
         const _args = [mimeTypes, nMimeTypes];
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a new `GdkContentFormats` for a given `GType`.
+     * @param type - a `GType`
+     */
     static formatsNewForGtype(type) {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_new_for_gtype", [
             {
@@ -29,6 +75,17 @@ export class ContentFormats {
             },
         ], { type: "boxed", borrowed: true, innerType: "GdkContentFormats" });
     }
+    /**
+     * Parses the given `string` into `GdkContentFormats` and
+     * returns the formats.
+     *
+     * Strings printed via [method@Gdk.ContentFormats.to_string]
+     * can be read in again successfully using this function.
+     *
+     * If `string` does not describe valid content formats, %NULL
+     * is returned.
+     * @param string - the string to parse
+     */
     static parse(string) {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_parse", [
             {
@@ -43,6 +100,10 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Checks if a given `GType` is part of the given @formats.
+     * @param type - the `GType` to search for
+     */
     containGtype(type) {
         return call("libgtk-4.so.1", "gdk_content_formats_contain_gtype", [
             {
@@ -55,6 +116,10 @@ export class ContentFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if a given mime type is part of the given @formats.
+     * @param mimeType - the mime type to search for
+     */
     containMimeType(mimeType) {
         return call("libgtk-4.so.1", "gdk_content_formats_contain_mime_type", [
             {
@@ -67,6 +132,13 @@ export class ContentFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the `GType`s included in @formats.
+     *
+     * Note that `formats` may not contain any `GType`s, in particular when
+     * they are empty. In that case %NULL will be returned.
+     * @param nGtypes - optional pointer to take the
+     */
     getGtypes(nGtypes) {
         return call("libgtk-4.so.1", "gdk_content_formats_get_gtypes", [
             {
@@ -83,6 +155,13 @@ export class ContentFormats {
             },
         ], { type: "array", itemType: { type: "int", size: 64, unsigned: true } });
     }
+    /**
+     * Gets the mime types included in @formats.
+     *
+     * Note that `formats` may not contain any mime types, in particular
+     * when they are empty. In that case %NULL will be returned.
+     * @param nMimeTypes - optional pointer to take the
+     */
     getMimeTypes(nMimeTypes) {
         return call("libgtk-4.so.1", "gdk_content_formats_get_mime_types", [
             {
@@ -99,6 +178,9 @@ export class ContentFormats {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Returns whether the content formats contain any formats.
+     */
     isEmpty() {
         return call("libgtk-4.so.1", "gdk_content_formats_is_empty", [
             {
@@ -107,6 +189,10 @@ export class ContentFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if `first` and `second` have any matching formats.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     match(second) {
         return call("libgtk-4.so.1", "gdk_content_formats_match", [
             {
@@ -124,6 +210,13 @@ export class ContentFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Finds the first `GType` from `first` that is also contained
+     * in @second.
+     *
+     * If no matching `GType` is found, %G_TYPE_INVALID is returned.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     matchGtype(second) {
         return call("libgtk-4.so.1", "gdk_content_formats_match_gtype", [
             {
@@ -141,6 +234,13 @@ export class ContentFormats {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Finds the first mime type from `first` that is also contained
+     * in @second.
+     *
+     * If no matching mime type is found, %NULL is returned.
+     * @param second - the `GdkContentFormats` to intersect with
+     */
     matchMimeType(second) {
         return call("libgtk-4.so.1", "gdk_content_formats_match_mime_type", [
             {
@@ -158,6 +258,13 @@ export class ContentFormats {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Prints the given `formats` into a string for human consumption.
+     *
+     * The result of this function can later be parsed with
+     * [func@Gdk.ContentFormats.parse].
+     * @param string - a `GString` to print into
+     */
     print(string) {
         call("libgtk-4.so.1", "gdk_content_formats_print", [
             {
@@ -175,6 +282,9 @@ export class ContentFormats {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Increases the reference count of a `GdkContentFormats` by one.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_ref", [
             {
@@ -189,6 +299,14 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Prints the given `formats` into a human-readable string.
+     *
+     * The resulting string can be parsed with [func@Gdk.ContentFormats.parse].
+     *
+     * This is a small wrapper around [method@Gdk.ContentFormats.print]
+     * to help when debugging.
+     */
     toString() {
         return call("libgtk-4.so.1", "gdk_content_formats_to_string", [
             {
@@ -197,6 +315,11 @@ export class ContentFormats {
             },
         ], { type: "string" });
     }
+    /**
+     * Append all missing types from `second` to @first, in the order
+     * they had in @second.
+     * @param second - the `GdkContentFormats` to merge from
+     */
     union(second) {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_union", [
             {
@@ -220,6 +343,10 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Add GTypes for mime types in `formats` for which deserializers are
+     * registered.
+     */
     unionDeserializeGtypes() {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_union_deserialize_gtypes", [
             {
@@ -234,6 +361,10 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Add mime types for GTypes in `formats` for which deserializers are
+     * registered.
+     */
     unionDeserializeMimeTypes() {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_union_deserialize_mime_types", [
             {
@@ -248,6 +379,10 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Add GTypes for the mime types in `formats` for which serializers are
+     * registered.
+     */
     unionSerializeGtypes() {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_union_serialize_gtypes", [
             {
@@ -262,6 +397,10 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Add mime types for GTypes in `formats` for which serializers are
+     * registered.
+     */
     unionSerializeMimeTypes() {
         const ptr = call("libgtk-4.so.1", "gdk_content_formats_union_serialize_mime_types", [
             {
@@ -276,6 +415,11 @@ export class ContentFormats {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Decreases the reference count of a `GdkContentFormats` by one.
+     *
+     * If the resulting reference count is zero, frees the formats.
+     */
     unref() {
         call("libgtk-4.so.1", "gdk_content_formats_unref", [
             {

package/dist/generated/gdk/content-provider.d.ts

@@ -4,15 +4,74 @@ import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
 export declare class ContentProvider extends GObject.GObject {
+    /**
+     * Create a content provider that provides the given `bytes` as data for
+     * the given @mime_type.
+     * @param mimeType - the mime type
+     * @param bytes - a `GBytes` with the data for @mime_type
+     */
     constructor(mimeType: string, bytes: GLib.Bytes);
     constructor(...args: unknown[]);
+    /**
+     * Create a content provider that provides the given @value.
+     * @param value - a `GValue`
+     */
     static providerNewForValue(value: GObject.Value): ContentProvider;
+    /**
+     * Creates a content provider that represents all the given @providers.
+     *
+     * Whenever data needs to be written, the union provider will try the given
+     * `providers` in the given order and the first one supporting a format will
+     * be chosen to provide it.
+     *
+     * This allows an easy way to support providing data in different formats.
+     * For example, an image may be provided by its file and by the image
+     * contents with a call such as
+     * ```c
+     * gdk_content_provider_new_union ((GdkContentProvider *[2]) {
+     * gdk_content_provider_new_typed (G_TYPE_FILE, file),
+     * gdk_content_provider_new_typed (GDK_TYPE_TEXTURE, texture)
+     * }, 2);
+     * ```
+     * @param providers - The `GdkContentProvider`s to present the union of
+     * @param nProviders - the number of providers
+     */
     static providerNewUnion(nProviders: number, providers?: ContentProvider[] | null): ContentProvider;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Emits the ::content-changed signal.
+     */
     contentChanged(): void;
+    /**
+     * Gets the contents of `provider` stored in @value.
+     *
+     * The `value` will have been initialized to the `GType` the value should be
+     * provided in. This given `GType` does not need to be listed in the formats
+     * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
+     * given `GType` is not supported, this operation can fail and
+     * `G_IO_ERROR_NOT_SUPPORTED` will be reported.
+     * @param value - the `GValue` to fill
+     */
     getValue(value: Ref<GObject.Value>): boolean;
+    /**
+     * Gets the formats that the provider can provide its current contents in.
+     */
     refFormats(): ContentFormats;
+    /**
+     * Gets the formats that the provider suggests other applications to store
+     * the data in.
+     *
+     * An example of such an application would be a clipboard manager.
+     *
+     * This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].
+     */
     refStorableFormats(): ContentFormats;
+    /**
+     * Finishes an asynchronous write operation.
+     *
+     * See [method@Gdk.ContentProvider.write_mime_type_async].
+     * @param result - a `GAsyncResult`
+     */
     writeMimeTypeFinish(result: Gio.AsyncResult): boolean;
     connect(signal: "content-changed", handler: (self: ContentProvider) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: ContentProvider, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gdk/content-provider.js

@@ -2,6 +2,17 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { ContentFormats } from "./content-formats.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Provides content for the clipboard or for drag-and-drop operations
+ * in a number of formats.
+ *
+ * To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value]
+ * or [ctor@Gdk.ContentProvider.new_for_bytes].
+ *
+ * GDK knows how to handle common text and image formats out-of-the-box. See
+ * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want
+ * to add support for application-specific data formats.
+ */
 const SIGNAL_META = {
     "content-changed": { params: [], returnType: { type: "undefined" } },
 };
@@ -9,6 +20,10 @@ export class ContentProvider extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Create a content provider that provides the given @value.
+     * @param value - a `GValue`
+     */
     static providerNewForValue(value) {
         const ptr = call("libgtk-4.so.1", "gdk_content_provider_new_for_value", [
             {
@@ -23,6 +38,25 @@ export class ContentProvider extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, ContentProvider);
     }
+    /**
+     * Creates a content provider that represents all the given @providers.
+     *
+     * Whenever data needs to be written, the union provider will try the given
+     * `providers` in the given order and the first one supporting a format will
+     * be chosen to provide it.
+     *
+     * This allows an easy way to support providing data in different formats.
+     * For example, an image may be provided by its file and by the image
+     * contents with a call such as
+     * ```c
+     * gdk_content_provider_new_union ((GdkContentProvider *[2]) {
+     * gdk_content_provider_new_typed (G_TYPE_FILE, file),
+     * gdk_content_provider_new_typed (GDK_TYPE_TEXTURE, texture)
+     * }, 2);
+     * ```
+     * @param providers - The `GdkContentProvider`s to present the union of
+     * @param nProviders - the number of providers
+     */
     static providerNewUnion(nProviders, providers) {
         const ptr = call("libgtk-4.so.1", "gdk_content_provider_new_union", [
             {
@@ -55,6 +89,9 @@ export class ContentProvider extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Emits the ::content-changed signal.
+     */
     contentChanged() {
         call("libgtk-4.so.1", "gdk_content_provider_content_changed", [
             {
@@ -63,6 +100,16 @@ export class ContentProvider extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the contents of `provider` stored in @value.
+     *
+     * The `value` will have been initialized to the `GType` the value should be
+     * provided in. This given `GType` does not need to be listed in the formats
+     * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
+     * given `GType` is not supported, this operation can fail and
+     * `G_IO_ERROR_NOT_SUPPORTED` will be reported.
+     * @param value - the `GValue` to fill
+     */
     getValue(value) {
         const error = { value: null };
         const result = call("libgtk-4.so.1", "gdk_content_provider_get_value", [
@@ -98,6 +145,9 @@ export class ContentProvider extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Gets the formats that the provider can provide its current contents in.
+     */
     refFormats() {
         const ptr = call("libgtk-4.so.1", "gdk_content_provider_ref_formats", [
             {
@@ -112,6 +162,14 @@ export class ContentProvider extends GObject.GObject {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Gets the formats that the provider suggests other applications to store
+     * the data in.
+     *
+     * An example of such an application would be a clipboard manager.
+     *
+     * This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].
+     */
     refStorableFormats() {
         const ptr = call("libgtk-4.so.1", "gdk_content_provider_ref_storable_formats", [
             {
@@ -126,6 +184,12 @@ export class ContentProvider extends GObject.GObject {
         });
         return getObject(ptr, ContentFormats);
     }
+    /**
+     * Finishes an asynchronous write operation.
+     *
+     * See [method@Gdk.ContentProvider.write_mime_type_async].
+     * @param result - a `GAsyncResult`
+     */
     writeMimeTypeFinish(result) {
         const error = { value: null };
         const _result = call("libgtk-4.so.1", "gdk_content_provider_write_mime_type_finish", [