@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/drawing-area.js

@@ -1,6 +1,86 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Allows drawing with cairo.
+ *
+ *
+ *
+ * It’s essentially a blank widget; you can draw on it. After
+ * creating a drawing area, the application may want to connect to:
+ *
+ * - The [signal@Gtk.Widget::realize] signal to take any necessary actions
+ * when the widget is instantiated on a particular display.
+ * (Create GDK resources in response to this signal.)
+ *
+ * - The [signal@Gtk.DrawingArea::resize] signal to take any necessary
+ * actions when the widget changes size.
+ *
+ * - Call [method@Gtk.DrawingArea.set_draw_func] to handle redrawing the
+ * contents of the widget.
+ *
+ * The following code portion demonstrates using a drawing
+ * area to display a circle in the normal widget foreground
+ * color.
+ *
+ * ## Simple GtkDrawingArea usage
+ *
+ * ```c
+ * static void
+ * draw_function (GtkDrawingArea *area,
+ * cairo_t        *cr,
+ * int             width,
+ * int             height,
+ * gpointer        data)
+ * {
+ * GdkRGBA color;
+ *
+ * cairo_arc (cr,
+ * width / 2.0, height / 2.0,
+ * MIN (width, height) / 2.0,
+ * 0, 2 * G_PI);
+ *
+ * gtk_widget_get_color (GTK_WIDGET (area),
+ * &color);
+ * gdk_cairo_set_source_rgba (cr, &color);
+ *
+ * cairo_fill (cr);
+ * }
+ *
+ * int
+ * main (int argc, char **argv)
+ * {
+ * gtk_init ();
+ *
+ * GtkWidget *area = gtk_drawing_area_new ();
+ * gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100);
+ * gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100);
+ * gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area),
+ * draw_function,
+ * NULL, NULL);
+ * return 0;
+ * }
+ * ```
+ *
+ * The draw function is normally called when a drawing area first comes
+ * onscreen, or when it’s covered by another window and then uncovered.
+ * You can also force a redraw by adding to the “damage region” of the
+ * drawing area’s window using [method@Gtk.Widget.queue_draw].
+ * This will cause the drawing area to call the draw function again.
+ *
+ * The available routines for drawing are documented in the
+ * [Cairo documentation](https://www.cairographics.org/manual/); GDK
+ * offers additional API to integrate with Cairo, like [func@Gdk.cairo_set_source_rgba]
+ * or [func@Gdk.cairo_set_source_pixbuf].
+ *
+ * To receive mouse events on a drawing area, you will need to use
+ * event controllers. To receive keyboard events, you will need to set
+ * the “can-focus” property on the drawing area, and you should probably
+ * draw some user-visible indication that the drawing area is focused.
+ *
+ * If you need more complex control over your widget, you should consider
+ * creating your own `GtkWidget` subclass.
+ */
 const SIGNAL_META = {
     resize: {
         params: [
@@ -11,6 +91,9 @@ const SIGNAL_META = {
     },
 };
 export class DrawingArea extends Widget {
+    /**
+     * Creates a new drawing area.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -20,6 +103,9 @@ export class DrawingArea extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Retrieves the content height of the `GtkDrawingArea`.
+     */
     getContentHeight() {
         return call("libgtk-4.so.1", "gtk_drawing_area_get_content_height", [
             {
@@ -28,6 +114,9 @@ export class DrawingArea extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the content width of the `GtkDrawingArea`.
+     */
     getContentWidth() {
         return call("libgtk-4.so.1", "gtk_drawing_area_get_content_width", [
             {
@@ -36,6 +125,17 @@ export class DrawingArea extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets the desired height of the contents of the drawing area.
+     *
+     * Note that because widgets may be allocated larger sizes than they
+     * requested, it is possible that the actual height passed to your draw
+     * function is larger than the height set here. You can use
+     * [method@Gtk.Widget.set_valign] to avoid that.
+     *
+     * If the height is set to 0 (the default), the drawing area may disappear.
+     * @param height - the height of contents
+     */
     setContentHeight(height) {
         call("libgtk-4.so.1", "gtk_drawing_area_set_content_height", [
             {
@@ -48,6 +148,17 @@ export class DrawingArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the desired width of the contents of the drawing area.
+     *
+     * Note that because widgets may be allocated larger sizes than they
+     * requested, it is possible that the actual width passed to your draw
+     * function is larger than the width set here. You can use
+     * [method@Gtk.Widget.set_halign] to avoid that.
+     *
+     * If the width is set to 0 (the default), the drawing area may disappear.
+     * @param width - the width of contents
+     */
     setContentWidth(width) {
         call("libgtk-4.so.1", "gtk_drawing_area_set_content_width", [
             {
@@ -60,6 +171,25 @@ export class DrawingArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Setting a draw function is the main thing you want to do when using
+     * a drawing area.
+     *
+     * The draw function is called whenever GTK needs to draw the contents
+     * of the drawing area to the screen.
+     *
+     * The draw function will be called during the drawing stage of GTK.
+     * In the drawing stage it is not allowed to change properties of any
+     * GTK widgets or call any functions that would cause any properties
+     * to be changed. You should restrict yourself exclusively to drawing
+     * your contents in the draw function.
+     *
+     * If what you are drawing does change, call [method@Gtk.Widget.queue_draw]
+     * on the drawing area. This will cause a redraw and will call `draw_func` again.
+     * @param drawFunc - callback
+     * @param userData - user data passed to @draw_func
+     * @param destroy - destroy notifier for @user_data
+     */
     setDrawFunc(drawFunc) {
         call("libgtk-4.so.1", "gtk_drawing_area_set_draw_func", [
             {

package/dist/generated/gtk/drop-controller-motion.d.ts

@@ -2,10 +2,26 @@ import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
 import { EventController } from "./event-controller.js";
 export declare class DropControllerMotion extends EventController {
+    /**
+     * Creates a new event controller that will handle pointer motion
+     * events during drag and drop.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns if a Drag-and-Drop operation is within the widget
+     * `self` or one of its children.
+     */
     containsPointer(): boolean;
+    /**
+     * Returns the `GdkDrop` of a current Drag-and-Drop operation
+     * over the widget of @self.
+     */
     getDrop(): Gdk.Drop | null;
+    /**
+     * Returns if a Drag-and-Drop operation is within the widget
+     * @self, not one of its children.
+     */
     isPointer(): boolean;
     connect(signal: "enter", handler: (self: DropControllerMotion, x: number, y: number) => void, after?: boolean): number;
     connect(signal: "leave", handler: (self: DropControllerMotion) => void, after?: boolean): number;

package/dist/generated/gtk/drop-controller-motion.js

@@ -2,6 +2,15 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as Gdk from "../gdk/index.js";
 import { EventController } from "./event-controller.js";
+/**
+ * An event controller tracking the pointer during Drag-and-Drop operations.
+ *
+ * It is modeled after [class@Gtk.EventControllerMotion] so if you
+ * have used that, this should feel really familiar.
+ *
+ * This controller is not able to accept drops, use [class@Gtk.DropTarget]
+ * for that purpose.
+ */
 const SIGNAL_META = {
     enter: {
         params: [
@@ -20,6 +29,10 @@ const SIGNAL_META = {
     },
 };
 export class DropControllerMotion extends EventController {
+    /**
+     * Creates a new event controller that will handle pointer motion
+     * events during drag and drop.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -29,6 +42,10 @@ export class DropControllerMotion extends EventController {
             borrowed: false,
         });
     }
+    /**
+     * Returns if a Drag-and-Drop operation is within the widget
+     * `self` or one of its children.
+     */
     containsPointer() {
         return call("libgtk-4.so.1", "gtk_drop_controller_motion_contains_pointer", [
             {
@@ -37,6 +54,10 @@ export class DropControllerMotion extends EventController {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the `GdkDrop` of a current Drag-and-Drop operation
+     * over the widget of @self.
+     */
     getDrop() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_controller_motion_get_drop", [
             {
@@ -48,6 +69,10 @@ export class DropControllerMotion extends EventController {
             return null;
         return getObject(ptr, Gdk.Drop);
     }
+    /**
+     * Returns if a Drag-and-Drop operation is within the widget
+     * @self, not one of its children.
+     */
     isPointer() {
         return call("libgtk-4.so.1", "gtk_drop_controller_motion_is_pointer", [
             {

package/dist/generated/gtk/drop-down.d.ts

@@ -5,28 +5,120 @@ import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
 import { Widget } from "./widget.js";
 export declare class DropDown extends Widget {
+    /**
+     * Creates a new `GtkDropDown`.
+     *
+     * You may want to call [method@Gtk.DropDown.set_factory]
+     * to set up a way to map its items to widgets.
+     * @param model - the model to use
+     * @param expression - the expression to use
+     */
     constructor(model?: Gio.ListModel | null, expression?: Expression | null);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new `GtkDropDown` that is populated with
+     * the strings.
+     * @param strings - The strings to put in the dropdown
+     */
     static downNewFromStrings(strings: string[]): DropDown;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Returns whether search is enabled.
+     */
     getEnableSearch(): boolean;
+    /**
+     * Gets the expression set that is used to obtain strings from items.
+     *
+     * See [method@Gtk.DropDown.set_expression].
+     */
     getExpression(): Expression | null;
+    /**
+     * Gets the factory that's currently used to populate list items.
+     *
+     * The factory returned by this function is always used for the
+     * item in the button. It is also used for items in the popup
+     * if [property@Gtk.DropDown:list-factory] is not set.
+     */
     getFactory(): ListItemFactory | null;
+    /**
+     * Gets the factory that's currently used to create header widgets for the popup.
+     */
     getHeaderFactory(): ListItemFactory | null;
+    /**
+     * Gets the factory that's currently used to populate list items in the popup.
+     */
     getListFactory(): ListItemFactory | null;
+    /**
+     * Gets the model that provides the displayed items.
+     */
     getModel(): Gio.ListModel | null;
+    /**
+     * Returns the match mode that the search filter is using.
+     */
     getSearchMatchMode(): StringFilterMatchMode;
+    /**
+     * Gets the position of the selected item.
+     */
     getSelected(): number;
+    /**
+     * Gets the selected item. If no item is selected, %NULL is returned.
+     */
     getSelectedItem(): GObject.GObject | null;
+    /**
+     * Returns whether to show an arrow within the widget.
+     */
     getShowArrow(): boolean;
+    /**
+     * Sets whether a search entry will be shown in the popup that
+     * allows to search for items in the list.
+     *
+     * Note that [property@Gtk.DropDown:expression] must be set for
+     * search to work.
+     * @param enableSearch - whether to enable search
+     */
     setEnableSearch(enableSearch: boolean): void;
+    /**
+     * Sets the expression that gets evaluated to obtain strings from items.
+     *
+     * This is used for search in the popup. The expression must have
+     * a value type of %G_TYPE_STRING.
+     * @param expression - a `GtkExpression`
+     */
     setExpression(expression?: Expression | null): void;
+    /**
+     * Sets the `GtkListItemFactory` to use for populating list items.
+     * @param factory - the factory to use
+     */
     setFactory(factory?: ListItemFactory | null): void;
+    /**
+     * Sets the `GtkListItemFactory` to use for creating header widgets for the popup.
+     * @param factory - the factory to use
+     */
     setHeaderFactory(factory?: ListItemFactory | null): void;
+    /**
+     * Sets the `GtkListItemFactory` to use for populating list items in the popup.
+     * @param factory - the factory to use
+     */
     setListFactory(factory?: ListItemFactory | null): void;
+    /**
+     * Sets the `GListModel` to use.
+     * @param model - the model to use
+     */
     setModel(model?: Gio.ListModel | null): void;
+    /**
+     * Sets the match mode for the search filter.
+     * @param searchMatchMode - the new match mode
+     */
     setSearchMatchMode(searchMatchMode: StringFilterMatchMode): void;
+    /**
+     * Selects the item at the given position.
+     * @param position - the position of the item to select, or %GTK_INVALID_LIST_POSITION
+     */
     setSelected(position: number): void;
+    /**
+     * Sets whether an arrow will be displayed within the widget.
+     * @param showArrow - whether to show an arrow within the widget
+     */
     setShowArrow(showArrow: boolean): void;
     connect(signal: "activate", handler: (self: DropDown) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: DropDown, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gtk/drop-down.js

@@ -5,6 +5,63 @@ import { ListItemFactory } from "./list-item-factory.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Allows the user to choose an item from a list of options.
+ *
+ *
+ *
+ * The `GtkDropDown` displays the [selected][property@Gtk.DropDown:selected]
+ * choice.
+ *
+ * The options are given to `GtkDropDown` in the form of `GListModel`
+ * and how the individual options are represented is determined by
+ * a [class@Gtk.ListItemFactory]. The default factory displays simple strings,
+ * and adds a checkmark to the selected item in the popup.
+ *
+ * To set your own factory, use [method@Gtk.DropDown.set_factory]. It is
+ * possible to use a separate factory for the items in the popup, with
+ * [method@Gtk.DropDown.set_list_factory].
+ *
+ * `GtkDropDown` knows how to obtain strings from the items in a
+ * [class@Gtk.StringList]; for other models, you have to provide an expression
+ * to find the strings via [method@Gtk.DropDown.set_expression].
+ *
+ * `GtkDropDown` can optionally allow search in the popup, which is
+ * useful if the list of options is long. To enable the search entry,
+ * use [method@Gtk.DropDown.set_enable_search].
+ *
+ * Here is a UI definition example for `GtkDropDown` with a simple model:
+ *
+ * ```xml
+ * <object class="GtkDropDown">
+ * <property name="model">
+ * <object class="GtkStringList">
+ * <items>
+ * <item translatable="yes">Factory</item>
+ * <item translatable="yes">Home</item>
+ * <item translatable="yes">Subway</item>
+ * </items>
+ * </object>
+ * </property>
+ * </object>
+ * ```
+ *
+ * If a `GtkDropDown` is created in this manner, or with
+ * [ctor@Gtk.DropDown.new_from_strings], for instance, the object returned from
+ * [method@Gtk.DropDown.get_selected_item] will be a [class@Gtk.StringObject].
+ *
+ * To learn more about the list widget framework, see the
+ * overview.
+ *
+ * ## CSS nodes
+ *
+ * `GtkDropDown` has a single CSS node with name dropdown,
+ * with the button and popover nodes as children.
+ *
+ * ## Accessibility
+ *
+ * `GtkDropDown` uses the [enum@Gtk.AccessibleRole.combo_box] role.
+ */
 const SIGNAL_META = {
     activate: { params: [], returnType: { type: "undefined" } },
 };
@@ -12,6 +69,11 @@ export class DropDown extends Widget {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new `GtkDropDown` that is populated with
+     * the strings.
+     * @param strings - The strings to put in the dropdown
+     */
     static downNewFromStrings(strings) {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_new_from_strings", [
             {
@@ -36,6 +98,9 @@ export class DropDown extends Widget {
             },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Returns whether search is enabled.
+     */
     getEnableSearch() {
         return call("libgtk-4.so.1", "gtk_drop_down_get_enable_search", [
             {
@@ -44,6 +109,11 @@ export class DropDown extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the expression set that is used to obtain strings from items.
+     *
+     * See [method@Gtk.DropDown.set_expression].
+     */
     getExpression() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_expression", [
             {
@@ -55,6 +125,13 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, Expression);
     }
+    /**
+     * Gets the factory that's currently used to populate list items.
+     *
+     * The factory returned by this function is always used for the
+     * item in the button. It is also used for items in the popup
+     * if [property@Gtk.DropDown:list-factory] is not set.
+     */
     getFactory() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_factory", [
             {
@@ -66,6 +143,9 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, ListItemFactory);
     }
+    /**
+     * Gets the factory that's currently used to create header widgets for the popup.
+     */
     getHeaderFactory() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_header_factory", [
             {
@@ -77,6 +157,9 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, ListItemFactory);
     }
+    /**
+     * Gets the factory that's currently used to populate list items in the popup.
+     */
     getListFactory() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_list_factory", [
             {
@@ -88,6 +171,9 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, ListItemFactory);
     }
+    /**
+     * Gets the model that provides the displayed items.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_model", [
             {
@@ -99,6 +185,9 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, Gio.ListModel);
     }
+    /**
+     * Returns the match mode that the search filter is using.
+     */
     getSearchMatchMode() {
         return call("libgtk-4.so.1", "gtk_drop_down_get_search_match_mode", [
             {
@@ -107,6 +196,9 @@ export class DropDown extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the position of the selected item.
+     */
     getSelected() {
         return call("libgtk-4.so.1", "gtk_drop_down_get_selected", [
             {
@@ -115,6 +207,9 @@ export class DropDown extends Widget {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets the selected item. If no item is selected, %NULL is returned.
+     */
     getSelectedItem() {
         const ptr = call("libgtk-4.so.1", "gtk_drop_down_get_selected_item", [
             {
@@ -126,6 +221,9 @@ export class DropDown extends Widget {
             return null;
         return getObject(ptr, GObject.GObject);
     }
+    /**
+     * Returns whether to show an arrow within the widget.
+     */
     getShowArrow() {
         return call("libgtk-4.so.1", "gtk_drop_down_get_show_arrow", [
             {
@@ -134,6 +232,14 @@ export class DropDown extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets whether a search entry will be shown in the popup that
+     * allows to search for items in the list.
+     *
+     * Note that [property@Gtk.DropDown:expression] must be set for
+     * search to work.
+     * @param enableSearch - whether to enable search
+     */
     setEnableSearch(enableSearch) {
         call("libgtk-4.so.1", "gtk_drop_down_set_enable_search", [
             {
@@ -146,6 +252,13 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the expression that gets evaluated to obtain strings from items.
+     *
+     * This is used for search in the popup. The expression must have
+     * a value type of %G_TYPE_STRING.
+     * @param expression - a `GtkExpression`
+     */
     setExpression(expression) {
         call("libgtk-4.so.1", "gtk_drop_down_set_expression", [
             {
@@ -159,6 +272,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `GtkListItemFactory` to use for populating list items.
+     * @param factory - the factory to use
+     */
     setFactory(factory) {
         call("libgtk-4.so.1", "gtk_drop_down_set_factory", [
             {
@@ -172,6 +289,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `GtkListItemFactory` to use for creating header widgets for the popup.
+     * @param factory - the factory to use
+     */
     setHeaderFactory(factory) {
         call("libgtk-4.so.1", "gtk_drop_down_set_header_factory", [
             {
@@ -185,6 +306,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `GtkListItemFactory` to use for populating list items in the popup.
+     * @param factory - the factory to use
+     */
     setListFactory(factory) {
         call("libgtk-4.so.1", "gtk_drop_down_set_list_factory", [
             {
@@ -198,6 +323,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `GListModel` to use.
+     * @param model - the model to use
+     */
     setModel(model) {
         call("libgtk-4.so.1", "gtk_drop_down_set_model", [
             {
@@ -211,6 +340,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the match mode for the search filter.
+     * @param searchMatchMode - the new match mode
+     */
     setSearchMatchMode(searchMatchMode) {
         call("libgtk-4.so.1", "gtk_drop_down_set_search_match_mode", [
             {
@@ -223,6 +356,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Selects the item at the given position.
+     * @param position - the position of the item to select, or %GTK_INVALID_LIST_POSITION
+     */
     setSelected(position) {
         call("libgtk-4.so.1", "gtk_drop_down_set_selected", [
             {
@@ -235,6 +372,10 @@ export class DropDown extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether an arrow will be displayed within the widget.
+     * @param showArrow - whether to show an arrow within the widget
+     */
     setShowArrow(showArrow) {
         call("libgtk-4.so.1", "gtk_drop_down_set_show_arrow", [
             {