@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtksource/file-loader.js

@@ -5,10 +5,36 @@ import { Buffer } from "./buffer.js";
 import { File } from "./file.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Load a file into a GtkSourceBuffer.
+ *
+ * A `GtkSourceFileLoader` object permits to load the contents of a [iface@Gio.File] or a
+ * [class@Gio.InputStream] into a [class@Buffer].
+ *
+ * A file loader should be used only for one load operation, including errors
+ * handling. If an error occurs, you can reconfigure the loader and relaunch the
+ * operation with [method@FileLoader.load_async].
+ *
+ * Running a `GtkSourceFileLoader` is an undoable action for the
+ * [class@Buffer].
+ *
+ * After a file loading, the buffer is reset to the contents provided by the
+ * [iface@Gio.File] or [class@Gio.InputStream], so the buffer is set as “unmodified”, that is,
+ * [method@Gtk.TextBuffer.set_modified] is called with %FALSE. If the contents isn't
+ * saved somewhere (for example if you load from stdin), then you should
+ * probably call [method@Gtk.TextBuffer.set_modified] with %TRUE after calling
+ * [method@FileLoader.load_finish].
+ */
 export class FileLoader extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new #GtkSourceFileLoader object. The contents is read from @stream.
+     * @param buffer - the #GtkSourceBuffer to load the contents into.
+     * @param file - the #GtkSourceFile.
+     * @param stream - the #GInputStream to load, e.g. stdin.
+     */
     static fileLoaderNewFromStream(buffer, file, stream) {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_file_loader_new_from_stream", [
             {
@@ -109,6 +135,14 @@ export class FileLoader extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Finishes a file loading started with [method@FileLoader.load_async].
+     *
+     * If the contents has been loaded, the following [class@File] properties will
+     * be updated: the location, the encoding, the newline type and the compression
+     * type.
+     * @param result - a #GAsyncResult.
+     */
     loadFinish(result) {
         const error = { value: null };
         const _result = call("libgtksourceview-5.so.0", "gtk_source_file_loader_load_finish", [
@@ -137,6 +171,20 @@ export class FileLoader extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Sets the candidate encodings for the file loading.
+     *
+     * The encodings are tried in the same order as the list.
+     *
+     * For convenience, `candidate_encodings` can contain duplicates. Only the first
+     * occurrence of a duplicated encoding is kept in the list.
+     *
+     * By default the candidate encodings are (in that order in the list):
+     *
+     * 1. If set, the [class@File]'s encoding as returned by [method@File.get_encoding].
+     * 2. The default candidates as returned by [func@Encoding.get_default_candidates].
+     * @param candidateEncodings - a list of
+     */
     setCandidateEncodings(candidateEncodings) {
         call("libgtksourceview-5.so.0", "gtk_source_file_loader_set_candidate_encodings", [
             {

package/dist/generated/gtksource/file-saver.d.ts

@@ -4,9 +4,40 @@ import { Buffer } from "./buffer.js";
 import { File } from "./file.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Save a [class@Buffer] into a file.
+ *
+ * A `GtkSourceFileSaver` object permits to save a [class@Buffer] into a
+ * [iface@Gio.File].
+ *
+ * A file saver should be used only for one save operation, including errors
+ * handling. If an error occurs, you can reconfigure the saver and relaunch the
+ * operation with [method@FileSaver.save_async].
+ */
 export declare class FileSaver extends GObject.GObject {
+    /**
+     * Creates a new #GtkSourceFileSaver object. The `buffer` will be saved to the
+     * [class@File]'s location.
+     *
+     * This constructor is suitable for a simple "save" operation, when the `file` already contains a non-%NULL [property@File:location].
+     * @param buffer - the #GtkSourceBuffer to save.
+     * @param file - the #GtkSourceFile.
+     */
     constructor(buffer: Buffer, file: File);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new #GtkSourceFileSaver object with a target location.
+     *
+     * When the file saving is finished successfully, `target_location` is set to the @file's
+     * [property@File:location] property. If an error occurs, the previous valid
+     * location is still available in [class@File].
+     *
+     * This constructor is suitable for a "save as" operation, or for saving a new
+     * buffer for the first time.
+     * @param buffer - the #GtkSourceBuffer to save.
+     * @param file - the #GtkSourceFile.
+     * @param targetLocation - the #GFile where to save the buffer to.
+     */
     static fileSaverNewWithTarget(buffer: Buffer, file: File, targetLocation: Gio.File): FileSaver;
     protected createPtr(args: unknown[]): unknown;
     getBuffer(): Buffer;
@@ -16,10 +47,40 @@ export declare class FileSaver extends GObject.GObject {
     getFlags(): FileSaverFlags;
     getLocation(): Gio.File;
     getNewlineType(): NewlineType;
+    /**
+     * Finishes a file saving started with [method@FileSaver.save_async].
+     *
+     * If the file has been saved successfully, the following [class@File]
+     * properties will be updated: the location, the encoding, the newline type and
+     * the compression type.
+     *
+     * Since the 3.20 version, [method@Gtk.TextBuffer.set_modified] is called with %FALSE
+     * if the file has been saved successfully.
+     * @param result - a #GAsyncResult.
+     */
     saveFinish(result: Gio.AsyncResult): boolean;
+    /**
+     * Sets the compression type. By default the compression type is taken from the
+     * #GtkSourceFile.
+     * @param compressionType - the new compression type.
+     */
     setCompressionType(compressionType: CompressionType): void;
+    /**
+     * Sets the encoding. If `encoding` is %NULL, the UTF-8 encoding will be set.
+     *
+     * By default the encoding is taken from the #GtkSourceFile.
+     * @param encoding - the new encoding, or %NULL for UTF-8.
+     */
     setEncoding(encoding?: Encoding | null): void;
+    /**
+     * @param flags - the new flags.
+     */
     setFlags(flags: FileSaverFlags): void;
+    /**
+     * Sets the newline type. By default the newline type is taken from the
+     * #GtkSourceFile.
+     * @param newlineType - the new newline type.
+     */
     setNewlineType(newlineType: NewlineType): void;
     connect(signal: "notify", handler: (self: FileSaver, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtksource/file-saver.js

@@ -5,10 +5,33 @@ import { Buffer } from "./buffer.js";
 import { File } from "./file.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Save a [class@Buffer] into a file.
+ *
+ * A `GtkSourceFileSaver` object permits to save a [class@Buffer] into a
+ * [iface@Gio.File].
+ *
+ * A file saver should be used only for one save operation, including errors
+ * handling. If an error occurs, you can reconfigure the saver and relaunch the
+ * operation with [method@FileSaver.save_async].
+ */
 export class FileSaver extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new #GtkSourceFileSaver object with a target location.
+     *
+     * When the file saving is finished successfully, `target_location` is set to the @file's
+     * [property@File:location] property. If an error occurs, the previous valid
+     * location is still available in [class@File].
+     *
+     * This constructor is suitable for a "save as" operation, or for saving a new
+     * buffer for the first time.
+     * @param buffer - the #GtkSourceBuffer to save.
+     * @param file - the #GtkSourceFile.
+     * @param targetLocation - the #GFile where to save the buffer to.
+     */
     static fileSaverNewWithTarget(buffer, file, targetLocation) {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_file_saver_new_with_target", [
             {
@@ -104,6 +127,17 @@ export class FileSaver extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Finishes a file saving started with [method@FileSaver.save_async].
+     *
+     * If the file has been saved successfully, the following [class@File]
+     * properties will be updated: the location, the encoding, the newline type and
+     * the compression type.
+     *
+     * Since the 3.20 version, [method@Gtk.TextBuffer.set_modified] is called with %FALSE
+     * if the file has been saved successfully.
+     * @param result - a #GAsyncResult.
+     */
     saveFinish(result) {
         const error = { value: null };
         const _result = call("libgtksourceview-5.so.0", "gtk_source_file_saver_save_finish", [
@@ -132,6 +166,11 @@ export class FileSaver extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Sets the compression type. By default the compression type is taken from the
+     * #GtkSourceFile.
+     * @param compressionType - the new compression type.
+     */
     setCompressionType(compressionType) {
         call("libgtksourceview-5.so.0", "gtk_source_file_saver_set_compression_type", [
             {
@@ -144,6 +183,12 @@ export class FileSaver extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the encoding. If `encoding` is %NULL, the UTF-8 encoding will be set.
+     *
+     * By default the encoding is taken from the #GtkSourceFile.
+     * @param encoding - the new encoding, or %NULL for UTF-8.
+     */
     setEncoding(encoding) {
         call("libgtksourceview-5.so.0", "gtk_source_file_saver_set_encoding", [
             {
@@ -162,6 +207,9 @@ export class FileSaver extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * @param flags - the new flags.
+     */
     setFlags(flags) {
         call("libgtksourceview-5.so.0", "gtk_source_file_saver_set_flags", [
             {
@@ -174,6 +222,11 @@ export class FileSaver extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the newline type. By default the newline type is taken from the
+     * #GtkSourceFile.
+     * @param newlineType - the new newline type.
+     */
     setNewlineType(newlineType) {
         call("libgtksourceview-5.so.0", "gtk_source_file_saver_set_newline_type", [
             {

package/dist/generated/gtksource/file.d.ts

@@ -2,18 +2,73 @@ import { CompressionType, NewlineType } from "./enums.js";
 import { Encoding } from "./encoding.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * On-disk representation of a [class@Buffer].
+ *
+ * A `GtkSourceFile` object is the on-disk representation of a [class@Buffer].
+ * With a `GtkSourceFile`, you can create and configure a [class@FileLoader]
+ * and [class@FileSaver] which take by default the values of the
+ * `GtkSourceFile` properties (except for the file loader which auto-detect some
+ * properties). On a successful load or save operation, the `GtkSourceFile`
+ * properties are updated. If an operation fails, the `GtkSourceFile` properties
+ * have still the previous valid values.
+ */
 export declare class File extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Checks synchronously the file on disk, to know whether the file is externally
+     * modified, or has been deleted, and whether the file is read-only.
+     *
+     * #GtkSourceFile doesn't create a [class@Gio.FileMonitor] to track those properties, so
+     * this function needs to be called instead. Creating lots of [class@Gio.FileMonitor]'s
+     * would take lots of resources.
+     *
+     * Since this function is synchronous, it is advised to call it only on local
+     * files. See [method@File.is_local].
+     */
     checkFileOnDisk(): void;
     getCompressionType(): CompressionType;
+    /**
+     * The encoding is initially %NULL. After a successful file loading or saving
+     * operation, the encoding is non-%NULL.
+     */
     getEncoding(): Encoding;
     getLocation(): Gio.File;
     getNewlineType(): NewlineType;
+    /**
+     * Returns whether the file has been deleted. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isDeleted(): boolean;
+    /**
+     * Returns whether the file is externally modified. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isExternallyModified(): boolean;
+    /**
+     * Returns whether the file is local. If the [property@File:location] is %NULL,
+     * returns %FALSE.
+     */
     isLocal(): boolean;
+    /**
+     * Returns whether the file is read-only. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isReadonly(): boolean;
+    /**
+     * Sets the location.
+     * @param location - the new #GFile, or %NULL.
+     */
     setLocation(location?: Gio.File | null): void;
     connect(signal: "notify", handler: (self: File, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtksource/file.js

@@ -3,6 +3,17 @@ import { getObject } from "@gtkx/ffi";
 import { Encoding } from "./encoding.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * On-disk representation of a [class@Buffer].
+ *
+ * A `GtkSourceFile` object is the on-disk representation of a [class@Buffer].
+ * With a `GtkSourceFile`, you can create and configure a [class@FileLoader]
+ * and [class@FileSaver] which take by default the values of the
+ * `GtkSourceFile` properties (except for the file loader which auto-detect some
+ * properties). On a successful load or save operation, the `GtkSourceFile`
+ * properties are updated. If an operation fails, the `GtkSourceFile` properties
+ * have still the previous valid values.
+ */
 export class File extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -13,6 +24,17 @@ export class File extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Checks synchronously the file on disk, to know whether the file is externally
+     * modified, or has been deleted, and whether the file is read-only.
+     *
+     * #GtkSourceFile doesn't create a [class@Gio.FileMonitor] to track those properties, so
+     * this function needs to be called instead. Creating lots of [class@Gio.FileMonitor]'s
+     * would take lots of resources.
+     *
+     * Since this function is synchronous, it is advised to call it only on local
+     * files. See [method@File.is_local].
+     */
     checkFileOnDisk() {
         call("libgtksourceview-5.so.0", "gtk_source_file_check_file_on_disk", [
             {
@@ -29,6 +51,10 @@ export class File extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * The encoding is initially %NULL. After a successful file loading or saving
+     * operation, the encoding is non-%NULL.
+     */
     getEncoding() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_file_get_encoding", [
             {
@@ -60,6 +86,13 @@ export class File extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether the file has been deleted. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isDeleted() {
         return call("libgtksourceview-5.so.0", "gtk_source_file_is_deleted", [
             {
@@ -68,6 +101,13 @@ export class File extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the file is externally modified. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isExternallyModified() {
         return call("libgtksourceview-5.so.0", "gtk_source_file_is_externally_modified", [
             {
@@ -76,6 +116,10 @@ export class File extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the file is local. If the [property@File:location] is %NULL,
+     * returns %FALSE.
+     */
     isLocal() {
         return call("libgtksourceview-5.so.0", "gtk_source_file_is_local", [
             {
@@ -84,6 +128,13 @@ export class File extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the file is read-only. If the
+     * [property@File:location] is %NULL, returns %FALSE.
+     *
+     * To have an up-to-date value, you must first call
+     * [method@File.check_file_on_disk].
+     */
     isReadonly() {
         return call("libgtksourceview-5.so.0", "gtk_source_file_is_readonly", [
             {
@@ -92,6 +143,10 @@ export class File extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the location.
+     * @param location - the new #GFile, or %NULL.
+     */
     setLocation(location) {
         call("libgtksourceview-5.so.0", "gtk_source_file_set_location", [
             {

package/dist/generated/gtksource/functions.d.ts

@@ -1,19 +1,148 @@
 import { Encoding } from "./encoding.js";
+/**
+ * Like GTK_SOURCE_CHECK_VERSION, but the check for gtk_source_check_version is
+ * at runtime instead of compile time. This is useful for compiling
+ * against older versions of GtkSourceView, but using features from newer
+ * versions.
+ * @param major - the major version to check
+ * @param minor - the minor version to check
+ * @param micro - the micro version to check
+ */
 export declare const checkVersion: (major: number, minor: number, micro: number) => boolean;
+/**
+ * Gets all encodings.
+ */
 export declare const encodingGetAll: () => Encoding[];
+/**
+ * Gets the #GtkSourceEncoding for the current locale.
+ *
+ * See also [func@GLib.get_charset].
+ */
 export declare const encodingGetCurrent: () => Encoding;
+/**
+ * Gets the list of default candidate encodings to try when loading a file.
+ *
+ * See [method@FileLoader.set_candidate_encodings].
+ *
+ * This function returns a different list depending on the current locale (i.e.
+ * language, country and default encoding). The UTF-8 encoding and the current
+ * locale encoding are guaranteed to be present in the returned list.
+ */
 export declare const encodingGetDefaultCandidates: () => Encoding[];
+/**
+ * Gets a #GtkSourceEncoding from a character set such as "UTF-8" or
+ * "ISO-8859-1".
+ * @param charset - a character set.
+ */
 export declare const encodingGetFromCharset: (charset: string) => Encoding | null;
 export declare const encodingGetUtf8: () => Encoding;
 export declare const fileLoaderErrorQuark: () => number;
 export declare const fileSaverErrorQuark: () => number;
+/**
+ * Free the resources allocated by GtkSourceView. For example it unrefs the
+ * singleton objects.
+ *
+ * It is not mandatory to call this function, it's just to be friendlier to
+ * memory debugging tools. This function is meant to be called at the end of
+ * main(). It can be called several times.
+ */
 export declare const finalize: () => void;
+/**
+ * Returns the major version number of the GtkSourceView library.
+ * (e.g. in GtkSourceView version 3.20.0 this is 3.)
+ *
+ * This function is in the library, so it represents the GtkSourceView library
+ * your code is running against. Contrast with the #GTK_SOURCE_MAJOR_VERSION
+ * macro, which represents the major version of the GtkSourceView headers you
+ * have included when compiling your code.
+ */
 export declare const getMajorVersion: () => number;
+/**
+ * Returns the micro version number of the GtkSourceView library.
+ * (e.g. in GtkSourceView version 3.20.0 this is 0.)
+ *
+ * This function is in the library, so it represents the GtkSourceView library
+ * your code is running against. Contrast with the #GTK_SOURCE_MICRO_VERSION
+ * macro, which represents the micro version of the GtkSourceView headers you
+ * have included when compiling your code.
+ */
 export declare const getMicroVersion: () => number;
+/**
+ * Returns the minor version number of the GtkSourceView library.
+ * (e.g. in GtkSourceView version 3.20.0 this is 20.)
+ *
+ * This function is in the library, so it represents the GtkSourceView library
+ * your code is running against. Contrast with the #GTK_SOURCE_MINOR_VERSION
+ * macro, which represents the minor version of the GtkSourceView headers you
+ * have included when compiling your code.
+ */
 export declare const getMinorVersion: () => number;
+/**
+ * Initializes the GtkSourceView library (e.g. for the internationalization).
+ *
+ * This function can be called several times, but is meant to be called at the
+ * beginning of main(), before any other GtkSourceView function call.
+ *
+ * The counterpart to this function is [func@finalize] which can be convenient
+ * when using memory debugging tools.
+ */
 export declare const init: () => void;
+/**
+ * Simplified version of [func@scheduler_add_full].
+ * @param callback - the callback to execute
+ * @param userData - user data for @callback
+ */
 export declare const schedulerAdd: (callback: (...args: unknown[]) => unknown, userData?: number | null) => number;
+/**
+ * Adds a new callback that will be executed as time permits on the main thread.
+ *
+ * This is useful when you need to do a lot of background work but want to do
+ * it incrementally.
+ *
+ * `callback` will be provided a deadline that it should complete it's work by
+ * (or near) and can be checked using [func@GLib.get_monotonic_time] for comparison.
+ *
+ * Use [func@scheduler_remove] to remove the handler.
+ * @param callback - the callback to execute
+ * @param userData - user data for @callback
+ * @param notify - closure notify for @user_data
+ */
 export declare const schedulerAddFull: (callback: (...args: unknown[]) => unknown, notify: () => void, userData?: number | null) => number;
+/**
+ * Removes a scheduler callback previously registered with
+ * [func@scheduler_add] or [func@scheduler_add_full].
+ * @param handlerId - the handler id
+ */
 export declare const schedulerRemove: (handlerId: number) => void;
+/**
+ * Use this function to escape the following characters: `\n`, `\r`, `\t` and `\`.
+ *
+ * For a regular expression search, use g_regex_escape_string() instead.
+ *
+ * One possible use case is to take the #GtkTextBuffer's selection and put it in a
+ * search entry. The selection can contain tabulations, newlines, etc. So it's
+ * better to escape those special characters to better fit in the search entry.
+ *
+ * See also: [func@utils_unescape_search_text].
+ *
+ * <warning>
+ * Warning: the escape and unescape functions are not reciprocal! For example,
+ * escape (unescape (\)) = \\. So avoid cycles such as: search entry -> unescape
+ * -> search settings -> escape -> search entry. The original search entry text
+ * may be modified.
+ * </warning>
+ * @param text - the text to escape.
+ */
 export declare const utilsEscapeSearchText: (text: string) => string;
+/**
+ * Use this function before [method@SearchSettings.set_search_text], to
+ * unescape the following sequences of characters: `\n`, `\r`, `\t` and `\\`.
+ * The purpose is to easily write those characters in a search entry.
+ *
+ * Note that unescaping the search text is not needed for regular expression
+ * searches.
+ *
+ * See also: [func@utils_escape_search_text].
+ * @param text - the text to unescape.
+ */
 export declare const utilsUnescapeSearchText: (text: string) => string;