@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/settings-schema-key.js

@@ -1,6 +1,10 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
+/**
+ * #GSettingsSchemaKey is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
 export class SettingsSchemaKey {
     ptr;
     constructor() {
@@ -9,6 +13,12 @@ export class SettingsSchemaKey {
     createPtr(_init) {
         return null;
     }
+    /**
+     * Gets the default value for @key.
+     *
+     * Note that this is the default value according to the schema.  System
+     * administrator defaults and lockdown are not visible via this API.
+     */
     getDefaultValue() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_key_get_default_value", [
             {
@@ -23,6 +33,22 @@ export class SettingsSchemaKey {
         });
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Gets the description for @key.
+     *
+     * If no description has been provided in the schema for @key, returns
+     * %NULL.
+     *
+     * The description can be one sentence to several paragraphs in length.
+     * Paragraphs are delimited with a double newline.  Descriptions can be
+     * translated and the value returned from this function is is the
+     * current locale.
+     *
+     * This function is slow.  The summary and description information for
+     * the schemas is not stored in the compiled schema database so this
+     * function has to parse all of the source XML files in the schema
+     * directory.
+     */
     getDescription() {
         return call("libgio-2.0.so.0", "g_settings_schema_key_get_description", [
             {
@@ -31,6 +57,9 @@ export class SettingsSchemaKey {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the name of @key.
+     */
     getName() {
         return call("libgio-2.0.so.0", "g_settings_schema_key_get_name", [
             {
@@ -39,6 +68,44 @@ export class SettingsSchemaKey {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Queries the range of a key.
+     *
+     * This function will return a #GVariant that fully describes the range
+     * of values that are valid for @key.
+     *
+     * The type of #GVariant returned is `(sv)`. The string describes
+     * the type of range restriction in effect. The type and meaning of
+     * the value contained in the variant depends on the string.
+     *
+     * If the string is `'type'` then the variant contains an empty array.
+     * The element type of that empty array is the expected type of value
+     * and all values of that type are valid.
+     *
+     * If the string is `'enum'` then the variant contains an array
+     * enumerating the possible values. Each item in the array is
+     * a possible valid value and no other values are valid.
+     *
+     * If the string is `'flags'` then the variant contains an array. Each
+     * item in the array is a value that may appear zero or one times in an
+     * array to be used as the value for this key. For example, if the
+     * variant contained the array `['x', 'y']` then the valid values for
+     * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
+     * `['y', 'x']`.
+     *
+     * Finally, if the string is `'range'` then the variant contains a pair
+     * of like-typed values -- the minimum and maximum permissible values
+     * for this key.
+     *
+     * This information should not be used by normal programs.  It is
+     * considered to be a hint for introspection purposes.  Normal programs
+     * should already know what is permitted by their own schema.  The
+     * format may change in any way in the future -- but particularly, new
+     * forms may be added to the possibilities described above.
+     *
+     * You should free the returned value with g_variant_unref() when it is
+     * no longer needed.
+     */
     getRange() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_key_get_range", [
             {
@@ -53,6 +120,21 @@ export class SettingsSchemaKey {
         });
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Gets the summary for @key.
+     *
+     * If no summary has been provided in the schema for @key, returns
+     * %NULL.
+     *
+     * The summary is a short description of the purpose of the key; usually
+     * one short sentence.  Summaries can be translated and the value
+     * returned from this function is is the current locale.
+     *
+     * This function is slow.  The summary and description information for
+     * the schemas is not stored in the compiled schema database so this
+     * function has to parse all of the source XML files in the schema
+     * directory.
+     */
     getSummary() {
         return call("libgio-2.0.so.0", "g_settings_schema_key_get_summary", [
             {
@@ -61,6 +143,9 @@ export class SettingsSchemaKey {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the #GVariantType of @key.
+     */
     getValueType() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_key_get_value_type", [
             {
@@ -75,6 +160,14 @@ export class SettingsSchemaKey {
         });
         return getObject(ptr, GLib.VariantType);
     }
+    /**
+     * Checks if the given `value` is within the
+     * permitted range for @key.
+     *
+     * It is a programmer error if `value` is not of the correct type — you
+     * must check for this first.
+     * @param value - the value to check
+     */
     rangeCheck(value) {
         return call("libgio-2.0.so.0", "g_settings_schema_key_range_check", [
             {
@@ -92,6 +185,9 @@ export class SettingsSchemaKey {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Increase the reference count of @key, returning a new reference.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_key_ref", [
             {
@@ -106,6 +202,9 @@ export class SettingsSchemaKey {
         });
         return getObject(ptr, SettingsSchemaKey);
     }
+    /**
+     * Decrease the reference count of @key, possibly freeing it.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_settings_schema_key_unref", [
             {

package/dist/generated/gio/settings-schema-source.d.ts

@@ -1,13 +1,102 @@
 import { Ref } from "@gtkx/native";
 import { SettingsSchema } from "./settings-schema.js";
+/** This is an opaque structure type.  You may not access it directly. */
 export declare class SettingsSchemaSource {
     ptr: unknown;
+    /**
+     * Attempts to create a new schema source corresponding to the contents
+     * of the given directory.
+     *
+     * This function is not required for normal uses of #GSettings but it
+     * may be useful to authors of plugin management systems.
+     *
+     * The directory should contain a file called `gschemas.compiled` as
+     * produced by the [glib-compile-schemas][glib-compile-schemas] tool.
+     *
+     * If `trusted` is %TRUE then `gschemas.compiled` is trusted not to be
+     * corrupted. This assumption has a performance advantage, but can result
+     * in crashes or inconsistent behaviour in the case of a corrupted file.
+     * Generally, you should set `trusted` to %TRUE for files installed by the
+     * system and to %FALSE for files in the home directory.
+     *
+     * In either case, an empty file or some types of corruption in the file will
+     * result in %G_FILE_ERROR_INVAL being returned.
+     *
+     * If `parent` is non-%NULL then there are two effects.
+     *
+     * First, if g_settings_schema_source_lookup() is called with the
+     * `recursive` flag set to %TRUE and the schema can not be found in the
+     * source, the lookup will recurse to the parent.
+     *
+     * Second, any references to other schemas specified within this
+     * source (ie: `child` or `extends`) references may be resolved
+     * from the @parent.
+     *
+     * For this second reason, except in very unusual situations, the
+     * `parent` should probably be given as the default schema source, as
+     * returned by g_settings_schema_source_get_default().
+     * @param directory - the filename of a directory
+     * @param parent - a #GSettingsSchemaSource, or %NULL
+     * @param trusted - %TRUE, if the directory is trusted
+     */
     constructor(directory: string, trusted: boolean, parent?: SettingsSchemaSource | null);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the default system schema source.
+     *
+     * This function is not required for normal uses of #GSettings but it
+     * may be useful to authors of plugin management systems or to those who
+     * want to introspect the content of schemas.
+     *
+     * If no schemas are installed, %NULL will be returned.
+     *
+     * The returned source may actually consist of multiple schema sources
+     * from different directories, depending on which directories were given
+     * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+     * lookups performed against the default source should probably be done
+     * recursively.
+     */
     static getDefault(): SettingsSchemaSource;
+    /**
+     * Lists the schemas in a given source.
+     *
+     * If `recursive` is %TRUE then include parent sources.  If %FALSE then
+     * only include the schemas from one source (ie: one directory).  You
+     * probably want %TRUE.
+     *
+     * Non-relocatable schemas are those for which you can call
+     * g_settings_new().  Relocatable schemas are those for which you must
+     * use g_settings_new_with_path().
+     *
+     * Do not call this function from normal programs.  This is designed for
+     * use by database editors, commandline tools, etc.
+     * @param recursive - if we should recurse
+     * @param nonRelocatable - the
+     * @param relocatable - the list
+     */
     listSchemas(recursive: boolean, nonRelocatable: Ref<string[]>, relocatable: Ref<string[]>): void;
+    /**
+     * Looks up a schema with the identifier `schema_id` in @source.
+     *
+     * This function is not required for normal uses of #GSettings but it
+     * may be useful to authors of plugin management systems or to those who
+     * want to introspect the content of schemas.
+     *
+     * If the schema isn't found directly in `source` and `recursive` is %TRUE
+     * then the parent sources will also be checked.
+     *
+     * If the schema isn't found, %NULL is returned.
+     * @param schemaId - a schema ID
+     * @param recursive - %TRUE if the lookup should be recursive
+     */
     lookup(schemaId: string, recursive: boolean): SettingsSchema | null;
+    /**
+     * Increase the reference count of @source, returning a new reference.
+     */
     ref(): SettingsSchemaSource;
+    /**
+     * Decrease the reference count of @source, possibly freeing it.
+     */
     unref(): void;
 }

package/dist/generated/gio/settings-schema-source.js

@@ -1,6 +1,7 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SettingsSchema } from "./settings-schema.js";
+/** This is an opaque structure type.  You may not access it directly. */
 export class SettingsSchemaSource {
     ptr;
     constructor(...args) {
@@ -30,6 +31,21 @@ export class SettingsSchemaSource {
             },
         ], { type: "boxed", borrowed: true, innerType: "GSettingsSchemaSource" });
     }
+    /**
+     * Gets the default system schema source.
+     *
+     * This function is not required for normal uses of #GSettings but it
+     * may be useful to authors of plugin management systems or to those who
+     * want to introspect the content of schemas.
+     *
+     * If no schemas are installed, %NULL will be returned.
+     *
+     * The returned source may actually consist of multiple schema sources
+     * from different directories, depending on which directories were given
+     * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+     * lookups performed against the default source should probably be done
+     * recursively.
+     */
     static getDefault() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_source_get_default", [], {
             type: "boxed",
@@ -39,6 +55,23 @@ export class SettingsSchemaSource {
         });
         return getObject(ptr, SettingsSchemaSource);
     }
+    /**
+     * Lists the schemas in a given source.
+     *
+     * If `recursive` is %TRUE then include parent sources.  If %FALSE then
+     * only include the schemas from one source (ie: one directory).  You
+     * probably want %TRUE.
+     *
+     * Non-relocatable schemas are those for which you can call
+     * g_settings_new().  Relocatable schemas are those for which you must
+     * use g_settings_new_with_path().
+     *
+     * Do not call this function from normal programs.  This is designed for
+     * use by database editors, commandline tools, etc.
+     * @param recursive - if we should recurse
+     * @param nonRelocatable - the
+     * @param relocatable - the list
+     */
     listSchemas(recursive, nonRelocatable, relocatable) {
         call("libgio-2.0.so.0", "g_settings_schema_source_list_schemas", [
             {
@@ -65,6 +98,20 @@ export class SettingsSchemaSource {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Looks up a schema with the identifier `schema_id` in @source.
+     *
+     * This function is not required for normal uses of #GSettings but it
+     * may be useful to authors of plugin management systems or to those who
+     * want to introspect the content of schemas.
+     *
+     * If the schema isn't found directly in `source` and `recursive` is %TRUE
+     * then the parent sources will also be checked.
+     *
+     * If the schema isn't found, %NULL is returned.
+     * @param schemaId - a schema ID
+     * @param recursive - %TRUE if the lookup should be recursive
+     */
     lookup(schemaId, recursive) {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_source_lookup", [
             {
@@ -89,6 +136,9 @@ export class SettingsSchemaSource {
             return null;
         return getObject(ptr, SettingsSchema);
     }
+    /**
+     * Increase the reference count of @source, returning a new reference.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_source_ref", [
             {
@@ -103,6 +153,9 @@ export class SettingsSchemaSource {
         });
         return getObject(ptr, SettingsSchemaSource);
     }
+    /**
+     * Decrease the reference count of @source, possibly freeing it.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_settings_schema_source_unref", [
             {

package/dist/generated/gio/settings-schema.d.ts

@@ -1,14 +1,150 @@
 import { SettingsSchemaKey } from "./settings-schema-key.js";
+/**
+ * The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a
+ * mechanism for advanced control over the loading of schemas and a
+ * mechanism for introspecting their content.
+ *
+ * Plugin loading systems that wish to provide plugins a way to access
+ * settings face the problem of how to make the schemas for these
+ * settings visible to GSettings.  Typically, a plugin will want to ship
+ * the schema along with itself and it won't be installed into the
+ * standard system directories for schemas.
+ *
+ * [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this
+ * by allowing the creation of a new ‘schema source’ from which schemas can
+ * be acquired.  This schema source can then become part of the metadata
+ * associated with the plugin and queried whenever the plugin requires
+ * access to some settings.
+ *
+ * Consider the following example:
+ *
+ * ```c
+ * typedef struct
+ * {
+ * …
+ * GSettingsSchemaSource *schema_source;
+ * …
+ * } Plugin;
+ *
+ * Plugin *
+ * initialise_plugin (const gchar *dir)
+ * {
+ * Plugin *plugin;
+ *
+ * …
+ *
+ * plugin->schema_source =
+ * g_settings_schema_source_new_from_directory (dir,
+ * g_settings_schema_source_get_default (), FALSE, NULL);
+ *
+ * …
+ *
+ * return plugin;
+ * }
+ *
+ * …
+ *
+ * GSettings *
+ * plugin_get_settings (Plugin      *plugin,
+ * const gchar *schema_id)
+ * {
+ * GSettingsSchema *schema;
+ *
+ * if (schema_id == NULL)
+ * schema_id = plugin->identifier;
+ *
+ * schema = g_settings_schema_source_lookup (plugin->schema_source,
+ * schema_id, FALSE);
+ *
+ * if (schema == NULL)
+ * {
+ * … disable the plugin or abort, etc …
+ * }
+ *
+ * return g_settings_new_full (schema, NULL, NULL);
+ * }
+ * ```
+ *
+ * The code above shows how hooks should be added to the code that
+ * initialises (or enables) the plugin to create the schema source and
+ * how an API can be added to the plugin system to provide a convenient
+ * way for the plugin to access its settings, using the schemas that it
+ * ships.
+ *
+ * From the standpoint of the plugin, it would need to ensure that it
+ * ships a gschemas.compiled file as part of itself, and then simply do
+ * the following:
+ *
+ * ```c
+ * {
+ * GSettings *settings;
+ * gint some_value;
+ *
+ * settings = plugin_get_settings (self, NULL);
+ * some_value = g_settings_get_int (settings, "some-value");
+ * …
+ * }
+ * ```
+ *
+ * It's also possible that the plugin system expects the schema source
+ * files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file.
+ * In that case, the plugin loading system must compile the schemas for
+ * itself before attempting to create the settings source.
+ */
 export declare class SettingsSchema {
     ptr: unknown;
     constructor();
     protected createPtr(_init: Record<string, unknown>): unknown;
+    /**
+     * Get the ID of @schema.
+     */
     getId(): string;
+    /**
+     * Gets the key named `name` from @schema.
+     *
+     * It is a programmer error to request a key that does not exist.  See
+     * g_settings_schema_list_keys().
+     * @param name - the name of a key
+     */
     getKey(name: string): SettingsSchemaKey;
+    /**
+     * Gets the path associated with @schema, or %NULL.
+     *
+     * Schemas may be single-instance or relocatable.  Single-instance
+     * schemas correspond to exactly one set of keys in the backend
+     * database: those located at the path returned by this function.
+     *
+     * Relocatable schemas can be referenced by other schemas and can
+     * therefore describe multiple sets of keys at different locations.  For
+     * relocatable schemas, this function will return %NULL.
+     */
     getPath(): string | null;
+    /**
+     * Checks if `schema` has a key named @name.
+     * @param name - the name of a key
+     */
     hasKey(name: string): boolean;
+    /**
+     * Gets the list of children in @schema.
+     *
+     * You should free the return value with g_strfreev() when you are done
+     * with it.
+     */
     listChildren(): string[];
+    /**
+     * Introspects the list of keys on @schema.
+     *
+     * You should probably not be calling this function from "normal" code
+     * (since you should already know what keys are in your schema).  This
+     * function is intended for introspection reasons.
+     */
     listKeys(): string[];
+    /**
+     * Increase the reference count of @schema, returning a new reference.
+     */
     ref(): SettingsSchema;
+    /**
+     * Decrease the reference count of @schema, possibly freeing it.
+     */
     unref(): void;
 }

package/dist/generated/gio/settings-schema.js

@@ -1,6 +1,98 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SettingsSchemaKey } from "./settings-schema-key.js";
+/**
+ * The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a
+ * mechanism for advanced control over the loading of schemas and a
+ * mechanism for introspecting their content.
+ *
+ * Plugin loading systems that wish to provide plugins a way to access
+ * settings face the problem of how to make the schemas for these
+ * settings visible to GSettings.  Typically, a plugin will want to ship
+ * the schema along with itself and it won't be installed into the
+ * standard system directories for schemas.
+ *
+ * [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this
+ * by allowing the creation of a new ‘schema source’ from which schemas can
+ * be acquired.  This schema source can then become part of the metadata
+ * associated with the plugin and queried whenever the plugin requires
+ * access to some settings.
+ *
+ * Consider the following example:
+ *
+ * ```c
+ * typedef struct
+ * {
+ * …
+ * GSettingsSchemaSource *schema_source;
+ * …
+ * } Plugin;
+ *
+ * Plugin *
+ * initialise_plugin (const gchar *dir)
+ * {
+ * Plugin *plugin;
+ *
+ * …
+ *
+ * plugin->schema_source =
+ * g_settings_schema_source_new_from_directory (dir,
+ * g_settings_schema_source_get_default (), FALSE, NULL);
+ *
+ * …
+ *
+ * return plugin;
+ * }
+ *
+ * …
+ *
+ * GSettings *
+ * plugin_get_settings (Plugin      *plugin,
+ * const gchar *schema_id)
+ * {
+ * GSettingsSchema *schema;
+ *
+ * if (schema_id == NULL)
+ * schema_id = plugin->identifier;
+ *
+ * schema = g_settings_schema_source_lookup (plugin->schema_source,
+ * schema_id, FALSE);
+ *
+ * if (schema == NULL)
+ * {
+ * … disable the plugin or abort, etc …
+ * }
+ *
+ * return g_settings_new_full (schema, NULL, NULL);
+ * }
+ * ```
+ *
+ * The code above shows how hooks should be added to the code that
+ * initialises (or enables) the plugin to create the schema source and
+ * how an API can be added to the plugin system to provide a convenient
+ * way for the plugin to access its settings, using the schemas that it
+ * ships.
+ *
+ * From the standpoint of the plugin, it would need to ensure that it
+ * ships a gschemas.compiled file as part of itself, and then simply do
+ * the following:
+ *
+ * ```c
+ * {
+ * GSettings *settings;
+ * gint some_value;
+ *
+ * settings = plugin_get_settings (self, NULL);
+ * some_value = g_settings_get_int (settings, "some-value");
+ * …
+ * }
+ * ```
+ *
+ * It's also possible that the plugin system expects the schema source
+ * files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file.
+ * In that case, the plugin loading system must compile the schemas for
+ * itself before attempting to create the settings source.
+ */
 export class SettingsSchema {
     ptr;
     constructor() {
@@ -9,6 +101,9 @@ export class SettingsSchema {
     createPtr(_init) {
         return null;
     }
+    /**
+     * Get the ID of @schema.
+     */
     getId() {
         return call("libgio-2.0.so.0", "g_settings_schema_get_id", [
             {
@@ -17,6 +112,13 @@ export class SettingsSchema {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the key named `name` from @schema.
+     *
+     * It is a programmer error to request a key that does not exist.  See
+     * g_settings_schema_list_keys().
+     * @param name - the name of a key
+     */
     getKey(name) {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_get_key", [
             {
@@ -35,6 +137,17 @@ export class SettingsSchema {
         });
         return getObject(ptr, SettingsSchemaKey);
     }
+    /**
+     * Gets the path associated with @schema, or %NULL.
+     *
+     * Schemas may be single-instance or relocatable.  Single-instance
+     * schemas correspond to exactly one set of keys in the backend
+     * database: those located at the path returned by this function.
+     *
+     * Relocatable schemas can be referenced by other schemas and can
+     * therefore describe multiple sets of keys at different locations.  For
+     * relocatable schemas, this function will return %NULL.
+     */
     getPath() {
         return call("libgio-2.0.so.0", "g_settings_schema_get_path", [
             {
@@ -43,6 +156,10 @@ export class SettingsSchema {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Checks if `schema` has a key named @name.
+     * @param name - the name of a key
+     */
     hasKey(name) {
         return call("libgio-2.0.so.0", "g_settings_schema_has_key", [
             {
@@ -55,6 +172,12 @@ export class SettingsSchema {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the list of children in @schema.
+     *
+     * You should free the return value with g_strfreev() when you are done
+     * with it.
+     */
     listChildren() {
         return call("libgio-2.0.so.0", "g_settings_schema_list_children", [
             {
@@ -63,6 +186,13 @@ export class SettingsSchema {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Introspects the list of keys on @schema.
+     *
+     * You should probably not be calling this function from "normal" code
+     * (since you should already know what keys are in your schema).  This
+     * function is intended for introspection reasons.
+     */
     listKeys() {
         return call("libgio-2.0.so.0", "g_settings_schema_list_keys", [
             {
@@ -71,6 +201,9 @@ export class SettingsSchema {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Increase the reference count of @schema, returning a new reference.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_settings_schema_ref", [
             {
@@ -85,6 +218,9 @@ export class SettingsSchema {
         });
         return getObject(ptr, SettingsSchema);
     }
+    /**
+     * Decrease the reference count of @schema, possibly freeing it.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_settings_schema_unref", [
             {