@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -5,56 +5,638 @@ import { SettingsBackend } from "./settings-backend.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 export declare class Settings extends GObject.GObject {
+    /**
+     * Creates a new [class@Gio.Settings] object with the schema specified by
+     * @schema_id.
+     *
+     * It is an error for the schema to not exist: schemas are an
+     * essential part of a program, as they provide type information.
+     * If schemas need to be dynamically loaded (for example, from an
+     * optional runtime dependency), [method@Gio.SettingsSchemaSource.lookup]
+     * can be used to test for their existence before loading them.
+     *
+     * Signals on the newly created [class@Gio.Settings] object will be dispatched
+     * via the thread-default [struct@GLib.MainContext] in effect at the time of the
+     * call to [ctor@Gio.Settings.new].  The new [class@Gio.Settings] will hold a reference
+     * on the context.  See [method@GLib.MainContext.push_thread_default].
+     * @param schemaId - the ID of the schema
+     */
     constructor(schemaId: string);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new [class@Gio.Settings] object with a given schema, backend and
+     * path.
+     *
+     * It should be extremely rare that you ever want to use this function.
+     * It is made available for advanced use-cases (such as plugin systems
+     * that want to provide access to schemas loaded from custom locations,
+     * etc).
+     *
+     * At the most basic level, a [class@Gio.Settings] object is a pure composition of
+     * four things: a [struct@Gio.SettingsSchema], a [class@Gio.SettingsBackend], a path within that
+     * backend, and a [struct@GLib.MainContext] to which signals are dispatched.
+     *
+     * This constructor therefore gives you full control over constructing
+     * [class@Gio.Settings] instances.  The first 3 parameters are given directly as
+     * @schema, `backend` and @path, and the main context is taken from the
+     * thread-default (as per [ctor@Gio.Settings.new]).
+     *
+     * If `backend` is `NULL` then the default backend is used.
+     *
+     * If `path` is `NULL` then the path from the schema is used.  It is an
+     * error if `path` is `NULL` and the schema has no path of its own or if
+     * `path` is non-`NULL` and not equal to the path that the schema does
+     * have.
+     * @param schema - the schema describing the settings
+     * @param backend - the settings backend to use
+     * @param path - the path to use
+     */
     static newFull(schema: SettingsSchema, backend?: SettingsBackend | null, path?: string | null): Settings;
+    /**
+     * Creates a new [class@Gio.Settings] object with the schema specified by
+     * `schema_id` and a given [class@Gio.SettingsBackend].
+     *
+     * Creating a [class@Gio.Settings] object with a different backend allows accessing
+     * settings from a database other than the usual one. For example, it may make
+     * sense to pass a backend corresponding to the ‘defaults’ settings database on
+     * the system to get a settings object that modifies the system default
+     * settings instead of the settings for this user.
+     * @param schemaId - the ID of the schema
+     * @param backend - the settings backend to use
+     */
     static newWithBackend(schemaId: string, backend: SettingsBackend): Settings;
+    /**
+     * Creates a new [class@Gio.Settings] object with the schema specified by
+     * `schema_id` and a given [class@Gio.SettingsBackend] and path.
+     *
+     * This is a mix of [ctor@Gio.Settings.new_with_backend] and
+     * [ctor@Gio.Settings.new_with_path].
+     * @param schemaId - the ID of the schema
+     * @param backend - the settings backend to use
+     * @param path - the path to use
+     */
     static newWithBackendAndPath(schemaId: string, backend: SettingsBackend, path: string): Settings;
+    /**
+     * Creates a new [class@Gio.Settings] object with the relocatable schema specified
+     * by `schema_id` and a given path.
+     *
+     * You only need to do this if you want to directly create a settings
+     * object with a schema that doesn’t have a specified path of its own.
+     * That’s quite rare.
+     *
+     * It is a programmer error to call this function for a schema that
+     * has an explicitly specified path.
+     *
+     * It is a programmer error if `path` is not a valid path.  A valid path
+     * begins and ends with `/` and does not contain two consecutive `/`
+     * characters.
+     * @param schemaId - the ID of the schema
+     * @param path - the path to use
+     */
     static newWithPath(schemaId: string, path: string): Settings;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Deprecated.
+     */
     static listRelocatableSchemas(): string[];
+    /**
+     * Deprecated.
+     */
     static listSchemas(): string[];
+    /**
+     * Ensures that all pending operations are complete for the default backend.
+     *
+     * Writes made to a [class@Gio.Settings] are handled asynchronously.  For this
+     * reason, it is very unlikely that the changes have it to disk by the
+     * time [method@Gio.Settings.set] returns.
+     *
+     * This call will block until all of the writes have made it to the
+     * backend.  Since the main loop is not running, no change notifications
+     * will be dispatched during this call (but some may be queued by the
+     * time the call is done).
+     */
     static sync(): void;
+    /**
+     * Removes an existing binding for `property` on @object.
+     *
+     * Note that bindings are automatically removed when the
+     * object is finalized, so it is rarely necessary to call this
+     * function.
+     * @param object - the object with property to unbind
+     * @param property - the property whose binding is removed
+     */
     static unbind(object: GObject.GObject, property: string): void;
+    /**
+     * Applies any changes that have been made to the settings.
+     *
+     * This function does nothing unless `settings` is in
+     * ‘delay-apply’ mode.  In the normal
+     * case settings are always applied immediately.
+     */
     apply(): void;
+    /**
+     * Create a binding between the `key` in the `settings` object
+     * and the property `property` of @object.
+     *
+     * The binding uses the default GIO mapping functions to map
+     * between the settings and property values. These functions
+     * handle booleans, numeric types and string types in a
+     * straightforward way. Use [method@Gio.Settings.bind_with_mapping] if
+     * you need a custom mapping, or map between types that are not
+     * supported by the default mapping functions.
+     *
+     * Unless the `flags` include [flags@Gio.SettingsBindFlags.NO_SENSITIVITY], this
+     * function also establishes a binding between the writability of
+     * `key` and the `sensitive` property of `object` (if `object` has
+     * a boolean property by that name). See [method@Gio.Settings.bind_writable]
+     * for more details about writable bindings.
+     *
+     * Note that the lifecycle of the binding is tied to @object,
+     * and that you can have only one binding per object property.
+     * If you bind the same property twice on the same object, the second
+     * binding overrides the first one.
+     * @param key - the key to bind
+     * @param object - the object with property to bind
+     * @param property - the name of the property to bind
+     * @param flags - flags for the binding
+     */
     bind(key: string, object: GObject.GObject, property: string, flags: SettingsBindFlags): void;
+    /**
+     * Version of [method@Gio.Settings.bind_with_mapping] using closures instead of
+     * callbacks for easier binding in other languages.
+     * @param key - the key to bind
+     * @param object - the object with property to bind
+     * @param property - the name of the property to bind
+     * @param flags - flags for the binding
+     * @param getMapping - a function that gets called to convert values
+     * @param setMapping - a function that gets called to convert values
+     */
     bindWithMappingClosures(key: string, object: GObject.GObject, property: string, flags: SettingsBindFlags, getMapping?: GObject.Closure | null, setMapping?: GObject.Closure | null): void;
+    /**
+     * Create a binding between the writability of `key` in the
+     * `settings` object and the property `property` of @object.
+     *
+     * The property must be boolean; `sensitive` or `visible`
+     * properties of widgets are the most likely candidates.
+     *
+     * Writable bindings are always uni-directional; changes of the
+     * writability of the setting will be propagated to the object
+     * property, not the other way.
+     *
+     * When the `inverted` argument is true, the binding inverts the
+     * value as it passes from the setting to the object, i.e. `property` will be set to true if the key is not writable.
+     *
+     * Note that the lifecycle of the binding is tied to @object,
+     * and that you can have only one binding per object property.
+     * If you bind the same property twice on the same object, the second
+     * binding overrides the first one.
+     * @param key - the key to bind
+     * @param object - the object with property to bind
+     * @param property - the name of a boolean property to bind
+     * @param inverted - whether to ‘invert’ the value
+     */
     bindWritable(key: string, object: GObject.GObject, property: string, inverted: boolean): void;
+    /**
+     * Creates a [iface@Gio.Action] corresponding to a given [class@Gio.Settings] key.
+     *
+     * The action has the same name as the key.
+     *
+     * The value of the key becomes the state of the action and the action
+     * is enabled when the key is writable.  Changing the state of the
+     * action results in the key being written to.  Changes to the value or
+     * writability of the key cause appropriate change notifications to be
+     * emitted for the action.
+     *
+     * For boolean-valued keys, action activations take no parameter and
+     * result in the toggling of the value.  For all other types,
+     * activations take the new value for the key (which must have the
+     * correct type).
+     * @param key - the name of a key in @settings
+     */
     createAction(key: string): Action;
+    /**
+     * Changes the [class@Gio.Settings] object into
+     * ‘delay-apply’ mode.
+     *
+     * In this
+     * mode, changes to `settings` are not immediately propagated to the
+     * backend, but kept locally until [method@Gio.Settings.apply] is called.
+     */
     delay(): void;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for booleans.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `b` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getBoolean(key: string): boolean;
+    /**
+     * Creates a child settings object which has a base path of
+     * `base-path/name`, where `base-path` is the base path of
+     * `settings` and `name` is as specified by the caller.
+     *
+     * The schema for the child settings object must have been declared
+     * in the schema of `settings` using a `<child>` element.
+     *
+     * The created child settings object will inherit the
+     * [property@Gio.Settings:delay-apply] mode from @settings.
+     * @param name - the name of the child schema
+     */
     getChild(name: string): Settings;
+    /**
+     * Gets the ‘default value’ of a key.
+     *
+     * This is the value that would be read if [method@Gio.Settings.reset] were to be
+     * called on the key.
+     *
+     * Note that this may be a different value than returned by
+     * [method@Gio.SettingsSchemaKey.get_default_value] if the system administrator
+     * has provided a default value.
+     *
+     * Comparing the return values of [method@Gio.Settings.get_default_value] and
+     * [method@Gio.Settings.get_value] is not sufficient for determining if a value
+     * has been set because the user may have explicitly set the value to
+     * something that happens to be equal to the default.  The difference
+     * here is that if the default changes in the future, the user’s key
+     * will still be set.
+     *
+     * This function may be useful for adding an indication to a UI of what
+     * the default value was before the user set it.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for @settings.
+     * @param key - the key to get the default value for
+     */
     getDefaultValue(key: string): GLib.Variant | null;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for doubles.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `d` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getDouble(key: string): number;
+    /**
+     * Gets the value that is stored in `settings` for `key` and converts it
+     * to the enum value that it represents.
+     *
+     * In order to use this function the type of the value must be a string
+     * and it must be marked in the schema file as an enumerated type.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for `settings` or is not marked as an enumerated type.
+     *
+     * If the value stored in the configuration database is not a valid
+     * value for the enumerated type then this function will return the
+     * default value.
+     * @param key - the key to get the value for
+     */
     getEnum(key: string): number;
+    /**
+     * Gets the value that is stored in `settings` for `key` and converts it
+     * to the flags value that it represents.
+     *
+     * In order to use this function the type of the value must be an array
+     * of strings and it must be marked in the schema file as a flags type.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for `settings` or is not marked as a flags type.
+     *
+     * If the value stored in the configuration database is not a valid
+     * value for the flags type then this function will return the default
+     * value.
+     * @param key - the key to get the value for
+     */
     getFlags(key: string): number;
+    /**
+     * Returns whether the [class@Gio.Settings] object has any unapplied
+     * changes.
+     *
+     * This can only be the case if it is in
+     * ‘delay-apply’ mode.
+     */
     getHasUnapplied(): boolean;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for 32-bit integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `i` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getInt(key: string): number;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for 64-bit integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `x` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getInt64(key: string): number;
+    /**
+     * Gets the value that is stored at `key` in @settings, subject to
+     * application-level validation/mapping.
+     *
+     * You should use this function when the application needs to perform
+     * some processing on the value of the key (for example, parsing).  The
+     * `mapping` function performs that processing.  If the function
+     * indicates that the processing was unsuccessful (due to a parse error,
+     * for example) then the mapping is tried again with another value.
+     *
+     * This allows a robust ‘fall back to defaults’ behaviour to be
+     * implemented somewhat automatically.
+     *
+     * The first value that is tried is the user’s setting for the key.  If
+     * the mapping function fails to map this value, other values may be
+     * tried in an unspecified order (system or site defaults, translated
+     * schema default values, untranslated schema default values, etc).
+     *
+     * If the mapping function fails for all possible values, one additional
+     * attempt is made: the mapping function is called with a `NULL` value.
+     * If the mapping function still indicates failure at this point then
+     * the application will be aborted.
+     *
+     * The result parameter for the `mapping` function is pointed to a
+     * `gpointer` which is initially set to `NULL`.  The same pointer is given
+     * to each invocation of @mapping.  The final value of that `gpointer` is
+     * what is returned by this function.  `NULL` is valid; it is returned
+     * just as any other value would be.
+     * @param key - the key to get the value for
+     * @param mapping - the function to map the value in the
+     * @param userData - user data for @mapping
+     */
     getMapped(key: string, mapping: (...args: unknown[]) => unknown, userData?: number | null): number | null;
+    /**
+     * Queries the range of a key.
+     * @param key - the key to query the range of
+     */
     getRange(key: string): GLib.Variant;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for strings.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `s` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getString(key: string): string;
+    /**
+     * A convenience variant of [method@Gio.Settings.get] for string arrays.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `as` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getStrv(key: string): string[];
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for 32-bit unsigned
+     * integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `u` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getUint(key: string): number;
+    /**
+     * Gets the value that is stored at `key` in @settings.
+     *
+     * A convenience variant of [method@Gio.Settings.get] for 64-bit unsigned
+     * integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `t` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to get the value for
+     */
     getUint64(key: string): number;
+    /**
+     * Checks the ‘user value’ of a key, if there is one.
+     *
+     * The user value of a key is the last value that was set by the user.
+     *
+     * After calling [method@Gio.Settings.reset] this function should always return
+     * `NULL` (assuming something is not wrong with the system
+     * configuration).
+     *
+     * It is possible that [method@Gio.Settings.get_value] will return a different
+     * value than this function.  This can happen in the case that the user
+     * set a value for a key that was subsequently locked down by the system
+     * administrator — this function will return the user’s old value.
+     *
+     * This function may be useful for adding a ‘reset’ option to a UI or
+     * for providing indication that a particular value has been changed.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for @settings.
+     * @param key - the key to get the user value for
+     */
     getUserValue(key: string): GLib.Variant | null;
+    /**
+     * Gets the value that is stored in `settings` for @key.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for @settings.
+     * @param key - the key to get the value for
+     */
     getValue(key: string): GLib.Variant;
+    /**
+     * Finds out if a key can be written.
+     * @param name - the name of a key
+     */
     isWritable(name: string): boolean;
+    /**
+     * Gets the list of children on @settings.
+     *
+     * The list is exactly the list of strings for which it is not an error
+     * to call [method@Gio.Settings.get_child].
+     *
+     * There is little reason to call this function from ‘normal’ code, since
+     * you should already know what children are in your schema. This function
+     * may still be useful there for introspection reasons, however.
+     *
+     * You should free the return value with [func@GLib.strfreev] when you are done
+     * with it.
+     */
     listChildren(): string[];
+    /**
+     * Introspects the list of keys on @settings.
+     *
+     * 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.
+     *
+     * You should free the return value with [func@GLib.strfreev] when you are done
+     * with it.
+     */
     listKeys(): string[];
+    /**
+     * Checks if the given `value` is of the correct type and within the
+     * permitted range for @key.
+     * @param key - the key to check
+     * @param value - the value to check
+     */
     rangeCheck(key: string, value: GLib.Variant): boolean;
+    /**
+     * Resets `key` to its default value.
+     *
+     * This call resets the key, as much as possible, to its default value.
+     * That might be the value specified in the schema or the one set by the
+     * administrator.
+     * @param key - the name of a key
+     */
     reset(key: string): void;
+    /**
+     * Reverts all unapplied changes to the settings.
+     *
+     * This function does nothing unless `settings` is in
+     * ‘delay-apply’ mode.  In the normal
+     * case settings are always applied immediately.
+     *
+     * Change notifications will be emitted for affected keys.
+     */
     revert(): void;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for booleans.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `b` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setBoolean(key: string, value: boolean): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for doubles.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `d` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setDouble(key: string, value: number): boolean;
+    /**
+     * Looks up the enumerated type nick for `value` and writes it to @key,
+     * within @settings.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for `settings` or is not marked as an enumerated type, or for
+     * `value` not to be a valid value for the named type.
+     *
+     * After performing the write, accessing `key` directly with
+     * [method@Gio.Settings.get_string] will return the ‘nick’ associated with
+     * @value.
+     * @param key - the key to set the value for
+     * @param value - an enumerated value
+     */
     setEnum(key: string, value: number): boolean;
+    /**
+     * Looks up the flags type nicks for the bits specified by @value, puts
+     * them in an array of strings and writes the array to @key, within
+     * @settings.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for `settings` or is not marked as a flags type, or for `value` to contain any bits that are not value for the named type.
+     *
+     * After performing the write, accessing `key` directly with
+     * [method@Gio.Settings.get_strv] will return an array of ‘nicks’; one for each
+     * bit in @value.
+     * @param key - the key to set the value for
+     * @param value - a flags value
+     */
     setFlags(key: string, value: number): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for 32-bit integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `i` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setInt(key: string, value: number): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for 64-bit integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `x` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setInt64(key: string, value: number): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for strings.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `s` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setString(key: string, value: string): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for string arrays.  If
+     * `value` is `NULL`, then `key` is set to be the empty array.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having an `as` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setStrv(key: string, value?: string[] | null): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for 32-bit unsigned
+     * integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `u` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setUint(key: string, value: number): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * A convenience variant of [method@Gio.Settings.set] for 64-bit unsigned
+     * integers.
+     *
+     * It is a programmer error to give a `key` that isn’t specified as
+     * having a `t` type in the schema for `settings` (see [struct@GLib.VariantType]).
+     * @param key - the key to set the value for
+     * @param value - the value to set it to
+     */
     setUint64(key: string, value: number): boolean;
+    /**
+     * Sets `key` in `settings` to @value.
+     *
+     * It is a programmer error to give a `key` that isn’t contained in the
+     * schema for `settings` or for `value` to have the incorrect type, per
+     * the schema.
+     *
+     * If `value` is floating then this function consumes the reference.
+     * @param key - the key to set the value for
+     * @param value - a [struct@GLib.Variant] of the correct type
+     */
     setValue(key: string, value: GLib.Variant): boolean;
     connect(signal: "change-event", handler: (self: Settings, keys: number[], nKeys: number) => boolean, after?: boolean): number;
     connect(signal: "changed", handler: (self: Settings, key: string) => void, after?: boolean): number;