@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtksource/snippet-chunk.js

@@ -2,7 +2,19 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SnippetContext } from "./snippet-context.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A chunk of text within the source snippet.
+ *
+ * The `GtkSourceSnippetChunk` represents a single chunk of text that
+ * may or may not be an edit point within the snippet. Chunks that are
+ * an edit point (also called a tab stop) have the
+ * [property@SnippetChunk:focus-position] property set.
+ */
 export class SnippetChunk extends GObject.InitiallyUnowned {
+    /**
+     * Create a new `GtkSourceSnippetChunk` that can be added to
+     * a [class@Snippet].
+     */
     constructor(...args) {
         super(...args);
     }
@@ -12,6 +24,9 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             borrowed: true,
         });
     }
+    /**
+     * Copies the source snippet.
+     */
     copy() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_copy", [
             {
@@ -21,6 +36,9 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SnippetChunk);
     }
+    /**
+     * Gets the context for the snippet insertion.
+     */
     getContext() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_get_context", [
             {
@@ -30,6 +48,17 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SnippetContext);
     }
+    /**
+     * Gets the [property@SnippetChunk:focus-position].
+     *
+     * The focus-position is used to determine how many tabs it takes for the
+     * snippet to advanced to this chunk.
+     *
+     * A focus-position of zero will be the last focus position of the snippet
+     * and snippet editing ends when it has been reached.
+     *
+     * A focus-position of -1 means the chunk cannot be focused by the user.
+     */
     getFocusPosition() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_get_focus_position", [
             {
@@ -38,6 +67,14 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the specification for the chunk.
+     *
+     * The specification is evaluated for variables when other chunks are edited
+     * within the snippet context. If the user has changed the text, the
+     * [property@SnippetChunk:text] and [property@SnippetChunk:text-set] properties
+     * are updated.
+     */
     getSpec() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_get_spec", [
             {
@@ -46,6 +83,13 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the [property@SnippetChunk:text] property.
+     *
+     * The text property is updated when the user edits the text of the chunk.
+     * If it has not been edited, the [property@SnippetChunk:spec] property is
+     * returned.
+     */
     getText() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_get_text", [
             {
@@ -54,6 +98,11 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the [property@SnippetChunk:text-set] property.
+     *
+     * This is typically set when the user has edited a snippet chunk.
+     */
     getTextSet() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_get_text_set", [
             {
@@ -82,6 +131,18 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the [property@SnippetChunk:focus-position] property.
+     *
+     * The focus-position is used to determine how many tabs it takes for the
+     * snippet to advanced to this chunk.
+     *
+     * A focus-position of zero will be the last focus position of the snippet
+     * and snippet editing ends when it has been reached.
+     *
+     * A focus-position of -1 means the chunk cannot be focused by the user.
+     * @param focusPosition - the focus-position
+     */
     setFocusPosition(focusPosition) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_set_focus_position", [
             {
@@ -94,6 +155,15 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the specification for the chunk.
+     *
+     * The specification is evaluated for variables when other chunks are edited
+     * within the snippet context. If the user has changed the text, the
+     * [property@SnippetChunk:text and] [property@SnippetChunk:text-set] properties
+     * are updated.
+     * @param spec - the new specification for the chunk
+     */
     setSpec(spec) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_set_spec", [
             {
@@ -106,6 +176,14 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the text for the snippet chunk.
+     *
+     * This is usually used by the snippet engine to update the text, but may
+     * be useful when creating custom snippets to avoid expansion of any
+     * specification.
+     * @param text - the text of the property
+     */
     setText(text) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_set_text", [
             {
@@ -118,6 +196,13 @@ export class SnippetChunk extends GObject.InitiallyUnowned {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the [property@SnippetChunk:text-set] property.
+     *
+     * This is typically set when the user has edited a snippet chunk by the
+     * snippet engine.
+     * @param textSet - the property value
+     */
     setTextSet(textSet) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_chunk_set_text_set", [
             {

package/dist/generated/gtksource/snippet-context.d.ts

@@ -1,14 +1,45 @@
 import * as GObject from "../gobject/index.js";
 export declare class SnippetContext extends GObject.GObject {
+    /**
+     * Creates a new #GtkSourceSnippetContext.
+     *
+     * Generally, this isn't needed unless you are controlling the
+     * expansion of snippets manually.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Removes all variables from the context.
+     */
     clearVariables(): void;
     expand(input: string): string;
+    /**
+     * Gets the current value for a variable named @key.
+     * @param key - the name of the variable
+     */
     getVariable(key: string): string | null;
+    /**
+     * Sets a constatnt within the context.
+     *
+     * This is similar to a variable set with [method@SnippetContext.set_variable]
+     * but is expected to not change during use of the snippet.
+     *
+     * Examples would be the date or users name.
+     * @param key - the constant name
+     * @param value - the value of the constant
+     */
     setConstant(key: string, value: string): void;
     setLinePrefix(linePrefix: string): void;
     setTabWidth(tabWidth: number): void;
     setUseSpaces(useSpaces: boolean): void;
+    /**
+     * Sets a variable within the context.
+     *
+     * This variable may be overridden by future updates to the
+     * context.
+     * @param key - the variable name
+     * @param value - the value for the variable
+     */
     setVariable(key: string, value: string): void;
     connect(signal: "changed", handler: (self: SnippetContext) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: SnippetContext, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gtksource/snippet-context.js

@@ -1,16 +1,36 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Context for expanding [class@SnippetChunk].
+ *
+ * This class is currently used primary as a hashtable. However, the longer
+ * term goal is to have it hold onto a `GjsContext` as well as other languages
+ * so that [class@SnippetChunk] can expand themselves by executing
+ * script within the context.
+ *
+ * The [class@Snippet] will build the context and then expand each of the
+ * chunks during the insertion/edit phase.
+ */
 const SIGNAL_META = {
     changed: { params: [], returnType: { type: "undefined" } },
 };
 export class SnippetContext extends GObject.GObject {
+    /**
+     * Creates a new #GtkSourceSnippetContext.
+     *
+     * Generally, this isn't needed unless you are controlling the
+     * expansion of snippets manually.
+     */
     constructor(...args) {
         super(...args);
     }
     createPtr(_args) {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_context_new", [], { type: "gobject", borrowed: false });
     }
+    /**
+     * Removes all variables from the context.
+     */
     clearVariables() {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_context_clear_variables", [
             {
@@ -31,6 +51,10 @@ export class SnippetContext extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Gets the current value for a variable named @key.
+     * @param key - the name of the variable
+     */
     getVariable(key) {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_context_get_variable", [
             {
@@ -43,6 +67,16 @@ export class SnippetContext extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Sets a constatnt within the context.
+     *
+     * This is similar to a variable set with [method@SnippetContext.set_variable]
+     * but is expected to not change during use of the snippet.
+     *
+     * Examples would be the date or users name.
+     * @param key - the constant name
+     * @param value - the value of the constant
+     */
     setConstant(key, value) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_context_set_constant", [
             {
@@ -95,6 +129,14 @@ export class SnippetContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets a variable within the context.
+     *
+     * This variable may be overridden by future updates to the
+     * context.
+     * @param key - the variable name
+     * @param value - the value for the variable
+     */
     setVariable(key, value) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_context_set_variable", [
             {

package/dist/generated/gtksource/snippet-manager.d.ts

@@ -1,15 +1,80 @@
 import { Snippet } from "./snippet.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Provides access to [class@Snippet].
+ *
+ * `GtkSourceSnippetManager` is an object which processes snippet description
+ * files and creates [class@Snippet] objects.
+ *
+ * Use [func@SnippetManager.get_default] to retrieve the default
+ * instance of `GtkSourceSnippetManager`.
+ *
+ * Use [method@SnippetManager.get_snippet] to retrieve snippets for
+ * a given snippets.
+ */
 export declare class SnippetManager extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns the default #GtkSourceSnippetManager instance.
+     */
     static getDefault(): SnippetManager;
+    /**
+     * Gets the list directories where `self` looks for snippet files.
+     */
     getSearchPath(): string[];
+    /**
+     * Queries the known snippets for the first matching @group, @language_id,
+     * and/or @trigger.
+     *
+     * If `group` or `language_id` are %NULL, they will be ignored.
+     * @param group - a group name or %NULL
+     * @param languageId - a #GtkSourceLanguage:id or %NULL
+     * @param trigger - the trigger for the snippet
+     */
     getSnippet(trigger: string, group?: string | null, languageId?: string | null): Snippet | null;
+    /**
+     * Gets a [iface@Gio.ListModel] of all snippets.
+     *
+     * This can be used to get an unfiltered list of all of the snippets
+     * known to the snippet manager.
+     */
     listAll(): Gio.ListModel;
+    /**
+     * List all the known groups within the snippet manager.
+     *
+     * The result should be freed with g_free(), and the individual strings are
+     * owned by `self` and should never be freed by the caller.
+     */
     listGroups(): string[];
+    /**
+     * Queries the known snippets for those matching @group, @language_id, and/or
+     * @trigger_prefix.
+     *
+     * If any of these are %NULL, they will be ignored when filtering the available snippets.
+     *
+     * The [iface@Gio.ListModel] only contains information about the available snippets until
+     * [method@Gio.ListModel.get_item] is called for a specific snippet. This helps reduce
+     * the number of [class@GObject.Object]'s that are created at runtime to those needed by
+     * the calling application.
+     * @param group - a group name or %NULL
+     * @param languageId - a #GtkSourceLanguage:id or %NULL
+     * @param triggerPrefix - a prefix for a trigger to activate
+     */
     listMatching(group?: string | null, languageId?: string | null, triggerPrefix?: string | null): Gio.ListModel;
+    /**
+     * Sets the list of directories in which the `GtkSourceSnippetManager` looks for
+     * snippet files.
+     *
+     * If `dirs` is %NULL, the search path is reset to default.
+     *
+     * At the moment this function can be called only before the
+     * snippet files are loaded for the first time. In practice
+     * to set a custom search path for a `GtkSourceSnippetManager`,
+     * you have to call this function right after creating it.
+     * @param dirs - a %NULL-terminated array of
+     */
     setSearchPath(dirs?: string[] | null): void;
     connect(signal: "notify", handler: (self: SnippetManager, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtksource/snippet-manager.js

@@ -3,6 +3,18 @@ import { getObject } from "@gtkx/ffi";
 import { Snippet } from "./snippet.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Provides access to [class@Snippet].
+ *
+ * `GtkSourceSnippetManager` is an object which processes snippet description
+ * files and creates [class@Snippet] objects.
+ *
+ * Use [func@SnippetManager.get_default] to retrieve the default
+ * instance of `GtkSourceSnippetManager`.
+ *
+ * Use [method@SnippetManager.get_snippet] to retrieve snippets for
+ * a given snippets.
+ */
 export class SnippetManager extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -14,10 +26,16 @@ export class SnippetManager extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Returns the default #GtkSourceSnippetManager instance.
+     */
     static getDefault() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_get_default", [], { type: "gobject", borrowed: true });
         return getObject(ptr, SnippetManager);
     }
+    /**
+     * Gets the list directories where `self` looks for snippet files.
+     */
     getSearchPath() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_get_search_path", [
             {
@@ -26,6 +44,15 @@ export class SnippetManager extends GObject.GObject {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Queries the known snippets for the first matching @group, @language_id,
+     * and/or @trigger.
+     *
+     * If `group` or `language_id` are %NULL, they will be ignored.
+     * @param group - a group name or %NULL
+     * @param languageId - a #GtkSourceLanguage:id or %NULL
+     * @param trigger - the trigger for the snippet
+     */
     getSnippet(trigger, group, languageId) {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_get_snippet", [
             {
@@ -51,6 +78,12 @@ export class SnippetManager extends GObject.GObject {
             return null;
         return getObject(ptr, Snippet);
     }
+    /**
+     * Gets a [iface@Gio.ListModel] of all snippets.
+     *
+     * This can be used to get an unfiltered list of all of the snippets
+     * known to the snippet manager.
+     */
     listAll() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_list_all", [
             {
@@ -60,6 +93,12 @@ export class SnippetManager extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Gio.ListModel);
     }
+    /**
+     * List all the known groups within the snippet manager.
+     *
+     * The result should be freed with g_free(), and the individual strings are
+     * owned by `self` and should never be freed by the caller.
+     */
     listGroups() {
         return call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_list_groups", [
             {
@@ -68,6 +107,20 @@ export class SnippetManager extends GObject.GObject {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Queries the known snippets for those matching @group, @language_id, and/or
+     * @trigger_prefix.
+     *
+     * If any of these are %NULL, they will be ignored when filtering the available snippets.
+     *
+     * The [iface@Gio.ListModel] only contains information about the available snippets until
+     * [method@Gio.ListModel.get_item] is called for a specific snippet. This helps reduce
+     * the number of [class@GObject.Object]'s that are created at runtime to those needed by
+     * the calling application.
+     * @param group - a group name or %NULL
+     * @param languageId - a #GtkSourceLanguage:id or %NULL
+     * @param triggerPrefix - a prefix for a trigger to activate
+     */
     listMatching(group, languageId, triggerPrefix) {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_list_matching", [
             {
@@ -92,6 +145,18 @@ export class SnippetManager extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Gio.ListModel);
     }
+    /**
+     * Sets the list of directories in which the `GtkSourceSnippetManager` looks for
+     * snippet files.
+     *
+     * If `dirs` is %NULL, the search path is reset to default.
+     *
+     * At the moment this function can be called only before the
+     * snippet files are loaded for the first time. In practice
+     * to set a custom search path for a `GtkSourceSnippetManager`,
+     * you have to call this function right after creating it.
+     * @param dirs - a %NULL-terminated array of
+     */
     setSearchPath(dirs) {
         call("libgtksourceview-5.so.0", "gtk_source_snippet_manager_set_search_path", [
             {

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

@@ -1,24 +1,110 @@
 import { SnippetChunk } from "./snippet-chunk.js";
 import { SnippetContext } from "./snippet-context.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Quick insertion code snippets.
+ *
+ * The `GtkSourceSnippet` represents a series of chunks that can quickly be
+ * inserted into the [class@View].
+ *
+ * Snippets are defined in XML files which are loaded by the
+ * [class@SnippetManager]. Alternatively, applications can create snippets
+ * on demand and insert them into the [class@View] using
+ * [method@View.push_snippet].
+ *
+ * Snippet chunks can reference other snippet chunks as well as post-process
+ * the values from other chunks such as capitalization.
+ */
 export declare class Snippet extends GObject.GObject {
+    /**
+     * Creates a new #GtkSourceSnippet
+     * @param trigger - the trigger word
+     * @param languageId - the source language
+     */
     constructor(trigger?: string | null, languageId?: string | null);
     constructor(...args: unknown[]);
+    /**
+     * Parses the snippet formatted `text` into a series of chunks and adds them
+     * to a new #GtkSourceSnippet.
+     * @param text - the formatted snippet text to parse
+     */
     static snippetNewParsed(text: string): Snippet;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Appends `chunk` to the @snippet.
+     *
+     * This may only be called before the snippet has been expanded.
+     * @param chunk - a #GtkSourceSnippetChunk
+     */
     addChunk(chunk: SnippetChunk): void;
+    /**
+     * Does a deep copy of the snippet.
+     */
     copy(): Snippet;
+    /**
+     * Gets the context used for expanding the snippet.
+     */
     getContext(): SnippetContext | null;
+    /**
+     * Gets the description for the snippet.
+     */
     getDescription(): string;
+    /**
+     * Gets the current focus for the snippet.
+     *
+     * This is changed as the user tabs through focus locations.
+     */
     getFocusPosition(): number;
+    /**
+     * Gets the language-id used for the source snippet.
+     *
+     * The language identifier should be one that matches a
+     * source language [property@Language:id] property.
+     */
     getLanguageId(): string;
+    /**
+     * Gets the number of chunks in the snippet.
+     *
+     * Note that not all chunks are editable.
+     */
     getNChunks(): number;
+    /**
+     * Gets the name for the snippet.
+     */
     getName(): string;
+    /**
+     * Gets the chunk at @nth.
+     * @param nth - the nth chunk to get
+     */
     getNthChunk(nth: number): SnippetChunk;
+    /**
+     * Gets the trigger for the source snippet.
+     *
+     * A trigger is a word that can be expanded into the full snippet when
+     * the user presses Tab.
+     */
     getTrigger(): string | null;
+    /**
+     * Sets the description for the snippet.
+     * @param description - the snippet description
+     */
     setDescription(description: string): void;
+    /**
+     * Sets the language identifier for the snippet.
+     *
+     * This should match the [property@Language:id] identifier.
+     * @param languageId - the language identifier for the snippet
+     */
     setLanguageId(languageId: string): void;
+    /**
+     * Sets the name for the snippet.
+     * @param name - the snippet name
+     */
     setName(name: string): void;
+    /**
+     * Sets the trigger for the snippet.
+     * @param trigger - the trigger word
+     */
     setTrigger(trigger: string): void;
     connect(signal: "notify", handler: (self: Snippet, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;