@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -5,6 +5,61 @@ import { SearchSettings } from "./search-settings.js";
 import { Style } from "./style.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Search context.
+ *
+ * A `GtkSourceSearchContext` is used for the search and replace in a
+ * [class@Buffer]. The search settings are represented by a
+ * [class@SearchSettings] object. There can be a many-to-many relationship
+ * between buffers and search settings, with the search contexts in-between: a
+ * search settings object can be shared between several search contexts; and a
+ * buffer can contain several search contexts at the same time.
+ *
+ * The total number of search occurrences can be retrieved with
+ * [method@SearchContext.get_occurrences_count]. To know the position of a
+ * certain match, use [method@SearchContext.get_occurrence_position].
+ *
+ * The buffer is scanned asynchronously, so it doesn't block the user interface.
+ * For each search, the buffer is scanned at most once. After that, navigating
+ * through the occurrences doesn't require to re-scan the buffer entirely.
+ *
+ * To search forward, use [method@SearchContext.forward] or
+ * [method@SearchContext.forward_async] for the asynchronous version.
+ * The backward search is done similarly. To replace a search match, or all
+ * matches, use [method@SearchContext.replace] and
+ * [method@SearchContext.replace_all].
+ *
+ * The search occurrences are highlighted by default. To disable it, use
+ * [method@SearchContext.set_highlight]. You can enable the search
+ * highlighting for several `GtkSourceSearchContext`s attached to the
+ * same buffer. Moreover, each of those `GtkSourceSearchContext`s can
+ * have a different text style associated. Use
+ * [method@SearchContext.set_match_style] to specify the [class@Style]
+ * to apply on search matches.
+ *
+ * Note that the [property@SearchContext:highlight] and
+ * [property@SearchContext:match-style] properties are in the
+ * `GtkSourceSearchContext` class, not [class@SearchSettings]. Appearance
+ * settings should be tied to one, and only one buffer, as different buffers can
+ * have different style scheme associated (a [class@SearchSettings] object
+ * can be bound indirectly to several buffers).
+ *
+ * The concept of "current match" doesn't exist yet. A way to highlight
+ * differently the current match is to select it.
+ *
+ * A search occurrence's position doesn't depend on the cursor position or other
+ * parameters. Take for instance the buffer "aaaa" with the search text "aa".
+ * The two occurrences are at positions [0:2] and [2:4]. If you begin to search
+ * at position 1, you will get the occurrence [2:4], not [1:3]. This is a
+ * prerequisite for regular expression searches. The pattern ".*" matches the
+ * entire line. If the cursor is at the middle of the line, you don't want the
+ * rest of the line as the occurrence, you want an entire line. (As a side note,
+ * regular expression searches can also match multiple lines.)
+ *
+ * In the GtkSourceView source code, there is an example of how to use the
+ * search and replace API: see the tests/test-search.c file. It is a mini
+ * application for the search and replace, with a basic user interface.
+ */
 export class SearchContext extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -23,6 +78,23 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Synchronous backward search.
+     *
+     * It is recommended to use the asynchronous functions instead, to not block the user interface.
+     * However, if you are sure that the `buffer` is small, this function is more convenient to use.
+     *
+     * If the [property@SearchSettings:wrap-around] property is %FALSE, this function
+     * doesn't try to wrap around.
+     *
+     * The `has_wrapped_around` out parameter is set independently of whether a match
+     * is found. So if this function returns %FALSE, `has_wrapped_around` will have
+     * the same value as the [property@SearchSettings:wrap-around] property.
+     * @param iter - start of search.
+     * @param matchStart - return location for start of match, or %NULL.
+     * @param matchEnd - return location for end of match, or %NULL.
+     * @param hasWrappedAround - return location to know whether the
+     */
     backward(iter, matchStart, matchEnd, hasWrappedAround) {
         return call("libgtksourceview-5.so.0", "gtk_source_search_context_backward", [
             {
@@ -69,6 +141,17 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Finishes a backward search started with
+     * [method@SearchContext.backward_async].
+     *
+     * See the documentation of [method@SearchContext.backward] for more
+     * details.
+     * @param result - a #GAsyncResult.
+     * @param matchStart - return location for start of match, or %NULL.
+     * @param matchEnd - return location for end of match, or %NULL.
+     * @param hasWrappedAround - return location to know whether the
+     */
     backwardFinish(result, matchStart, matchEnd, hasWrappedAround) {
         const error = { value: null };
         const _result = call("libgtksourceview-5.so.0", "gtk_source_search_context_backward_finish", [
@@ -126,6 +209,23 @@ export class SearchContext extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Synchronous forward search.
+     *
+     * It is recommended to use the asynchronous functions instead, to not block the user interface.
+     * However, if you are sure that the `buffer` is small, this function is more convenient to use.
+     *
+     * If the [property@SearchSettings:wrap-around] property is %FALSE, this function
+     * doesn't try to wrap around.
+     *
+     * The `has_wrapped_around` out parameter is set independently of whether a match
+     * is found. So if this function returns %FALSE, `has_wrapped_around` will have
+     * the same value as the  [property@SearchSettings:wrap-around] property.
+     * @param iter - start of search.
+     * @param matchStart - return location for start of match, or %NULL.
+     * @param matchEnd - return location for end of match, or %NULL.
+     * @param hasWrappedAround - return location to know whether the
+     */
     forward(iter, matchStart, matchEnd, hasWrappedAround) {
         return call("libgtksourceview-5.so.0", "gtk_source_search_context_forward", [
             {
@@ -172,6 +272,16 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Finishes a forward search started with [method@SearchContext.forward_async].
+     *
+     * See the documentation of [method@SearchContext.forward] for more
+     * details.
+     * @param result - a #GAsyncResult.
+     * @param matchStart - return location for start of match, or %NULL.
+     * @param matchEnd - return location for end of match, or %NULL.
+     * @param hasWrappedAround - return location to know whether the
+     */
     forwardFinish(result, matchStart, matchEnd, hasWrappedAround) {
         const error = { value: null };
         const _result = call("libgtksourceview-5.so.0", "gtk_source_search_context_forward_finish", [
@@ -255,6 +365,15 @@ export class SearchContext extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Style);
     }
+    /**
+     * Gets the position of a search occurrence.
+     *
+     * If the buffer is not already fully scanned, the position may be unknown,
+     * and -1 is returned. If 0 is returned, it means that this part of the buffer
+     * has already been scanned, and that `match_start` and `match_end` don't delimit an occurrence.
+     * @param matchStart - the start of the occurrence.
+     * @param matchEnd - the end of the occurrence.
+     */
     getOccurrencePosition(matchStart, matchEnd) {
         return call("libgtksourceview-5.so.0", "gtk_source_search_context_get_occurrence_position", [
             {
@@ -281,6 +400,12 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the total number of search occurrences.
+     *
+     * If the buffer is not already fully scanned, the total number of occurrences is
+     * unknown, and -1 is returned.
+     */
     getOccurrencesCount() {
         return call("libgtksourceview-5.so.0", "gtk_source_search_context_get_occurrences_count", [
             {
@@ -289,6 +414,15 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Regular expression patterns must follow certain rules. If
+     * [property@SearchSettings:search-text] breaks a rule, the error can be
+     * retrieved with this function.
+     *
+     * The error domain is [error@GLib.RegexError].
+     *
+     * Free the return value with [method@GLib.Error.free].
+     */
     getRegexError() {
         const ptr = call("libgtksourceview-5.so.0", "gtk_source_search_context_get_regex_error", [
             {
@@ -314,6 +448,20 @@ export class SearchContext extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SearchSettings);
     }
+    /**
+     * Replaces a search match by another text. If `match_start` and `match_end` doesn't correspond to a search match, %FALSE is returned.
+     *
+     * `match_start` and `match_end` iters are revalidated to point to the replacement
+     * text boundaries.
+     *
+     * For a regular expression replacement, you can check if `replace` is valid by
+     * calling [func@GLib.Regex.check_replacement]. The `replace` text can contain
+     * backreferences.
+     * @param matchStart - the start of the match to replace.
+     * @param matchEnd - the end of the match to replace.
+     * @param replace - the replacement text.
+     * @param replaceLength - the length of `replace` in bytes, or -1.
+     */
     replace(matchStart, matchEnd, replace, replaceLength) {
         const error = { value: null };
         const result = call("libgtksourceview-5.so.0", "gtk_source_search_context_replace", [
@@ -364,6 +512,17 @@ export class SearchContext extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Replaces all search matches by another text.
+     *
+     * It is a synchronous function, so it can block the user interface.
+     *
+     * For a regular expression replacement, you can check if `replace` is valid by
+     * calling [func@GLib.Regex.check_replacement]. The `replace` text can contain
+     * backreferences.
+     * @param replace - the replacement text.
+     * @param replaceLength - the length of `replace` in bytes, or -1.
+     */
     replaceAll(replace, replaceLength) {
         const error = { value: null };
         const result = call("libgtksourceview-5.so.0", "gtk_source_search_context_replace_all", [
@@ -396,6 +555,10 @@ export class SearchContext extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Enables or disables the search occurrences highlighting.
+     * @param highlight - the setting.
+     */
     setHighlight(highlight) {
         call("libgtksourceview-5.so.0", "gtk_source_search_context_set_highlight", [
             {
@@ -408,6 +571,13 @@ export class SearchContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Set the style to apply on search matches.
+     *
+     * If `match_style` is %NULL, default theme's scheme 'match-style' will be used.
+     * To enable or disable the search highlighting, use [method@SearchContext.set_highlight].
+     * @param matchStyle - a #GtkSourceStyle, or %NULL.
+     */
     setMatchStyle(matchStyle) {
         call("libgtksourceview-5.so.0", "gtk_source_search_context_set_match_style", [
             {

package/dist/generated/gtksource/search-settings.d.ts

@@ -1,18 +1,83 @@
 import * as GObject from "../gobject/index.js";
+/**
+ * Search settings.
+ *
+ * A `GtkSourceSearchSettings` object represents the settings of a search. The
+ * search settings can be associated with one or several
+ * [class@SearchContext]s.
+ */
 export declare class SearchSettings extends GObject.GObject {
+    /**
+     * Creates a new search settings object.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
     getAtWordBoundaries(): boolean;
     getCaseSensitive(): boolean;
     getRegexEnabled(): boolean;
+    /**
+     * Gets the text to search.
+     *
+     * The return value must not be freed.
+     *
+     * You may be interested to call [func@utils_escape_search_text] after
+     * this function.
+     */
     getSearchText(): string | null;
     getVisibleOnly(): boolean;
     getWrapAround(): boolean;
+    /**
+     * Change whether the search is done at word boundaries.
+     *
+     * If `at_word_boundaries` is %TRUE, a search match must start and end a word.
+     * The match can span multiple words. See also [method@Gtk.TextIter.starts_word] and
+     * [method@Gtk.TextIter.ends_word].
+     * @param atWordBoundaries - the setting.
+     */
     setAtWordBoundaries(atWordBoundaries: boolean): void;
+    /**
+     * Enables or disables the case sensitivity for the search.
+     * @param caseSensitive - the setting.
+     */
     setCaseSensitive(caseSensitive: boolean): void;
+    /**
+     * Enables or disables whether to search by regular expressions.
+     *
+     * If enabled, the [property@SearchSettings:search-text] property contains the
+     * pattern of the regular expression.
+     *
+     * [class@SearchContext] uses #GRegex when regex search is enabled. See the
+     * Regular expression syntax
+     * page in the GLib reference manual.
+     * @param regexEnabled - the setting.
+     */
     setRegexEnabled(regexEnabled: boolean): void;
+    /**
+     * Sets the text to search.
+     *
+     * If `search_text` is %NULL or is empty, the search will be disabled. A copy of `search_text` will be made, so you can safely free `search_text` after a call to this function.
+     *
+     * You may be interested to call [func@utils_unescape_search_text] before
+     * this function.
+     * @param searchText - the nul-terminated text to search, or %NULL to disable the search.
+     */
     setSearchText(searchText?: string | null): void;
+    /**
+     * Enables or disables whether to exclude invisible text from the search.
+     *
+     * If enabled, only visible text will be searched.
+     * A search match may have invisible text interspersed.
+     * @param visibleOnly - the setting.
+     */
     setVisibleOnly(visibleOnly: boolean): void;
+    /**
+     * Enables or disables the wrap around search.
+     *
+     * If `wrap_around` is %TRUE, the forward search continues at the beginning of the buffer
+     * if no search occurrences are found. Similarly, the backward search continues to search at
+     * the end of the buffer.
+     * @param wrapAround - the setting.
+     */
     setWrapAround(wrapAround: boolean): void;
     connect(signal: "notify", handler: (self: SearchSettings, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtksource/search-settings.js

@@ -1,7 +1,17 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Search settings.
+ *
+ * A `GtkSourceSearchSettings` object represents the settings of a search. The
+ * search settings can be associated with one or several
+ * [class@SearchContext]s.
+ */
 export class SearchSettings extends GObject.GObject {
+    /**
+     * Creates a new search settings object.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -32,6 +42,14 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the text to search.
+     *
+     * The return value must not be freed.
+     *
+     * You may be interested to call [func@utils_escape_search_text] after
+     * this function.
+     */
     getSearchText() {
         return call("libgtksourceview-5.so.0", "gtk_source_search_settings_get_search_text", [
             {
@@ -56,6 +74,14 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Change whether the search is done at word boundaries.
+     *
+     * If `at_word_boundaries` is %TRUE, a search match must start and end a word.
+     * The match can span multiple words. See also [method@Gtk.TextIter.starts_word] and
+     * [method@Gtk.TextIter.ends_word].
+     * @param atWordBoundaries - the setting.
+     */
     setAtWordBoundaries(atWordBoundaries) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_at_word_boundaries", [
             {
@@ -68,6 +94,10 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Enables or disables the case sensitivity for the search.
+     * @param caseSensitive - the setting.
+     */
     setCaseSensitive(caseSensitive) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_case_sensitive", [
             {
@@ -80,6 +110,17 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Enables or disables whether to search by regular expressions.
+     *
+     * If enabled, the [property@SearchSettings:search-text] property contains the
+     * pattern of the regular expression.
+     *
+     * [class@SearchContext] uses #GRegex when regex search is enabled. See the
+     * Regular expression syntax
+     * page in the GLib reference manual.
+     * @param regexEnabled - the setting.
+     */
     setRegexEnabled(regexEnabled) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_regex_enabled", [
             {
@@ -92,6 +133,15 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the text to search.
+     *
+     * If `search_text` is %NULL or is empty, the search will be disabled. A copy of `search_text` will be made, so you can safely free `search_text` after a call to this function.
+     *
+     * You may be interested to call [func@utils_unescape_search_text] before
+     * this function.
+     * @param searchText - the nul-terminated text to search, or %NULL to disable the search.
+     */
     setSearchText(searchText) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_search_text", [
             {
@@ -105,6 +155,13 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Enables or disables whether to exclude invisible text from the search.
+     *
+     * If enabled, only visible text will be searched.
+     * A search match may have invisible text interspersed.
+     * @param visibleOnly - the setting.
+     */
     setVisibleOnly(visibleOnly) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_visible_only", [
             {
@@ -117,6 +174,14 @@ export class SearchSettings extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Enables or disables the wrap around search.
+     *
+     * If `wrap_around` is %TRUE, the forward search continues at the beginning of the buffer
+     * if no search occurrences are found. Similarly, the backward search continues to search at
+     * the end of the buffer.
+     * @param wrapAround - the setting.
+     */
     setWrapAround(wrapAround) {
         call("libgtksourceview-5.so.0", "gtk_source_search_settings_set_wrap_around", [
             {

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

@@ -1,19 +1,104 @@
 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 declare class SnippetChunk extends GObject.InitiallyUnowned {
+    /**
+     * Create a new `GtkSourceSnippetChunk` that can be added to
+     * a [class@Snippet].
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Copies the source snippet.
+     */
     copy(): SnippetChunk;
+    /**
+     * Gets the context for the snippet insertion.
+     */
     getContext(): 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(): number;
+    /**
+     * 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(): string | null;
+    /**
+     * 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(): string;
+    /**
+     * Gets the [property@SnippetChunk:text-set] property.
+     *
+     * This is typically set when the user has edited a snippet chunk.
+     */
     getTextSet(): boolean;
     getTooltipText(): string;
     setContext(context: SnippetContext): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: boolean): void;
     setTooltipText(tooltipText: string): void;
     connect(signal: "notify", handler: (self: SnippetChunk, pspec: GObject.ParamSpec) => void, after?: boolean): number;