@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -8,73 +8,660 @@ import * as Gio from "../gio/index.js";
 import * as Gsk from "../gsk/index.js";
 import { Widget } from "./widget.js";
 export declare class Window extends Widget {
+    /**
+     * Creates a new `GtkWindow`.
+     *
+     * To get an undecorated window (without window borders),
+     * use [method@Gtk.Window.set_decorated].
+     *
+     * All top-level windows created by this function are stored
+     * in an internal top-level window list. This list can be obtained
+     * from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a
+     * reference to the window internally, this function does not
+     * return a reference to the caller.
+     *
+     * To delete a `GtkWindow`, call [method@Gtk.Window.destroy].
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns the fallback icon name for windows.
+     *
+     * The returned string is owned by GTK and should not
+     * be modified. It is only valid until the next call to
+     * [func@Gtk.Window.set_default_icon_name].
+     */
     static getDefaultIconName(): string;
+    /**
+     * Returns the list of all existing toplevel windows.
+     *
+     * If you want to iterate through the list and perform actions involving
+     * callbacks that might destroy the widgets or add new ones, be aware that
+     * the list of toplevels will change and emit the "items-changed" signal.
+     */
     static getToplevels(): Gio.ListModel;
+    /**
+     * Returns the list of all existing toplevel windows.
+     *
+     * The widgets in the list are not individually referenced.
+     * If you want to iterate through the list and perform actions
+     * involving callbacks that might destroy the widgets, you must
+     * call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first,
+     * and then unref all the widgets afterwards.
+     */
     static listToplevels(): Widget[];
+    /**
+     * Sets whether the window should request startup notification.
+     *
+     * By default, after showing the first window, GTK calls
+     * [method@Gdk.Toplevel.set_startup_id]. Call this function
+     * to disable the automatic startup notification. You might do this
+     * if your first window is a splash screen, and you want to delay
+     * notification until after your real main window has been shown,
+     * for example.
+     *
+     * In that example, you would disable startup notification
+     * temporarily, show your splash screen, then re-enable it so that
+     * showing the main window would automatically result in notification.
+     * @param setting - true to automatically do startup notification
+     */
     static setAutoStartupNotification(setting: boolean): void;
+    /**
+     * Sets an icon to be used as fallback.
+     *
+     * The fallback icon is used for windows that
+     * haven't had [method@Gtk.Window.set_icon_name]
+     * called on them.
+     * @param name - the name of the themed icon
+     */
     static setDefaultIconName(name: string): void;
+    /**
+     * Opens or closes the interactive debugger.
+     *
+     * The debugger offers access to the widget hierarchy of the application
+     * and to useful debugging tools.
+     *
+     * This function allows applications that already use
+     * `Ctrl`+`Shift`+`I`
+     * (or `Ctrl`+`Shift`+`D`)
+     * for their own key shortcuts to add a different shortcut to open the Inspector.
+     *
+     * If you are not overriding the default key shortcuts for the Inspector,
+     * you should not use this function.
+     * @param enable - true to enable interactive debugging
+     */
     static setInteractiveDebugging(enable: boolean): void;
+    /**
+     * Requests that the window is closed.
+     *
+     * This is similar to what happens when a window manager
+     * close button is clicked.
+     *
+     * This function can be used with close buttons in custom
+     * titlebars.
+     */
     close(): void;
+    /**
+     * Drops the internal reference GTK holds on toplevel windows.
+     */
     destroy(): void;
+    /**
+     * Asks to place the window in the fullscreen state.
+     *
+     * Note that you shouldn’t assume the window is definitely fullscreen
+     * afterward, because other entities (e.g. the user or window manager)
+     * unfullscreen it again, and not all window managers honor requests
+     * to fullscreen windows.
+     *
+     * If a window is not explicitly fullscreened or unfullscreened before
+     * it is shown, the initial state is at the window managers discretion.
+     *
+     * You can track the result of this operation via the
+     * [property@Gdk.Toplevel:state] property, or by listening to
+     * notifications of the [property@Gtk.Window:fullscreened] property.
+     */
     fullscreen(): void;
+    /**
+     * Asks to place the window in the fullscreen state on the given monitor.
+     *
+     * Note that you shouldn't assume the window is definitely fullscreen
+     * afterward, or that the windowing system allows fullscreen windows on
+     * any given monitor.
+     *
+     * You can track the result of this operation via the
+     * [property@Gdk.Toplevel:state] property, or by listening to
+     * notifications of the [property@Gtk.Window:fullscreened] property.
+     * @param monitor - which monitor to go fullscreen on
+     */
     fullscreenOnMonitor(monitor: Gdk.Monitor): void;
+    /**
+     * Gets the application object associated with the window.
+     */
     getApplication(): Application | null;
+    /**
+     * Gets the child widget of the window.
+     */
     getChild(): Widget | null;
+    /**
+     * Returns whether the window has been set to have decorations.
+     */
     getDecorated(): boolean;
+    /**
+     * Gets the default size of the window.
+     *
+     * A value of 0 for the width or height indicates that a default
+     * size has not been explicitly set for that dimension, so the
+     * “natural” size of the window will be used.
+     *
+     * This function is the recommended way for saving window state
+     * across restarts of applications.
+     * @param width - location to store the default width
+     * @param height - location to store the default height
+     */
     getDefaultSize(width?: Ref<number> | null, height?: Ref<number> | null): void;
+    /**
+     * Returns the default widget for @window.
+     */
     getDefaultWidget(): Widget | null;
+    /**
+     * Returns whether the window has been set to have a close button.
+     */
     getDeletable(): boolean;
+    /**
+     * Returns whether the window will be destroyed with its transient parent.
+     */
     getDestroyWithParent(): boolean;
+    /**
+     * Retrieves the current focused widget within the window.
+     *
+     * Note that this is the widget that would have the focus
+     * if the toplevel window focused; if the toplevel window
+     * is not focused then `gtk_widget_has_focus (widget)` will
+     * not be false for the widget.
+     */
     getFocus(): Widget | null;
+    /**
+     * Gets whether “focus rectangles” are supposed to be visible.
+     */
     getFocusVisible(): boolean;
+    /**
+     * Returns the gravity that is used when changing the window size programmatically.
+     */
     getGravity(): WindowGravity;
+    /**
+     * Returns the group for the window.
+     *
+     * If the window has no group, then the default group is returned.
+     */
     getGroup(): WindowGroup;
+    /**
+     * Returns whether this window reacts to `F10`
+     * presses by activating a menubar it contains.
+     */
     getHandleMenubarAccel(): boolean;
+    /**
+     * Returns whether the window will be hidden instead of destroyed when the close
+     * button is clicked.
+     */
     getHideOnClose(): boolean;
+    /**
+     * Returns the name of the themed icon for the window.
+     */
     getIconName(): string | null;
+    /**
+     * Gets whether mnemonics are supposed to be visible.
+     */
     getMnemonicsVisible(): boolean;
+    /**
+     * Returns whether the window is modal.
+     */
     getModal(): boolean;
+    /**
+     * Gets whether the user can resize the window.
+     */
     getResizable(): boolean;
+    /**
+     * Retrieves the title of the window.
+     */
     getTitle(): string | null;
+    /**
+     * Returns the titlebar that has been set with
+     * [method@Gtk.Window.set_titlebar].
+     */
     getTitlebar(): Widget | null;
+    /**
+     * Fetches the transient parent for this window.
+     */
     getTransientFor(): Window | null;
+    /**
+     * Returns whether the window has an explicit window group.
+     */
     hasGroup(): boolean;
+    /**
+     * Returns whether the window is part of the current active toplevel.
+     *
+     * The active toplevel is the window receiving keystrokes.
+     *
+     * The return value is %TRUE if the window is active toplevel itself.
+     * You might use this function if you wanted to draw a widget
+     * differently in an active window from a widget in an inactive window.
+     */
     isActive(): boolean;
+    /**
+     * Retrieves the current fullscreen state of the window.
+     *
+     * Note that since fullscreening is ultimately handled by the window
+     * manager and happens asynchronously to an application request, you
+     * shouldn’t assume the return value of this function changing
+     * immediately (or at all), as an effect of calling
+     * [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen].
+     *
+     * If the window isn't yet mapped, the value returned will whether the
+     * initial requested state is fullscreen.
+     */
     isFullscreen(): boolean;
+    /**
+     * Retrieves the current maximized state of the window.
+     *
+     * Note that since maximization is ultimately handled by the window
+     * manager and happens asynchronously to an application request, you
+     * shouldn’t assume the return value of this function changing
+     * immediately (or at all), as an effect of calling
+     * [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize].
+     *
+     * If the window isn't yet mapped, the value returned will whether the
+     * initial requested state is maximized.
+     */
     isMaximized(): boolean;
+    /**
+     * Retrieves the current suspended state of the window.
+     *
+     * A window being suspended means it's currently not visible
+     * to the user, for example by being on a inactive workspace,
+     * minimized, obstructed.
+     */
     isSuspended(): boolean;
+    /**
+     * Asks to maximize the window, so that it fills the screen.
+     *
+     * Note that you shouldn’t assume the window is definitely maximized
+     * afterward, because other entities (e.g. the user or window manager)
+     * could unmaximize it again, and not all window managers support
+     * maximization.
+     *
+     * It’s permitted to call this function before showing a window,
+     * in which case the window will be maximized when it appears onscreen
+     * initially.
+     *
+     * If a window is not explicitly maximized or unmaximized before it is
+     * shown, the initial state is at the window managers discretion. For
+     * example, it might decide to maximize a window that almost fills the
+     * screen.
+     *
+     * You can track the result of this operation via the
+     * [property@Gdk.Toplevel:state] property, or by listening to
+     * notifications on the [property@Gtk.Window:maximized]
+     * property.
+     */
     maximize(): void;
+    /**
+     * Asks to minimize the window.
+     *
+     * Note that you shouldn’t assume the window is definitely minimized
+     * afterward, because the windowing system might not support this
+     * functionality; other entities (e.g. the user or the window manager)
+     * could unminimize it again, or there may not be a window manager in
+     * which case minimization isn’t possible, etc.
+     *
+     * It’s permitted to call this function before showing a window,
+     * in which case the window will be minimized before it ever appears
+     * onscreen.
+     *
+     * You can track result of this operation via the
+     * [property@Gdk.Toplevel:state] property.
+     */
     minimize(): void;
+    /**
+     * Presents a window to the user.
+     *
+     * This may mean raising the window in the stacking order,
+     * unminimizing it, moving it to the current desktop and/or
+     * giving it the keyboard focus (possibly dependent on the user’s
+     * platform, window manager and preferences).
+     *
+     * If `window` is hidden, this function also makes it visible.
+     */
     present(): void;
+    /**
+     * Presents a window to the user in response to an user interaction.
+     *
+     * See [method@Gtk.Window.present] for more details.
+     *
+     * The timestamp should be gathered when the window was requested
+     * to be shown (when clicking a link for example), rather than once
+     * the window is ready to be shown.
+     * @param timestamp - the timestamp of the user interaction (typically a
+     */
     presentWithTime(timestamp: number): void;
+    /**
+     * Sets or unsets the application object associated with the window.
+     *
+     * The application will be kept alive for at least as long as it has
+     * any windows associated with it (see [method@Gio.Application.hold]
+     * for a way to keep it alive without windows).
+     *
+     * Normally, the connection between the application and the window will
+     * remain until the window is destroyed, but you can explicitly remove
+     * it by setting the `application` to %NULL.
+     *
+     * This is equivalent to calling [method@Gtk.Application.remove_window]
+     * and/or [method@Gtk.Application.add_window] on the old/new applications
+     * as relevant.
+     * @param application - a `GtkApplication`
+     */
     setApplication(application?: Application | null): void;
+    /**
+     * Sets the child widget of the window.
+     * @param child - the child widget
+     */
     setChild(child?: Widget | null): void;
+    /**
+     * Sets whether the window should be decorated.
+     *
+     * By default, windows are decorated with a title bar, resize
+     * controls, etc. Some window managers allow GTK to disable these
+     * decorations, creating a borderless window. If you set the decorated
+     * property to false using this function, GTK will do its best to
+     * convince the window manager not to decorate the window. Depending on
+     * the system, this function may not have any effect when called on a
+     * window that is already visible, so you should call it before calling
+     * [method@Gtk.Widget.show].
+     *
+     * On Windows, this function always works, since there’s no window manager
+     * policy involved.
+     * @param setting - true to decorate the window
+     */
     setDecorated(setting: boolean): void;
+    /**
+     * Sets the default size of a window.
+     *
+     * The default size of a window is the size that will be used
+     * if no other constraints apply.
+     *
+     * The default size will be updated whenever the window is resized
+     * to reflect the new size, unless the window is forced to a size,
+     * like when it is maximized or fullscreened.
+     *
+     * If the window’s minimum size request is larger than
+     * the default, the default will be ignored.
+     *
+     * Setting the default size to a value <= 0 will cause it to be
+     * ignored and the natural size request will be used instead. It
+     * is possible to do this while the window is showing to "reset"
+     * it to its initial size.
+     *
+     * Unlike [method@Gtk.Widget.set_size_request], which sets a size
+     * request for a widget and thus would keep users from shrinking
+     * the window, this function only sets the initial size, just as
+     * if the user had resized the window themselves. Users can still
+     * shrink the window again as they normally would. Setting a default
+     * size of -1 means to use the “natural” default size (the size request
+     * of the window).
+     *
+     * If you use this function to reestablish a previously saved window size,
+     * note that the appropriate size to save is the one returned by
+     * [method@Gtk.Window.get_default_size]. Using the window allocation
+     * directly will not work in all circumstances and can lead to growing
+     * or shrinking windows.
+     * @param width - width in pixels, or -1 to unset the default width
+     * @param height - height in pixels, or -1 to unset the default height
+     */
     setDefaultSize(width: number, height: number): void;
+    /**
+     * Sets the default widget.
+     *
+     * The default widget is the widget that is activated
+     * when the user presses `Enter` in a dialog
+     * (for example).
+     * @param defaultWidget - widget to be the default
+     */
     setDefaultWidget(defaultWidget?: Widget | null): void;
+    /**
+     * Sets whether the window should be deletable.
+     *
+     * By default, windows have a close button in the window frame.
+     * Some  window managers allow GTK to disable this button. If you
+     * set the deletable property to false using this function, GTK
+     * will do its best to convince the window manager not to show a
+     * close button. Depending on the system, this function may not
+     * have any effect when called on a window that is already visible,
+     * so you should call it before calling [method@Gtk.Widget.show].
+     *
+     * On Windows, this function always works, since there’s no window
+     * manager policy involved.
+     * @param setting - true to decorate the window as deletable
+     */
     setDeletable(setting: boolean): void;
+    /**
+     * Sets whether to destroy the window when the transient parent is destroyed.
+     *
+     * This is useful for dialogs that shouldn’t persist beyond the lifetime
+     * of the main window they are associated with, for example.
+     * @param setting - whether to destroy the window with its transient parent
+     */
     setDestroyWithParent(setting: boolean): void;
+    /**
+     * Sets the display where the window is displayed.
+     *
+     * If the window is already mapped, it will be unmapped,
+     * and then remapped on the new display.
+     * @param display - a display
+     */
     setDisplay(display: Gdk.Display): void;
+    /**
+     * Sets the focus widget.
+     *
+     * If `focus` is not the current focus widget, and is focusable,
+     * sets it as the focus widget for the window. If `focus` is %NULL,
+     * unsets the focus widget for this window. To set the focus to a
+     * particular widget in the toplevel, it is usually more convenient
+     * to use [method@Gtk.Widget.grab_focus] instead of this function.
+     * @param focus - the new focus widget
+     */
     setFocus(focus?: Widget | null): void;
+    /**
+     * Sets whether “focus rectangles” are supposed to be visible.
+     *
+     * This property is maintained by GTK based on user input,
+     * and should not be set by applications.
+     * @param setting - the new value
+     */
     setFocusVisible(setting: boolean): void;
+    /**
+     * Sets the gravity that is used when changing the window size programmatically.
+     * @param gravity - the new gravity
+     */
     setGravity(gravity: WindowGravity): void;
+    /**
+     * Sets whether this window should react to `F10`
+     * presses by activating a menubar it contains.
+     * @param handleMenubarAccel - true to make `window` handle `F10`
+     */
     setHandleMenubarAccel(handleMenubarAccel: boolean): void;
+    /**
+     * Sets whether clicking the close button will hide the window instead
+     * of destroying it.
+     * @param setting - whether to hide the window when it is closed
+     */
     setHideOnClose(setting: boolean): void;
+    /**
+     * Sets the icon for the window from a named themed icon.
+     *
+     * See the docs for [class@Gtk.IconTheme] for more details.
+     * On some platforms, the window icon is not used at all.
+     *
+     * Note that this has nothing to do with the WM_ICON_NAME
+     * property which is mentioned in the ICCCM.
+     * @param name - the name of the themed icon
+     */
     setIconName(name?: string | null): void;
+    /**
+     * Sets whether mnemonics are supposed to be visible.
+     *
+     * This property is maintained by GTK based on user input,
+     * and should not be set by applications.
+     * @param setting - the new value
+     */
     setMnemonicsVisible(setting: boolean): void;
+    /**
+     * Sets a window modal or non-modal.
+     *
+     * Modal windows prevent interaction with other windows in the same
+     * application. To keep modal dialogs on top of main application windows,
+     * use [method@Gtk.Window.set_transient_for] to make the dialog transient
+     * for the parent; most window managers will then disallow lowering the
+     * dialog below the parent.
+     * @param modal - whether the window is modal
+     */
     setModal(modal: boolean): void;
+    /**
+     * Sets whether the user can resize a window.
+     *
+     * Windows are user resizable by default.
+     * @param resizable - true if the user can resize this window
+     */
     setResizable(resizable: boolean): void;
+    /**
+     * Sets the startup notification ID.
+     *
+     * Startup notification identifiers are used by desktop environment
+     * to track application startup, to provide user feedback and other
+     * features. This function changes the corresponding property on the
+     * underlying `GdkSurface`.
+     *
+     * Normally, startup identifier is managed automatically and you should
+     * only use this function in special cases like transferring focus from
+     * other processes. You should use this function before calling
+     * [method@Gtk.Window.present] or any equivalent function generating
+     * a window map event.
+     *
+     * This function is only useful on Wayland or X11, not with other GDK
+     * backends.
+     * @param startupId - a string with startup-notification identifier
+     */
     setStartupId(startupId: string): void;
+    /**
+     * Sets the title of the window.
+     *
+     * The title of a window will be displayed in its title bar; on the
+     * X Window System, the title bar is rendered by the window manager
+     * so exactly how the title appears to users may vary according to a
+     * user’s exact configuration. The title should help a user distinguish
+     * this window from other windows they may have open. A good title might
+     * include the application name and current document filename, for example.
+     *
+     * Passing `NULL` does the same as setting the title to an empty string.
+     * @param title - title of the window
+     */
     setTitle(title?: string | null): void;
+    /**
+     * Sets a custom titlebar for the window.
+     *
+     * A typical widget used here is [class@Gtk.HeaderBar], as it
+     * provides various features expected of a titlebar while allowing
+     * the addition of child widgets to it.
+     *
+     * If you set a custom titlebar, GTK will do its best to convince
+     * the window manager not to put its own titlebar on the window.
+     * Depending on the system, this function may not work for a window
+     * that is already visible, so you set the titlebar before calling
+     * [method@Gtk.Widget.show].
+     * @param titlebar - the widget to use as titlebar
+     */
     setTitlebar(titlebar?: Widget | null): void;
+    /**
+     * Sets a transient parent for the window.
+     *
+     * Dialog windows should be set transient for the main application
+     * window they were spawned from. This allows window managers to e.g.
+     * keep the dialog on top of the main window, or center the dialog
+     * over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other
+     * convenience functions in GTK will sometimes call this function on
+     * your behalf.
+     *
+     * Passing `NULL` for `parent` unsets the current transient window.
+     *
+     * On Windows, this function puts the child window on top of the parent,
+     * much as the window manager would have done on X.
+     * @param parent - parent window
+     */
     setTransientFor(parent?: Window | null): void;
+    /**
+     * Asks to remove the fullscreen state for the window, and return to
+     * its previous state.
+     *
+     * Note that you shouldn’t assume the window is definitely not
+     * fullscreen afterward, because other entities (e.g. the user or
+     * window manager) could fullscreen it again, and not all window
+     * managers honor requests to unfullscreen windows; normally the
+     * window will end up restored to its normal state. Just don’t
+     * write code that crashes if not.
+     *
+     * If a window is not explicitly fullscreened or unfullscreened before
+     * it is shown, the initial state is at the window managers discretion.
+     *
+     * You can track the result of this operation via the
+     * [property@Gdk.Toplevel:state] property, or by listening to
+     * notifications of the [property@Gtk.Window:fullscreened] property.
+     */
     unfullscreen(): void;
+    /**
+     * Asks to unmaximize the window.
+     *
+     * Note that you shouldn’t assume the window is definitely unmaximized
+     * afterward, because other entities (e.g. the user or window manager)
+     * maximize it again, and not all window managers honor requests to
+     * unmaximize.
+     *
+     * If a window is not explicitly maximized or unmaximized before it is
+     * shown, the initial state is at the window managers discretion. For
+     * example, it might decide to maximize a window that almost fills the
+     * screen.
+     *
+     * You can track the result of this operation via the
+     * [property@Gdk.Toplevel:state] property, or by listening to
+     * notifications on the [property@Gtk.Window:maximized] property.
+     */
     unmaximize(): void;
+    /**
+     * Asks to unminimize the window.
+     *
+     * Note that you shouldn’t assume the window is definitely unminimized
+     * afterward, because the windowing system might not support this
+     * functionality; other entities (e.g. the user or the window manager)
+     * could minimize it again, or there may not be a window manager in
+     * which case minimization isn’t possible, etc.
+     *
+     * You can track result of this operation via the
+     * [property@Gdk.Toplevel:state] property.
+     */
     unminimize(): void;
+    /**
+     * Returns the renderer that is used for this `GtkNative`.
+     */
     getRenderer(): Gsk.Renderer | null;
+    /**
+     * Returns the surface of this `GtkNative`.
+     */
     getSurface(): Gdk.Surface | null;
+    /**
+     * Retrieves the surface transform of @self.
+     *
+     * This is the translation from @self's surface coordinates into
+     * @self's widget coordinates.
+     * @param x - return location for the x coordinate
+     * @param y - return location for the y coordinate
+     */
     getSurfaceTransform(x: Ref<number>, y: Ref<number>): void;
     connect(signal: "activate-default", handler: (self: Window) => void, after?: boolean): number;
     connect(signal: "activate-focus", handler: (self: Window) => void, after?: boolean): number;