@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/calendar.js

@@ -2,6 +2,61 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Displays a Gregorian calendar, one month at a time.
+ *
+ *
+ *
+ * A `GtkCalendar` can be created with [ctor@Gtk.Calendar.new].
+ *
+ * The selected date can be retrieved from a `GtkCalendar` using
+ * [method@Gtk.Calendar.get_date].
+ * It can be altered with [method@Gtk.Calendar.set_date].
+ *
+ * To place a visual marker on a particular day, use
+ * [method@Gtk.Calendar.mark_day] and to remove the marker,
+ * [method@Gtk.Calendar.unmark_day]. Alternative, all
+ * marks can be cleared with [method@Gtk.Calendar.clear_marks].
+ *
+ * Users should be aware that, although the Gregorian calendar is the
+ * legal calendar in most countries, it was adopted progressively
+ * between 1582 and 1929. Display before these dates is likely to be
+ * historically incorrect.
+ *
+ * # Shortcuts and Gestures
+ *
+ * `GtkCalendar` supports the following gestures:
+ *
+ * - Scrolling up or down will switch to the previous or next month.
+ * - Date strings can be dropped for setting the current day.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * calendar.view
+ * ├── header
+ * │   ├── button
+ * │   ├── stack.month
+ * │   ├── button
+ * │   ├── button
+ * │   ├── label.year
+ * │   ╰── button
+ * ╰── grid
+ * ╰── label[.day-name][.week-number][.day-number][.other-month][.today]
+ * ```
+ *
+ * `GtkCalendar` has a main node with name calendar. It contains a subnode
+ * called header containing the widgets for switching between years and months.
+ *
+ * The grid subnode contains all day labels, including week numbers on the left
+ * (marked with the .week-number css class) and day names on top (marked with the
+ * .day-name css class).
+ *
+ * Day labels that belong to the previous or next month get the .other-month
+ * style class. The label of the current day get the .today style class.
+ *
+ * Marked day labels get the :selected state assigned.
+ */
 const SIGNAL_META = {
     "day-selected": { params: [], returnType: { type: "undefined" } },
     "next-month": { params: [], returnType: { type: "undefined" } },
@@ -10,6 +65,9 @@ const SIGNAL_META = {
     "prev-year": { params: [], returnType: { type: "undefined" } },
 };
 export class Calendar extends Widget {
+    /**
+     * Creates a new calendar, with the current date being selected.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -19,6 +77,9 @@ export class Calendar extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Remove all visual markers.
+     */
     clearMarks() {
         call("libgtk-4.so.1", "gtk_calendar_clear_marks", [
             {
@@ -27,6 +88,12 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns a `GDateTime` representing the shown
+     * year, month and the selected day.
+     *
+     * The returned date is in the local time zone.
+     */
     getDate() {
         const ptr = call("libgtk-4.so.1", "gtk_calendar_get_date", [
             {
@@ -41,6 +108,9 @@ export class Calendar extends Widget {
         });
         return getObject(ptr, GLib.DateTime);
     }
+    /**
+     * Gets the day of the selected date.
+     */
     getDay() {
         return call("libgtk-4.so.1", "gtk_calendar_get_day", [
             {
@@ -49,6 +119,10 @@ export class Calendar extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns if the `day` of the `calendar` is already marked.
+     * @param day - the day number between 1 and 31.
+     */
     getDayIsMarked(day) {
         return call("libgtk-4.so.1", "gtk_calendar_get_day_is_marked", [
             {
@@ -61,6 +135,9 @@ export class Calendar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the month of the selected date.
+     */
     getMonth() {
         return call("libgtk-4.so.1", "gtk_calendar_get_month", [
             {
@@ -69,6 +146,13 @@ export class Calendar extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether `self` is currently showing the names
+     * of the week days.
+     *
+     * This is the value of the [property@Gtk.Calendar:show-day-names]
+     * property.
+     */
     getShowDayNames() {
         return call("libgtk-4.so.1", "gtk_calendar_get_show_day_names", [
             {
@@ -77,6 +161,12 @@ export class Calendar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether `self` is currently showing the heading.
+     *
+     * This is the value of the [property@Gtk.Calendar:show-heading]
+     * property.
+     */
     getShowHeading() {
         return call("libgtk-4.so.1", "gtk_calendar_get_show_heading", [
             {
@@ -85,6 +175,13 @@ export class Calendar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether `self` is showing week numbers right
+     * now.
+     *
+     * This is the value of the [property@Gtk.Calendar:show-week-numbers]
+     * property.
+     */
     getShowWeekNumbers() {
         return call("libgtk-4.so.1", "gtk_calendar_get_show_week_numbers", [
             {
@@ -93,6 +190,9 @@ export class Calendar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the year of the selected date.
+     */
     getYear() {
         return call("libgtk-4.so.1", "gtk_calendar_get_year", [
             {
@@ -101,6 +201,10 @@ export class Calendar extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Places a visual marker on a particular day of the current month.
+     * @param day - the day number to mark between 1 and 31.
+     */
     markDay(day) {
         call("libgtk-4.so.1", "gtk_calendar_mark_day", [
             {
@@ -113,6 +217,10 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Switches to @date's year and month and select its day.
+     * @param date - a `GDateTime` representing the day to select
+     */
     selectDay(date) {
         call("libgtk-4.so.1", "gtk_calendar_select_day", [
             {
@@ -130,6 +238,10 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Switches to @date's year and month and selects its day.
+     * @param date - a `GDateTime` representing the day to select
+     */
     setDate(date) {
         call("libgtk-4.so.1", "gtk_calendar_set_date", [
             {
@@ -147,6 +259,13 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the day for the selected date.
+     *
+     * The new date must be valid. For example, setting the day to 31 when the
+     * month is February will fail.
+     * @param day - The desired day for the selected date (as a number between 1 and 31).
+     */
     setDay(day) {
         call("libgtk-4.so.1", "gtk_calendar_set_day", [
             {
@@ -159,6 +278,13 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the month for the selected date.
+     *
+     * The new date must be valid. For example, setting the month to 1 (February)
+     * when the day is 31 will fail.
+     * @param month - The desired month for the selected date (as a number between 0 and 11).
+     */
     setMonth(month) {
         call("libgtk-4.so.1", "gtk_calendar_set_month", [
             {
@@ -171,6 +297,10 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the calendar shows day names.
+     * @param value - Whether to show day names above the day numbers
+     */
     setShowDayNames(value) {
         call("libgtk-4.so.1", "gtk_calendar_set_show_day_names", [
             {
@@ -183,6 +313,13 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the calendar should show a heading.
+     *
+     * The heading contains the current year and month as well as
+     * buttons for changing both.
+     * @param value - Whether to show the heading in the calendar
+     */
     setShowHeading(value) {
         call("libgtk-4.so.1", "gtk_calendar_set_show_heading", [
             {
@@ -195,6 +332,10 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether week numbers are shown in the calendar.
+     * @param value - whether to show week numbers alongside the days
+     */
     setShowWeekNumbers(value) {
         call("libgtk-4.so.1", "gtk_calendar_set_show_week_numbers", [
             {
@@ -207,6 +348,13 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the year for the selected date.
+     *
+     * The new date must be valid. For example, setting the year to 2023 when the
+     * date is February 29 will fail.
+     * @param year - The desired year for the selected date (within [struct@GLib.DateTime]
+     */
     setYear(year) {
         call("libgtk-4.so.1", "gtk_calendar_set_year", [
             {
@@ -219,6 +367,10 @@ export class Calendar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Removes the visual marker from a particular day.
+     * @param day - the day number to unmark between 1 and 31.
+     */
     unmarkDay(day) {
         call("libgtk-4.so.1", "gtk_calendar_unmark_day", [
             {

package/dist/generated/gtk/callback-action.d.ts

@@ -1,5 +1,13 @@
 import { ShortcutAction } from "./shortcut-action.js";
+/** Invokes a callback. */
 export declare class CallbackAction extends ShortcutAction {
+    /**
+     * Create a custom action that calls the given `callback` when
+     * activated.
+     * @param callback - the callback
+     * @param data - the data to be passed to @callback
+     * @param destroy - the function to be called when the callback action is finalized
+     */
     constructor(callback: (...args: unknown[]) => unknown, destroy: () => void, data?: number | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;

package/dist/generated/gtk/callback-action.js

@@ -1,5 +1,6 @@
 import { call } from "@gtkx/native";
 import { ShortcutAction } from "./shortcut-action.js";
+/** Invokes a callback. */
 export class CallbackAction extends ShortcutAction {
     constructor(...args) {
         super(...args);

package/dist/generated/gtk/cclosure-expression.d.ts

@@ -1,5 +1,20 @@
 import { Expression } from "./expression.js";
+/** A variant of `GtkClosureExpression` using a C closure. */
 export declare class CClosureExpression extends Expression {
+    /**
+     * Creates a `GtkExpression` that calls `callback_func` when it is evaluated.
+     *
+     * This function is a variant of [ctor@Gtk.ClosureExpression.new] that
+     * creates a `GClosure` by calling g_cclosure_new() with the given
+     * `callback_func`, `user_data` and `user_destroy`.
+     * @param valueType - the type of the value that this expression evaluates to
+     * @param marshal - marshaller used for creating a closure
+     * @param nParams - the number of params needed for evaluating @closure
+     * @param params - expressions for each parameter
+     * @param callbackFunc - callback used for creating a closure
+     * @param userData - user data used for creating a closure
+     * @param userDestroy - destroy notify for @user_data
+     */
     constructor(valueType: number, nParams: number, params: Expression[], callbackFunc: (...args: unknown[]) => unknown, marshal?: (...args: unknown[]) => unknown | null, userData?: number | null, userDestroy?: (...args: unknown[]) => unknown | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;

package/dist/generated/gtk/cclosure-expression.js

@@ -1,5 +1,6 @@
 import { call } from "@gtkx/native";
 import { Expression } from "./expression.js";
+/** A variant of `GtkClosureExpression` using a C closure. */
 export class CClosureExpression extends Expression {
     constructor(...args) {
         super(...args);

package/dist/generated/gtk/cell-area-box.d.ts

@@ -1,12 +1,50 @@
 import { Orientation } from "./enums.js";
 import * as GObject from "../gobject/index.js";
 import { CellArea } from "./cell-area.js";
+/**
+ * A cell area that renders GtkCellRenderers into a row or a column
+ *
+ * The `GtkCellAreaBox` renders cell renderers into a row or a column
+ * depending on its `GtkOrientation`.
+ *
+ * GtkCellAreaBox uses a notion of packing. Packing
+ * refers to adding cell renderers with reference to a particular position
+ * in a `GtkCellAreaBox`. There are two reference positions: the
+ * start and the end of the box.
+ * When the `GtkCellAreaBox` is oriented in the %GTK_ORIENTATION_VERTICAL
+ * orientation, the start is defined as the top of the box and the end is
+ * defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation
+ * start is defined as the left side and the end is defined as the right
+ * side.
+ *
+ * Alignments of `GtkCellRenderer`s rendered in adjacent rows can be
+ * configured by configuring the `GtkCellAreaBox` align child cell property
+ * with gtk_cell_area_cell_set_property() or by specifying the "align"
+ * argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end().
+ */
 export declare class CellAreaBox extends CellArea {
+    /**
+     * Creates a new `GtkCellAreaBox`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the spacing added between cell renderers.
+     */
     getSpacing(): number;
+    /**
+     * Sets the spacing to add between cell renderers in @box.
+     * @param spacing - the space to add between `GtkCellRenderer`s
+     */
     setSpacing(spacing: number): void;
+    /**
+     * Retrieves the orientation of the @orientable.
+     */
     getOrientation(): Orientation;
+    /**
+     * Sets the orientation of the @orientable.
+     * @param orientation - the orientable’s new orientation
+     */
     setOrientation(orientation: Orientation): void;
     connect(signal: "notify", handler: (self: CellAreaBox, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/cell-area-box.js

@@ -1,7 +1,31 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { CellArea } from "./cell-area.js";
+/**
+ * A cell area that renders GtkCellRenderers into a row or a column
+ *
+ * The `GtkCellAreaBox` renders cell renderers into a row or a column
+ * depending on its `GtkOrientation`.
+ *
+ * GtkCellAreaBox uses a notion of packing. Packing
+ * refers to adding cell renderers with reference to a particular position
+ * in a `GtkCellAreaBox`. There are two reference positions: the
+ * start and the end of the box.
+ * When the `GtkCellAreaBox` is oriented in the %GTK_ORIENTATION_VERTICAL
+ * orientation, the start is defined as the top of the box and the end is
+ * defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation
+ * start is defined as the left side and the end is defined as the right
+ * side.
+ *
+ * Alignments of `GtkCellRenderer`s rendered in adjacent rows can be
+ * configured by configuring the `GtkCellAreaBox` align child cell property
+ * with gtk_cell_area_cell_set_property() or by specifying the "align"
+ * argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end().
+ */
 export class CellAreaBox extends CellArea {
+    /**
+     * Creates a new `GtkCellAreaBox`.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +35,9 @@ export class CellAreaBox extends CellArea {
             borrowed: true,
         });
     }
+    /**
+     * Gets the spacing added between cell renderers.
+     */
     getSpacing() {
         return call("libgtk-4.so.1", "gtk_cell_area_box_get_spacing", [
             {
@@ -19,6 +46,10 @@ export class CellAreaBox extends CellArea {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets the spacing to add between cell renderers in @box.
+     * @param spacing - the space to add between `GtkCellRenderer`s
+     */
     setSpacing(spacing) {
         call("libgtk-4.so.1", "gtk_cell_area_box_set_spacing", [
             {
@@ -31,6 +62,9 @@ export class CellAreaBox extends CellArea {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves the orientation of the @orientable.
+     */
     getOrientation() {
         return call("libgtk-4.so.1", "gtk_orientable_get_orientation", [
             {
@@ -39,6 +73,10 @@ export class CellAreaBox extends CellArea {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets the orientation of the @orientable.
+     * @param orientation - the orientable’s new orientation
+     */
     setOrientation(orientation) {
         call("libgtk-4.so.1", "gtk_orientable_set_orientation", [
             {

package/dist/generated/gtk/cell-area-context.d.ts

@@ -1,18 +1,151 @@
 import { Ref } from "@gtkx/native";
 import { CellArea } from "./cell-area.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Stores geometrical information for a series of rows in a GtkCellArea
+ *
+ * The `GtkCellAreaContext` object is created by a given `GtkCellArea`
+ * implementation via its `GtkCellAreaClass.create_context()` virtual
+ * method and is used to store cell sizes and alignments for a series of
+ * `GtkTreeModel` rows that are requested and rendered in the same context.
+ *
+ * `GtkCellLayout` widgets can create any number of contexts in which to
+ * request and render groups of data rows. However, it’s important that the
+ * same context which was used to request sizes for a given `GtkTreeModel`
+ * row also be used for the same row when calling other `GtkCellArea` APIs
+ * such as gtk_cell_area_render() and gtk_cell_area_event().
+ */
 export declare class CellAreaContext extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Allocates a width and/or a height for all rows which are to be
+     * rendered with @context.
+     *
+     * Usually allocation is performed only horizontally or sometimes
+     * vertically since a group of rows are usually rendered side by
+     * side vertically or horizontally and share either the same width
+     * or the same height. Sometimes they are allocated in both horizontal
+     * and vertical orientations producing a homogeneous effect of the
+     * rows. This is generally the case for `GtkTreeView` when
+     * `GtkTreeView:fixed-height-mode` is enabled.
+     * @param width - the allocated width for all `GtkTreeModel` rows rendered
+     * @param height - the allocated height for all `GtkTreeModel` rows rendered
+     */
     allocate(width: number, height: number): void;
+    /**
+     * Fetches the current allocation size for @context.
+     *
+     * If the context was not allocated in width or height, or if the
+     * context was recently reset with gtk_cell_area_context_reset(),
+     * the returned value will be -1.
+     * @param width - location to store the allocated width
+     * @param height - location to store the allocated height
+     */
     getAllocation(width?: Ref<number> | null, height?: Ref<number> | null): void;
+    /**
+     * Fetches the `GtkCellArea` this `context` was created by.
+     *
+     * This is generally unneeded by layouting widgets; however,
+     * it is important for the context implementation itself to
+     * fetch information about the area it is being used for.
+     *
+     * For instance at `GtkCellAreaContextClass.allocate()` time
+     * it’s important to know details about any cell spacing
+     * that the `GtkCellArea` is configured with in order to
+     * compute a proper allocation.
+     */
     getArea(): CellArea;
+    /**
+     * Gets the accumulative preferred height for all rows which have been
+     * requested with this context.
+     *
+     * After gtk_cell_area_context_reset() is called and/or before ever
+     * requesting the size of a `GtkCellArea`, the returned values are 0.
+     * @param minimumHeight - location to store the minimum height
+     * @param naturalHeight - location to store the natural height
+     */
     getPreferredHeight(minimumHeight?: Ref<number> | null, naturalHeight?: Ref<number> | null): void;
+    /**
+     * Gets the accumulative preferred height for `width` for all rows
+     * which have been requested for the same said `width` with this context.
+     *
+     * After gtk_cell_area_context_reset() is called and/or before ever
+     * requesting the size of a `GtkCellArea`, the returned values are -1.
+     * @param width - a proposed width for allocation
+     * @param minimumHeight - location to store the minimum height
+     * @param naturalHeight - location to store the natural height
+     */
     getPreferredHeightForWidth(width: number, minimumHeight?: Ref<number> | null, naturalHeight?: Ref<number> | null): void;
+    /**
+     * Gets the accumulative preferred width for all rows which have been
+     * requested with this context.
+     *
+     * After gtk_cell_area_context_reset() is called and/or before ever
+     * requesting the size of a `GtkCellArea`, the returned values are 0.
+     * @param minimumWidth - location to store the minimum width
+     * @param naturalWidth - location to store the natural width
+     */
     getPreferredWidth(minimumWidth?: Ref<number> | null, naturalWidth?: Ref<number> | null): void;
+    /**
+     * Gets the accumulative preferred width for `height` for all rows which
+     * have been requested for the same said `height` with this context.
+     *
+     * After gtk_cell_area_context_reset() is called and/or before ever
+     * requesting the size of a `GtkCellArea`, the returned values are -1.
+     * @param height - a proposed height for allocation
+     * @param minimumWidth - location to store the minimum width
+     * @param naturalWidth - location to store the natural width
+     */
     getPreferredWidthForHeight(height: number, minimumWidth?: Ref<number> | null, naturalWidth?: Ref<number> | null): void;
+    /**
+     * Causes the minimum and/or natural height to grow if the new
+     * proposed sizes exceed the current minimum and natural height.
+     *
+     * This is used by `GtkCellAreaContext` implementations during
+     * the request process over a series of `GtkTreeModel` rows to
+     * progressively push the requested height over a series of
+     * gtk_cell_area_get_preferred_height() requests.
+     * @param minimumHeight - the proposed new minimum height for @context
+     * @param naturalHeight - the proposed new natural height for @context
+     */
     pushPreferredHeight(minimumHeight: number, naturalHeight: number): void;
+    /**
+     * Causes the minimum and/or natural width to grow if the new
+     * proposed sizes exceed the current minimum and natural width.
+     *
+     * This is used by `GtkCellAreaContext` implementations during
+     * the request process over a series of `GtkTreeModel` rows to
+     * progressively push the requested width over a series of
+     * gtk_cell_area_get_preferred_width() requests.
+     * @param minimumWidth - the proposed new minimum width for @context
+     * @param naturalWidth - the proposed new natural width for @context
+     */
     pushPreferredWidth(minimumWidth: number, naturalWidth: number): void;
+    /**
+     * Resets any previously cached request and allocation
+     * data.
+     *
+     * When underlying `GtkTreeModel` data changes its
+     * important to reset the context if the content
+     * size is allowed to shrink. If the content size
+     * is only allowed to grow (this is usually an option
+     * for views rendering large data stores as a measure
+     * of optimization), then only the row that changed
+     * or was inserted needs to be (re)requested with
+     * gtk_cell_area_get_preferred_width().
+     *
+     * When the new overall size of the context requires
+     * that the allocated size changes (or whenever this
+     * allocation changes at all), the variable row
+     * sizes need to be re-requested for every row.
+     *
+     * For instance, if the rows are displayed all with
+     * the same width from top to bottom then a change
+     * in the allocated width necessitates a recalculation
+     * of all the displayed row heights using
+     * gtk_cell_area_get_preferred_height_for_width().
+     */
     reset(): void;
     connect(signal: "notify", handler: (self: CellAreaContext, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;