@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/media-stream.js

@@ -2,6 +2,25 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * The integration point for media playback inside GTK.
+ *
+ * GTK provides an implementation of the `GtkMediaStream` interface that
+ * is called [class@Gtk.MediaFile].
+ *
+ * Apart from application-facing API for stream playback, `GtkMediaStream`
+ * has a number of APIs that are only useful for implementations and should
+ * not be used in applications:
+ * [method@Gtk.MediaStream.prepared],
+ * [method@Gtk.MediaStream.unprepared],
+ * [method@Gtk.MediaStream.update],
+ * [method@Gtk.MediaStream.ended],
+ * [method@Gtk.MediaStream.seek_success],
+ * [method@Gtk.MediaStream.seek_failed],
+ * [method@Gtk.MediaStream.gerror],
+ * [method@Gtk.MediaStream.error],
+ * [method@Gtk.MediaStream.error_valist].
+ */
 export class MediaStream extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +36,21 @@ export class MediaStream extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Sets `self` into an error state.
+     *
+     * This will pause the stream (you can check for an error
+     * via [method@Gtk.MediaStream.get_error] in your
+     * GtkMediaStream.pause() implementation), abort pending
+     * seeks and mark the stream as prepared.
+     *
+     * if the stream is already in an error state, this call
+     * will be ignored and the existing error will be retained.
+     *
+     * To unset an error, the stream must be reset via a call to
+     * [method@Gtk.MediaStream.unprepared].
+     * @param error - the `GError` to set
+     */
     gerror(error) {
         call("libgtk-4.so.1", "gtk_media_stream_gerror", [
             {
@@ -29,6 +63,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the duration of the stream.
+     *
+     * If the duration is not known, 0 will be returned.
+     */
     getDuration() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_duration", [
             {
@@ -37,6 +76,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "int", size: 64, unsigned: false });
     }
+    /**
+     * Returns whether the streams playback is finished.
+     */
     getEnded() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_ended", [
             {
@@ -45,6 +87,22 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * If the stream is in an error state, returns the `GError`
+     * explaining that state.
+     *
+     * Any type of error can be reported here depending on the
+     * implementation of the media stream.
+     *
+     * A media stream in an error cannot be operated on, calls
+     * like [method@Gtk.MediaStream.play] or
+     * [method@Gtk.MediaStream.seek] will not have any effect.
+     *
+     * `GtkMediaStream` itself does not provide a way to unset
+     * an error, but implementations may provide options. For example,
+     * a [class@Gtk.MediaFile] will unset errors when a new source is
+     * set, e.g. with [method@Gtk.MediaFile.set_file].
+     */
     getError() {
         const ptr = call("libgtk-4.so.1", "gtk_media_stream_get_error", [
             {
@@ -61,6 +119,11 @@ export class MediaStream extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.GError);
     }
+    /**
+     * Returns whether the stream is set to loop.
+     *
+     * See [method@Gtk.MediaStream.set_loop] for details.
+     */
     getLoop() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_loop", [
             {
@@ -69,6 +132,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the audio for the stream is muted.
+     *
+     * See [method@Gtk.MediaStream.set_muted] for details.
+     */
     getMuted() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_muted", [
             {
@@ -77,6 +145,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Return whether the stream is currently playing.
+     */
     getPlaying() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_playing", [
             {
@@ -85,6 +156,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the current presentation timestamp in microseconds.
+     */
     getTimestamp() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_timestamp", [
             {
@@ -93,6 +167,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "int", size: 64, unsigned: false });
     }
+    /**
+     * Returns the volume of the audio for the stream.
+     *
+     * See [method@Gtk.MediaStream.set_volume] for details.
+     */
     getVolume() {
         return call("libgtk-4.so.1", "gtk_media_stream_get_volume", [
             {
@@ -101,6 +180,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "float", size: 64 });
     }
+    /**
+     * Returns whether the stream has audio.
+     */
     hasAudio() {
         return call("libgtk-4.so.1", "gtk_media_stream_has_audio", [
             {
@@ -109,6 +191,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the stream has video.
+     */
     hasVideo() {
         return call("libgtk-4.so.1", "gtk_media_stream_has_video", [
             {
@@ -117,6 +202,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the stream has finished initializing.
+     *
+     * At this point the existence of audio and video is known.
+     */
     isPrepared() {
         return call("libgtk-4.so.1", "gtk_media_stream_is_prepared", [
             {
@@ -125,6 +215,17 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if a stream may be seekable.
+     *
+     * This is meant to be a hint. Streams may not allow seeking even if
+     * this function returns %TRUE. However, if this function returns
+     * %FALSE, streams are guaranteed to not be seekable and user interfaces
+     * may hide controls that allow seeking.
+     *
+     * It is allowed to call [method@Gtk.MediaStream.seek] on a non-seekable
+     * stream, though it will not do anything.
+     */
     isSeekable() {
         return call("libgtk-4.so.1", "gtk_media_stream_is_seekable", [
             {
@@ -133,6 +234,9 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if there is currently a seek operation going on.
+     */
     isSeeking() {
         return call("libgtk-4.so.1", "gtk_media_stream_is_seeking", [
             {
@@ -141,6 +245,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Pauses playback of the stream.
+     *
+     * If the stream is not playing, do nothing.
+     */
     pause() {
         call("libgtk-4.so.1", "gtk_media_stream_pause", [
             {
@@ -149,6 +258,11 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Starts playing the stream.
+     *
+     * If the stream is in error or already playing, do nothing.
+     */
     play() {
         call("libgtk-4.so.1", "gtk_media_stream_play", [
             {
@@ -157,6 +271,25 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Called by users to attach the media stream to a `GdkSurface` they manage.
+     *
+     * The stream can then access the resources of `surface` for its
+     * rendering purposes. In particular, media streams might want to
+     * create a `GdkGLContext` or sync to the `GdkFrameClock`.
+     *
+     * Whoever calls this function is responsible for calling
+     * [method@Gtk.MediaStream.unrealize] before either the stream
+     * or `surface` get destroyed.
+     *
+     * Multiple calls to this function may happen from different
+     * users of the video, even with the same @surface. Each of these
+     * calls must be followed by its own call to
+     * [method@Gtk.MediaStream.unrealize].
+     *
+     * It is not required to call this function to make a media stream work.
+     * @param surface - a `GdkSurface`
+     */
     realize(surface) {
         call("libgtk-4.so.1", "gtk_media_stream_realize", [
             {
@@ -169,6 +302,20 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Start a seek operation on `self` to @timestamp.
+     *
+     * If `timestamp` is out of range, it will be clamped.
+     *
+     * Seek operations may not finish instantly. While a
+     * seek operation is in process, the [property@Gtk.MediaStream:seeking]
+     * property will be set.
+     *
+     * When calling gtk_media_stream_seek() during an
+     * ongoing seek operation, the new seek will override
+     * any pending seek.
+     * @param timestamp - timestamp to seek to.
+     */
     seek(timestamp) {
         call("libgtk-4.so.1", "gtk_media_stream_seek", [
             {
@@ -181,6 +328,15 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Ends a seek operation started via GtkMediaStream.seek() as a failure.
+     *
+     * This will not cause an error on the stream and will assume that
+     * playback continues as if no seek had happened.
+     *
+     * See [method@Gtk.MediaStream.seek_success] for the other way of
+     * ending a seek.
+     */
     seekFailed() {
         call("libgtk-4.so.1", "gtk_media_stream_seek_failed", [
             {
@@ -189,6 +345,15 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Ends a seek operation started via GtkMediaStream.seek() successfully.
+     *
+     * This function will unset the GtkMediaStream:ended property
+     * if it was set.
+     *
+     * See [method@Gtk.MediaStream.seek_failed] for the other way of
+     * ending a seek.
+     */
     seekSuccess() {
         call("libgtk-4.so.1", "gtk_media_stream_seek_success", [
             {
@@ -197,6 +362,17 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the stream should loop.
+     *
+     * In this case, it will attempt to restart playback
+     * from the beginning instead of stopping at the end.
+     *
+     * Not all streams may support looping, in particular
+     * non-seekable streams. Those streams will ignore the
+     * loop setting and just end.
+     * @param loop - %TRUE if the stream should loop
+     */
     setLoop(loop) {
         call("libgtk-4.so.1", "gtk_media_stream_set_loop", [
             {
@@ -209,6 +385,17 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the audio stream should be muted.
+     *
+     * Muting a stream will cause no audio to be played, but it
+     * does not modify the volume. This means that muting and
+     * then unmuting the stream will restore the volume settings.
+     *
+     * If the stream has no audio, calling this function will
+     * still work but it will not have an audible effect.
+     * @param muted - %TRUE if the stream should be muted
+     */
     setMuted(muted) {
         call("libgtk-4.so.1", "gtk_media_stream_set_muted", [
             {
@@ -221,6 +408,10 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Starts or pauses playback of the stream.
+     * @param playing - whether to start or pause playback
+     */
     setPlaying(playing) {
         call("libgtk-4.so.1", "gtk_media_stream_set_playing", [
             {
@@ -233,6 +424,20 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the volume of the audio stream.
+     *
+     * This function call will work even if the stream is muted.
+     *
+     * The given `volume` should range from 0.0 for silence to 1.0
+     * for as loud as possible. Values outside of this range will
+     * be clamped to the nearest value.
+     *
+     * If the stream has no audio or is muted, calling this function
+     * will still work but it will not have an immediate audible effect.
+     * When the stream is unmuted, the new volume setting will take effect.
+     * @param volume - New volume of the stream from 0.0 to 1.0
+     */
     setVolume(volume) {
         call("libgtk-4.so.1", "gtk_media_stream_set_volume", [
             {
@@ -245,6 +450,14 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Pauses the media stream and marks it as ended.
+     *
+     * This is a hint only, calls to [method@Gtk.MediaStream.play]
+     * may still happen.
+     *
+     * The media stream must be prepared when this function is called.
+     */
     streamEnded() {
         call("libgtk-4.so.1", "gtk_media_stream_stream_ended", [
             {
@@ -253,6 +466,22 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Called by `GtkMediaStream` implementations to advertise the stream
+     * being ready to play and providing details about the stream.
+     *
+     * Note that the arguments are hints. If the stream implementation
+     * cannot determine the correct values, it is better to err on the
+     * side of caution and return %TRUE. User interfaces will use those
+     * values to determine what controls to show.
+     *
+     * This function may not be called again until the stream has been
+     * reset via [method@Gtk.MediaStream.stream_unprepared].
+     * @param hasAudio - %TRUE if the stream should advertise audio support
+     * @param hasVideo - %TRUE if the stream should advertise video support
+     * @param seekable - %TRUE if the stream should advertise seekability
+     * @param duration - The duration of the stream or 0 if unknown
+     */
     streamPrepared(hasAudio, hasVideo, seekable, duration) {
         call("libgtk-4.so.1", "gtk_media_stream_stream_prepared", [
             {
@@ -277,6 +506,13 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Resets a given media stream implementation.
+     *
+     * [method@Gtk.MediaStream.stream_prepared] can then be called again.
+     *
+     * This function will also reset any error state the stream was in.
+     */
     streamUnprepared() {
         call("libgtk-4.so.1", "gtk_media_stream_stream_unprepared", [
             {
@@ -285,6 +521,13 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Undoes a previous call to gtk_media_stream_realize().
+     *
+     * This causes the stream to release all resources it had
+     * allocated from @surface.
+     * @param surface - the `GdkSurface` the stream was realized with
+     */
     unrealize(surface) {
         call("libgtk-4.so.1", "gtk_media_stream_unrealize", [
             {
@@ -297,6 +540,16 @@ export class MediaStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Media stream implementations should regularly call this
+     * function to update the timestamp reported by the stream.
+     *
+     * It is up to implementations to call this at the frequency
+     * they deem appropriate.
+     *
+     * The media stream must be prepared when this function is called.
+     * @param timestamp - the new timestamp
+     */
     update(timestamp) {
         call("libgtk-4.so.1", "gtk_media_stream_update", [
             {

package/dist/generated/gtk/menu-button.d.ts

@@ -3,32 +3,187 @@ import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
 import { Widget } from "./widget.js";
 export declare class MenuButton extends Widget {
+    /**
+     * Creates a new `GtkMenuButton` widget with downwards-pointing
+     * arrow as the only child.
+     *
+     * You can replace the child widget with another `GtkWidget`
+     * should you wish to.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns whether the menu button is active.
+     */
     getActive(): boolean;
+    /**
+     * Gets whether to show a dropdown arrow even when using an icon or a custom
+     * child.
+     */
     getAlwaysShowArrow(): boolean;
+    /**
+     * Retrieves whether the button can be smaller than the natural
+     * size of its contents.
+     */
     getCanShrink(): boolean;
+    /**
+     * Gets the child widget of @menu_button.
+     */
     getChild(): Widget | null;
+    /**
+     * Returns whether the button has a frame.
+     */
     getHasFrame(): boolean;
+    /**
+     * Gets the name of the icon shown in the button.
+     */
     getIconName(): string | null;
+    /**
+     * Gets the label shown in the button
+     */
     getLabel(): string | null;
+    /**
+     * Returns the `GMenuModel` used to generate the popup.
+     */
     getMenuModel(): Gio.MenuModel | null;
+    /**
+     * Returns the `GtkPopover` that pops out of the button.
+     *
+     * If the button is not using a `GtkPopover`, this function
+     * returns %NULL.
+     */
     getPopover(): Popover | null;
+    /**
+     * Returns whether the menu button acts as a primary menu.
+     */
     getPrimary(): boolean;
+    /**
+     * Returns whether an embedded underline in the text indicates a
+     * mnemonic.
+     */
     getUseUnderline(): boolean;
+    /**
+     * Dismiss the menu.
+     */
     popdown(): void;
+    /**
+     * Pop up the menu.
+     */
     popup(): void;
+    /**
+     * Sets whether the menu button is active.
+     * @param active - whether the menu button is active
+     */
     setActive(active: boolean): void;
+    /**
+     * Sets whether to show a dropdown arrow even when using an icon or a custom
+     * child.
+     * @param alwaysShowArrow - whether to show a dropdown arrow even when using an icon
+     */
     setAlwaysShowArrow(alwaysShowArrow: boolean): void;
+    /**
+     * Sets whether the button size can be smaller than the natural size of
+     * its contents.
+     *
+     * For text buttons, setting `can_shrink` to true will ellipsize the label.
+     *
+     * For icon buttons, this function has no effect.
+     * @param canShrink - whether the button can shrink
+     */
     setCanShrink(canShrink: boolean): void;
+    /**
+     * Sets the child widget of @menu_button.
+     *
+     * Setting a child resets [property@Gtk.MenuButton:label] and
+     * [property@Gtk.MenuButton:icon-name].
+     *
+     * If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and
+     * [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow
+     * will be shown next to the child.
+     * @param child - the child widget
+     */
     setChild(child?: Widget | null): void;
+    /**
+     * Sets `func` to be called when a popup is about to be shown.
+     *
+     * `func` should use one of
+     *
+     * - [method@Gtk.MenuButton.set_popover]
+     * - [method@Gtk.MenuButton.set_menu_model]
+     *
+     * to set a popup for @menu_button.
+     * If `func` is non-%NULL, `menu_button` will always be sensitive.
+     *
+     * Using this function will not reset the menu widget attached to
+     * @menu_button. Instead, this can be done manually in @func.
+     * @param func - function
+     * @param userData - user data to pass to @func
+     * @param destroyNotify - destroy notify for @user_data
+     */
     setCreatePopupFunc(func?: (...args: unknown[]) => unknown | null, userData?: number | null, destroyNotify?: () => void | null): void;
+    /**
+     * Sets the style of the button.
+     * @param hasFrame - whether the button should have a visible frame
+     */
     setHasFrame(hasFrame: boolean): void;
+    /**
+     * Sets the name of an icon to show inside the menu button.
+     *
+     * Setting icon name resets [property@Gtk.MenuButton:label] and
+     * [property@Gtk.MenuButton:child].
+     *
+     * If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and
+     * [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow
+     * will be shown next to the icon.
+     * @param iconName - the icon name
+     */
     setIconName(iconName: string): void;
+    /**
+     * Sets the label to show inside the menu button.
+     *
+     * Setting a label resets [property@Gtk.MenuButton:icon-name] and
+     * [property@Gtk.MenuButton:child].
+     *
+     * If [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown
+     * arrow will be shown next to the label.
+     * @param label - the label
+     */
     setLabel(label: string): void;
+    /**
+     * Sets the `GMenuModel` from which the popup will be constructed.
+     *
+     * If `menu_model` is %NULL, the button is disabled.
+     *
+     * A [class@Gtk.Popover] will be created from the menu model with
+     * [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected
+     * as documented for this function.
+     *
+     * If [property@Gtk.MenuButton:popover] is already set, it will be
+     * dissociated from the @menu_button, and the property is set to %NULL.
+     * @param menuModel - a `GMenuModel`, or %NULL to unset and disable the
+     */
     setMenuModel(menuModel?: Gio.MenuModel | null): void;
+    /**
+     * Sets the `GtkPopover` that will be popped up when the `menu_button` is clicked.
+     *
+     * If `popover` is %NULL, the button is disabled.
+     *
+     * If [property@Gtk.MenuButton:menu-model] is set, the menu model is dissociated
+     * from the @menu_button, and the property is set to %NULL.
+     * @param popover - a `GtkPopover`, or %NULL to unset and
+     */
     setPopover(popover?: Popover | null): void;
+    /**
+     * Sets whether menu button acts as a primary menu.
+     *
+     * Primary menus can be opened with the `F10` key.
+     * @param primary - whether the menubutton should act as a primary menu
+     */
     setPrimary(primary: boolean): void;
+    /**
+     * If true, an underline in the text indicates a mnemonic.
+     * @param useUnderline - %TRUE if underlines in the text indicate mnemonics
+     */
     setUseUnderline(useUnderline: boolean): void;
     connect(signal: "activate", handler: (self: MenuButton) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: MenuButton, pspec: GObject.ParamSpec) => void, after?: boolean): number;