@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/gesture.js

@@ -2,6 +2,97 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as Gdk from "../gdk/index.js";
 import { EventController } from "./event-controller.js";
+/**
+ * The base class for gesture recognition.
+ *
+ * Although `GtkGesture` is quite generalized to serve as a base for
+ * multi-touch gestures, it is suitable to implement single-touch and
+ * pointer-based gestures (using the special %NULL `GdkEventSequence`
+ * value for these).
+ *
+ * The number of touches that a `GtkGesture` need to be recognized is
+ * controlled by the [property@Gtk.Gesture:n-points] property, if a
+ * gesture is keeping track of less or more than that number of sequences,
+ * it won't check whether the gesture is recognized.
+ *
+ * As soon as the gesture has the expected number of touches, it will check
+ * regularly if it is recognized, the criteria to consider a gesture as
+ * "recognized" is left to `GtkGesture` subclasses.
+ *
+ * A recognized gesture will then emit the following signals:
+ *
+ * - [signal@Gtk.Gesture::begin] when the gesture is recognized.
+ * - [signal@Gtk.Gesture::update], whenever an input event is processed.
+ * - [signal@Gtk.Gesture::end] when the gesture is no longer recognized.
+ *
+ * ## Event propagation
+ *
+ * In order to receive events, a gesture needs to set a propagation phase
+ * through [method@Gtk.EventController.set_propagation_phase].
+ *
+ * In the capture phase, events are propagated from the toplevel down
+ * to the target widget, and gestures that are attached to containers
+ * above the widget get a chance to interact with the event before it
+ * reaches the target.
+ *
+ * In the bubble phase, events are propagated up from the target widget
+ * to the toplevel, and gestures that are attached to containers above
+ * the widget get a chance to interact with events that have not been
+ * handled yet.
+ *
+ * ## States of a sequence
+ *
+ * Whenever input interaction happens, a single event may trigger a cascade
+ * of `GtkGesture`s, both across the parents of the widget receiving the
+ * event and in parallel within an individual widget. It is a responsibility
+ * of the widgets using those gestures to set the state of touch sequences
+ * accordingly in order to enable cooperation of gestures around the
+ * `GdkEventSequence`s triggering those.
+ *
+ * Within a widget, gestures can be grouped through [method@Gtk.Gesture.group].
+ * Grouped gestures synchronize the state of sequences, so calling
+ * [method@Gtk.Gesture.set_state] on one will effectively propagate
+ * the state throughout the group.
+ *
+ * By default, all sequences start out in the %GTK_EVENT_SEQUENCE_NONE state,
+ * sequences in this state trigger the gesture event handler, but event
+ * propagation will continue unstopped by gestures.
+ *
+ * If a sequence enters into the %GTK_EVENT_SEQUENCE_DENIED state, the gesture
+ * group will effectively ignore the sequence, letting events go unstopped
+ * through the gesture, but the "slot" will still remain occupied while
+ * the touch is active.
+ *
+ * If a sequence enters in the %GTK_EVENT_SEQUENCE_CLAIMED state, the gesture
+ * group will grab all interaction on the sequence, by:
+ *
+ * - Setting the same sequence to %GTK_EVENT_SEQUENCE_DENIED on every other
+ * gesture group within the widget, and every gesture on parent widgets
+ * in the propagation chain.
+ * - Emitting [signal@Gtk.Gesture::cancel] on every gesture in widgets
+ * underneath in the propagation chain.
+ * - Stopping event propagation after the gesture group handles the event.
+ *
+ * Note: if a sequence is set early to %GTK_EVENT_SEQUENCE_CLAIMED on
+ * %GDK_TOUCH_BEGIN/%GDK_BUTTON_PRESS (so those events are captured before
+ * reaching the event widget, this implies %GTK_PHASE_CAPTURE), one similar
+ * event will be emulated if the sequence changes to %GTK_EVENT_SEQUENCE_DENIED.
+ * This way event coherence is preserved before event propagation is unstopped
+ * again.
+ *
+ * Sequence states can't be changed freely.
+ * See [method@Gtk.Gesture.set_state] to know about the possible
+ * lifetimes of a `GdkEventSequence`.
+ *
+ * ## Touchpad gestures
+ *
+ * On the platforms that support it, `GtkGesture` will handle transparently
+ * touchpad gesture events. The only precautions users of `GtkGesture` should
+ * do to enable this support are:
+ *
+ * - If the gesture has %GTK_PHASE_NONE, ensuring events of type
+ * %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the `GtkGesture`
+ */
 const SIGNAL_META = {
     begin: {
         params: [
@@ -60,6 +151,20 @@ export class Gesture extends EventController {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * If there are touch sequences being currently handled by @gesture,
+     * returns %TRUE and fills in `rect` with the bounding box containing
+     * all active touches.
+     *
+     * Otherwise, %FALSE will be returned.
+     *
+     * Note: This function will yield unexpected results on touchpad
+     * gestures. Since there is no correlation between physical and
+     * pixel distances, these will look as if constrained in an
+     * infinitely small area, `rect` width and height will thus be 0
+     * regardless of the number of touchpoints.
+     * @param rect - bounding box containing all active touches.
+     */
     getBoundingBox(rect) {
         return call("libgtk-4.so.1", "gtk_gesture_get_bounding_box", [
             {
@@ -79,6 +184,15 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * If there are touch sequences being currently handled by @gesture,
+     * returns %TRUE and fills in `x` and `y` with the center of the bounding
+     * box containing all active touches.
+     *
+     * Otherwise, %FALSE will be returned.
+     * @param x - X coordinate for the bounding box center
+     * @param y - Y coordinate for the bounding box center
+     */
     getBoundingBoxCenter(x, y) {
         return call("libgtk-4.so.1", "gtk_gesture_get_bounding_box_center", [
             {
@@ -95,6 +209,12 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the logical `GdkDevice` that is currently operating
+     * on @gesture.
+     *
+     * This returns %NULL if the gesture is not being interacted.
+     */
     getDevice() {
         const ptr = call("libgtk-4.so.1", "gtk_gesture_get_device", [
             {
@@ -106,6 +226,9 @@ export class Gesture extends EventController {
             return null;
         return getObject(ptr, Gdk.Device);
     }
+    /**
+     * Returns all gestures in the group of @gesture
+     */
     getGroup() {
         const ptrs = call("libgtk-4.so.1", "gtk_gesture_get_group", [
             {
@@ -120,6 +243,14 @@ export class Gesture extends EventController {
         });
         return ptrs.map((ptr) => getObject(ptr, Gesture));
     }
+    /**
+     * Returns the last event that was processed for @sequence.
+     *
+     * Note that the returned pointer is only valid as long as the
+     * `sequence` is still interpreted by the @gesture. If in doubt,
+     * you should make a copy of the event.
+     * @param sequence - a `GdkEventSequence`
+     */
     getLastEvent(sequence) {
         const ptr = call("libgtk-4.so.1", "gtk_gesture_get_last_event", [
             {
@@ -141,6 +272,9 @@ export class Gesture extends EventController {
             return null;
         return getObject(ptr, Gdk.Event);
     }
+    /**
+     * Returns the `GdkEventSequence` that was last updated on @gesture.
+     */
     getLastUpdatedSequence() {
         const ptr = call("libgtk-4.so.1", "gtk_gesture_get_last_updated_sequence", [
             {
@@ -157,6 +291,16 @@ export class Gesture extends EventController {
             return null;
         return getObject(ptr, Gdk.EventSequence);
     }
+    /**
+     * If `sequence` is currently being interpreted by @gesture,
+     * returns %TRUE and fills in `x` and `y` with the last coordinates
+     * stored for that event sequence.
+     *
+     * The coordinates are always relative to the widget allocation.
+     * @param sequence - a `GdkEventSequence`, or %NULL for pointer events
+     * @param x - return location for X axis of the sequence coordinates
+     * @param y - return location for Y axis of the sequence coordinates
+     */
     getPoint(sequence, x, y) {
         return call("libgtk-4.so.1", "gtk_gesture_get_point", [
             {
@@ -185,6 +329,10 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the `sequence` state, as seen by @gesture.
+     * @param sequence - a `GdkEventSequence`
+     */
     getSequenceState(sequence) {
         return call("libgtk-4.so.1", "gtk_gesture_get_sequence_state", [
             {
@@ -202,6 +350,10 @@ export class Gesture extends EventController {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the list of `GdkEventSequences` currently being interpreted
+     * by @gesture.
+     */
     getSequences() {
         return call("libgtk-4.so.1", "gtk_gesture_get_sequences", [
             {
@@ -219,6 +371,26 @@ export class Gesture extends EventController {
             borrowed: true,
         });
     }
+    /**
+     * Adds `gesture` to the same group than @group_gesture.
+     *
+     * Gestures are by default isolated in their own groups.
+     *
+     * Both gestures must have been added to the same widget before
+     * they can be grouped.
+     *
+     * When gestures are grouped, the state of `GdkEventSequences`
+     * is kept in sync for all of those, so calling
+     * [method@Gtk.Gesture.set_sequence_state], on one will transfer
+     * the same value to the others.
+     *
+     * Groups also perform an "implicit grabbing" of sequences, if a
+     * `GdkEventSequence` state is set to %GTK_EVENT_SEQUENCE_CLAIMED
+     * on one group, every other gesture group attached to the same
+     * `GtkWidget` will switch the state for that sequence to
+     * %GTK_EVENT_SEQUENCE_DENIED.
+     * @param gesture - a `GtkGesture`
+     */
     group(gesture) {
         call("libgtk-4.so.1", "gtk_gesture_group", [
             {
@@ -231,6 +403,11 @@ export class Gesture extends EventController {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns %TRUE if `gesture` is currently handling events
+     * corresponding to @sequence.
+     * @param sequence - a `GdkEventSequence`
+     */
     handlesSequence(sequence) {
         return call("libgtk-4.so.1", "gtk_gesture_handles_sequence", [
             {
@@ -249,6 +426,12 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if the gesture is currently active.
+     *
+     * A gesture is active while there are touch sequences
+     * interacting with it.
+     */
     isActive() {
         return call("libgtk-4.so.1", "gtk_gesture_is_active", [
             {
@@ -257,6 +440,10 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if both gestures pertain to the same group.
+     * @param other - another `GtkGesture`
+     */
     isGroupedWith(other) {
         return call("libgtk-4.so.1", "gtk_gesture_is_grouped_with", [
             {
@@ -269,6 +456,12 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if the gesture is currently recognized.
+     *
+     * A gesture is recognized if there are as many interacting
+     * touch sequences as required by @gesture.
+     */
     isRecognized() {
         return call("libgtk-4.so.1", "gtk_gesture_is_recognized", [
             {
@@ -277,6 +470,52 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the state of `sequence` in @gesture.
+     *
+     * Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever
+     * they change state, they can never go back to that state. Likewise,
+     * sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to
+     * a not denied state. With these rules, the lifetime of an event
+     * sequence is constrained to the next four:
+     *
+     * * None
+     * * None → Denied
+     * * None → Claimed
+     * * None → Claimed → Denied
+     *
+     * Note: Due to event handling ordering, it may be unsafe to set the
+     * state on another gesture within a [signal@Gtk.Gesture::begin] signal
+     * handler, as the callback might be executed before the other gesture
+     * knows about the sequence. A safe way to perform this could be:
+     *
+     * ```c
+     * static void
+     * first_gesture_begin_cb (GtkGesture       *first_gesture,
+     * GdkEventSequence *sequence,
+     * gpointer          user_data)
+     * {
+     * gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED);
+     * gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+     * }
+     *
+     * static void
+     * second_gesture_begin_cb (GtkGesture       *second_gesture,
+     * GdkEventSequence *sequence,
+     * gpointer          user_data)
+     * {
+     * if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED)
+     * gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+     * }
+     * ```
+     *
+     * If both gestures are in the same group, just set the state on
+     * the gesture emitting the event, the sequence will be already
+     * be initialized to the group's global state when the second
+     * gesture processes the event.
+     * @param sequence - a `GdkEventSequence`
+     * @param state - the sequence state
+     */
     setSequenceState(sequence, state) {
         return call("libgtk-4.so.1", "gtk_gesture_set_sequence_state", [
             {
@@ -298,6 +537,52 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the state of all sequences that `gesture` is currently
+     * interacting with.
+     *
+     * Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever
+     * they change state, they can never go back to that state. Likewise,
+     * sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to
+     * a not denied state. With these rules, the lifetime of an event
+     * sequence is constrained to the next four:
+     *
+     * * None
+     * * None → Denied
+     * * None → Claimed
+     * * None → Claimed → Denied
+     *
+     * Note: Due to event handling ordering, it may be unsafe to set the
+     * state on another gesture within a [signal@Gtk.Gesture::begin] signal
+     * handler, as the callback might be executed before the other gesture
+     * knows about the sequence. A safe way to perform this could be:
+     *
+     * ```c
+     * static void
+     * first_gesture_begin_cb (GtkGesture       *first_gesture,
+     * GdkEventSequence *sequence,
+     * gpointer          user_data)
+     * {
+     * gtk_gesture_set_state (first_gesture, GTK_EVENT_SEQUENCE_CLAIMED);
+     * gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED);
+     * }
+     *
+     * static void
+     * second_gesture_begin_cb (GtkGesture       *second_gesture,
+     * GdkEventSequence *sequence,
+     * gpointer          user_data)
+     * {
+     * if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED)
+     * gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED);
+     * }
+     * ```
+     *
+     * If both gestures are in the same group, just set the state on
+     * the gesture emitting the event, the sequence will be already
+     * be initialized to the group's global state when the second
+     * gesture processes the event.
+     * @param state - the sequence state
+     */
     setState(state) {
         return call("libgtk-4.so.1", "gtk_gesture_set_state", [
             {
@@ -310,6 +595,9 @@ export class Gesture extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Separates `gesture` into an isolated group.
+     */
     ungroup() {
         call("libgtk-4.so.1", "gtk_gesture_ungroup", [
             {

package/dist/generated/gtk/glarea.d.ts

@@ -4,26 +4,157 @@ import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
 import { Widget } from "./widget.js";
 export declare class GLArea extends Widget {
+    /**
+     * Creates a new `GtkGLArea` widget.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Binds buffers to the framebuffer.
+     *
+     * Ensures that the `area` framebuffer object is made the current draw
+     * and read target, and that all the required buffers for the `area` are created and bound to the framebuffer.
+     *
+     * This function is automatically called before emitting the
+     * [signal@Gtk.GLArea::render] signal, and doesn't normally need to be
+     * called by application code.
+     */
     attachBuffers(): void;
+    /**
+     * Gets the allowed APIs.
+     *
+     * See [method@Gtk.GLArea.set_allowed_apis].
+     */
     getAllowedApis(): Gdk.GLAPI;
+    /**
+     * Gets the API that is currently in use.
+     *
+     * If the GL area has not been realized yet, 0 is returned.
+     */
     getApi(): Gdk.GLAPI;
+    /**
+     * Returns whether the area is in auto render mode or not.
+     */
     getAutoRender(): boolean;
+    /**
+     * Retrieves the `GdkGLContext` used by @area.
+     */
     getContext(): Gdk.GLContext | null;
+    /**
+     * Gets the current error set on the @area.
+     */
     getError(): GLib.GError | null;
+    /**
+     * Returns whether the area has a depth buffer.
+     */
     getHasDepthBuffer(): boolean;
+    /**
+     * Returns whether the area has a stencil buffer.
+     */
     getHasStencilBuffer(): boolean;
+    /**
+     * Retrieves the required version of OpenGL.
+     *
+     * See [method@Gtk.GLArea.set_required_version].
+     * @param major - return location for the required major version
+     * @param minor - return location for the required minor version
+     */
     getRequiredVersion(major: Ref<number>, minor: Ref<number>): void;
+    /**
+     * Returns whether the `GtkGLArea` should use OpenGL ES.
+     *
+     * See [method@Gtk.GLArea.set_use_es].
+     */
     getUseEs(): boolean;
+    /**
+     * Ensures that the `GdkGLContext` used by `area` is associated with
+     * the `GtkGLArea`.
+     *
+     * This function is automatically called before emitting the
+     * [signal@Gtk.GLArea::render] signal, and doesn't normally need
+     * to be called by application code.
+     */
     makeCurrent(): void;
+    /**
+     * Marks the currently rendered data (if any) as invalid, and queues
+     * a redraw of the widget.
+     *
+     * This ensures that the [signal@Gtk.GLArea::render] signal
+     * is emitted during the draw.
+     *
+     * This is only needed when [method@Gtk.GLArea.set_auto_render] has
+     * been called with a %FALSE value. The default behaviour is to
+     * emit [signal@Gtk.GLArea::render] on each draw.
+     */
     queueRender(): void;
+    /**
+     * Sets the allowed APIs to create a context with.
+     *
+     * You should check [property@Gtk.GLArea:api] before drawing
+     * with either API.
+     *
+     * By default, all APIs are allowed.
+     * @param apis - the allowed APIs
+     */
     setAllowedApis(apis: Gdk.GLAPI): void;
+    /**
+     * Sets whether the `GtkGLArea` is in auto render mode.
+     *
+     * If `auto_render` is %TRUE the [signal@Gtk.GLArea::render] signal will
+     * be emitted every time the widget draws. This is the default and is
+     * useful if drawing the widget is faster.
+     *
+     * If `auto_render` is %FALSE the data from previous rendering is kept
+     * around and will be used for drawing the widget the next time,
+     * unless the window is resized. In order to force a rendering
+     * [method@Gtk.GLArea.queue_render] must be called. This mode is
+     * useful when the scene changes seldom, but takes a long time to redraw.
+     * @param autoRender - a boolean
+     */
     setAutoRender(autoRender: boolean): void;
+    /**
+     * Sets an error on the area which will be shown instead of the
+     * GL rendering.
+     *
+     * This is useful in the [signal@Gtk.GLArea::create-context]
+     * signal if GL context creation fails.
+     * @param error - a new `GError`, or %NULL to unset the error
+     */
     setError(error?: GLib.GError | null): void;
+    /**
+     * Sets whether the `GtkGLArea` should use a depth buffer.
+     *
+     * If `has_depth_buffer` is %TRUE the widget will allocate and
+     * enable a depth buffer for the target framebuffer. Otherwise
+     * there will be none.
+     * @param hasDepthBuffer - %TRUE to add a depth buffer
+     */
     setHasDepthBuffer(hasDepthBuffer: boolean): void;
+    /**
+     * Sets whether the `GtkGLArea` should use a stencil buffer.
+     *
+     * If `has_stencil_buffer` is %TRUE the widget will allocate and
+     * enable a stencil buffer for the target framebuffer. Otherwise
+     * there will be none.
+     * @param hasStencilBuffer - %TRUE to add a stencil buffer
+     */
     setHasStencilBuffer(hasStencilBuffer: boolean): void;
+    /**
+     * Sets the required version of OpenGL to be used when creating
+     * the context for the widget.
+     *
+     * This function must be called before the area has been realized.
+     * @param major - the major version
+     * @param minor - the minor version
+     */
     setRequiredVersion(major: number, minor: number): void;
+    /**
+     * Sets whether the `area` should create an OpenGL or an OpenGL ES context.
+     *
+     * You should check the capabilities of the `GdkGLContext` before drawing
+     * with either API.
+     * @param useEs - whether to use OpenGL or OpenGL ES
+     */
     setUseEs(useEs: boolean): void;
     connect(signal: "create-context", handler: (self: GLArea) => Gdk.GLContext, after?: boolean): number;
     connect(signal: "render", handler: (self: GLArea, context: Gdk.GLContext) => boolean, after?: boolean): number;