@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gio/menu-item.js

@@ -3,10 +3,23 @@ import { getObject } from "@gtkx/ffi";
 import { MenuModel } from "./menu-model.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * #GMenuItem is an opaque structure type.  You must access it using the
+ * functions below.
+ */
 export class MenuItem extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a #GMenuItem as an exact copy of an existing menu item in a
+     * #GMenuModel.
+     *
+     * `item_index` must be valid (ie: be sure to call
+     * g_menu_model_get_n_items() first).
+     * @param model - a #GMenuModel
+     * @param itemIndex - the index of an item in @model
+     */
     static itemNewFromModel(model, itemIndex) {
         const ptr = call("libgio-2.0.so.0", "g_menu_item_new_from_model", [
             {
@@ -20,6 +33,70 @@ export class MenuItem extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, MenuItem);
     }
+    /**
+     * Creates a new #GMenuItem representing a section.
+     *
+     * This is a convenience API around g_menu_item_new() and
+     * g_menu_item_set_section().
+     *
+     * The effect of having one menu appear as a section of another is
+     * exactly as it sounds: the items from `section` become a direct part of
+     * the menu that `menu_item` is added to.
+     *
+     * Visual separation is typically displayed between two non-empty
+     * sections.  If `label` is non-%NULL then it will be incorporated into
+     * this visual indication.  This allows for labeled subsections of a
+     * menu.
+     *
+     * As a simple example, consider a typical "Edit" menu from a simple
+     * program.  It probably contains an "Undo" and "Redo" item, followed by
+     * a separator, followed by "Cut", "Copy" and "Paste".
+     *
+     * This would be accomplished by creating three #GMenu instances.  The
+     * first would be populated with the "Undo" and "Redo" items, and the
+     * second with the "Cut", "Copy" and "Paste" items.  The first and
+     * second menus would then be added as submenus of the third.  In XML
+     * format, this would look something like the following:
+     * |[
+     * <menu id='edit-menu'>
+     * <section>
+     * <item label='Undo'/>
+     * <item label='Redo'/>
+     * </section>
+     * <section>
+     * <item label='Cut'/>
+     * <item label='Copy'/>
+     * <item label='Paste'/>
+     * </section>
+     * </menu>
+     * ]|
+     *
+     * The following example is exactly equivalent.  It is more illustrative
+     * of the exact relationship between the menus and items (keeping in
+     * mind that the 'link' element defines a new menu that is linked to the
+     * containing one).  The style of the second example is more verbose and
+     * difficult to read (and therefore not recommended except for the
+     * purpose of understanding what is really going on).
+     * |[
+     * <menu id='edit-menu'>
+     * <item>
+     * <link name='section'>
+     * <item label='Undo'/>
+     * <item label='Redo'/>
+     * </link>
+     * </item>
+     * <item>
+     * <link name='section'>
+     * <item label='Cut'/>
+     * <item label='Copy'/>
+     * <item label='Paste'/>
+     * </link>
+     * </item>
+     * </menu>
+     * ]|
+     * @param label - the section label, or %NULL
+     * @param section - a #GMenuModel with the items of the section
+     */
     static itemNewSection(section, label) {
         const ptr = call("libgio-2.0.so.0", "g_menu_item_new_section", [
             {
@@ -34,6 +111,14 @@ export class MenuItem extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, MenuItem);
     }
+    /**
+     * Creates a new #GMenuItem representing a submenu.
+     *
+     * This is a convenience API around g_menu_item_new() and
+     * g_menu_item_set_submenu().
+     * @param label - the section label, or %NULL
+     * @param submenu - a #GMenuModel with the items of the submenu
+     */
     static itemNewSubmenu(submenu, label) {
         const ptr = call("libgio-2.0.so.0", "g_menu_item_new_submenu", [
             {
@@ -63,6 +148,15 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Queries the named `attribute` on @menu_item.
+     *
+     * If `expected_type` is specified and the attribute does not have this
+     * type, %NULL is returned.  %NULL is also returned if the attribute
+     * simply does not exist.
+     * @param attribute - the attribute name to query
+     * @param expectedType - the expected type of the attribute
+     */
     getAttributeValue(attribute, expectedType) {
         const ptr = call("libgio-2.0.so.0", "g_menu_item_get_attribute_value", [
             {
@@ -93,6 +187,10 @@ export class MenuItem extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Queries the named `link` on @menu_item.
+     * @param link - the link name to query
+     */
     getLink(link) {
         const ptr = call("libgio-2.0.so.0", "g_menu_item_get_link", [
             {
@@ -108,6 +206,46 @@ export class MenuItem extends GObject.GObject {
             return null;
         return getObject(ptr, MenuModel);
     }
+    /**
+     * Sets or unsets the "action" and "target" attributes of @menu_item.
+     *
+     * If `action` is %NULL then both the "action" and "target" attributes
+     * are unset (and `target_value` is ignored).
+     *
+     * If `action` is non-%NULL then the "action" attribute is set.  The
+     * "target" attribute is then set to the value of `target_value` if it is
+     * non-%NULL or unset otherwise.
+     *
+     * Normal menu items (ie: not submenu, section or other custom item
+     * types) are expected to have the "action" attribute set to identify
+     * the action that they are associated with.  The state type of the
+     * action help to determine the disposition of the menu item.  See
+     * #GAction and #GActionGroup for an overview of actions.
+     *
+     * In general, clicking on the menu item will result in activation of
+     * the named action with the "target" attribute given as the parameter
+     * to the action invocation.  If the "target" attribute is not set then
+     * the action is invoked with no parameter.
+     *
+     * If the action has no state then the menu item is usually drawn as a
+     * plain menu item (ie: with no additional decoration).
+     *
+     * If the action has a boolean state then the menu item is usually drawn
+     * as a toggle menu item (ie: with a checkmark or equivalent
+     * indication).  The item should be marked as 'toggled' or 'checked'
+     * when the boolean state is %TRUE.
+     *
+     * If the action has a string state then the menu item is usually drawn
+     * as a radio menu item (ie: with a radio bullet or equivalent
+     * indication).  The item should be marked as 'selected' when the string
+     * state is equal to the value of the `target` property.
+     *
+     * See g_menu_item_set_action_and_target() or
+     * g_menu_item_set_detailed_action() for two equivalent calls that are
+     * probably more convenient for most uses.
+     * @param action - the name of the action for this item
+     * @param targetValue - a #GVariant to use as the action target
+     */
     setActionAndTargetValue(action, targetValue) {
         call("libgio-2.0.so.0", "g_menu_item_set_action_and_target_value", [
             {
@@ -131,6 +269,29 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets or unsets an attribute on @menu_item.
+     *
+     * The attribute to set or unset is specified by @attribute. This
+     * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+     * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+     * attribute name.
+     * Attribute names are restricted to lowercase characters, numbers
+     * and '-'. Furthermore, the names must begin with a lowercase character,
+     * must not end with a '-', and must not contain consecutive dashes.
+     *
+     * must consist only of lowercase
+     * ASCII characters, digits and '-'.
+     *
+     * If `value` is non-%NULL then it is used as the new value for the
+     * attribute.  If `value` is %NULL then the attribute is unset. If
+     * the `value` #GVariant is floating, it is consumed.
+     *
+     * See also g_menu_item_set_attribute() for a more convenient way to do
+     * the same.
+     * @param attribute - the attribute to set
+     * @param value - a #GVariant to use as the value, or %NULL
+     */
     setAttributeValue(attribute, value) {
         call("libgio-2.0.so.0", "g_menu_item_set_attribute_value", [
             {
@@ -153,6 +314,20 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the "action" and possibly the "target" attribute of @menu_item.
+     *
+     * The format of `detailed_action` is the same format parsed by
+     * g_action_parse_detailed_name().
+     *
+     * See g_menu_item_set_action_and_target() or
+     * g_menu_item_set_action_and_target_value() for more flexible (but
+     * slightly less convenient) alternatives.
+     *
+     * See also g_menu_item_set_action_and_target_value() for a description of
+     * the semantics of the action and target attributes.
+     * @param detailedAction - the "detailed" action string
+     */
     setDetailedAction(detailedAction) {
         call("libgio-2.0.so.0", "g_menu_item_set_detailed_action", [
             {
@@ -165,6 +340,21 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets (or unsets) the icon on @menu_item.
+     *
+     * This call is the same as calling g_icon_serialize() and using the
+     * result as the value to g_menu_item_set_attribute_value() for
+     * %G_MENU_ATTRIBUTE_ICON.
+     *
+     * This API is only intended for use with "noun" menu items; things like
+     * bookmarks or applications in an "Open With" menu.  Don't use it on
+     * menu items corresponding to verbs (eg: stock icons for 'Save' or
+     * 'Quit').
+     *
+     * If `icon` is %NULL then the icon is unset.
+     * @param icon - a #GIcon, or %NULL
+     */
     setIcon(icon) {
         call("libgio-2.0.so.0", "g_menu_item_set_icon", [
             {
@@ -177,6 +367,13 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets or unsets the "label" attribute of @menu_item.
+     *
+     * If `label` is non-%NULL it is used as the label for the menu item.  If
+     * it is %NULL then the label attribute is unset.
+     * @param label - the label to set, or %NULL to unset
+     */
     setLabel(label) {
         call("libgio-2.0.so.0", "g_menu_item_set_label", [
             {
@@ -190,6 +387,20 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a link from `menu_item` to `model` if non-%NULL, or unsets it.
+     *
+     * Links are used to establish a relationship between a particular menu
+     * item and another menu.  For example, %G_MENU_LINK_SUBMENU is used to
+     * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
+     * is used to create a section. Other types of link can be used, but there
+     * is no guarantee that clients will be able to make sense of them.
+     * Link types are restricted to lowercase characters, numbers
+     * and '-'. Furthermore, the names must begin with a lowercase character,
+     * must not end with a '-', and must not contain consecutive dashes.
+     * @param link - type of link to establish or unset
+     * @param model - the #GMenuModel to link to (or %NULL to unset)
+     */
     setLink(link, model) {
         call("libgio-2.0.so.0", "g_menu_item_set_link", [
             {
@@ -207,6 +418,16 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets or unsets the "section" link of `menu_item` to @section.
+     *
+     * The effect of having one menu appear as a section of another is
+     * exactly as it sounds: the items from `section` become a direct part of
+     * the menu that `menu_item` is added to.  See g_menu_item_new_section()
+     * for more information about what it means for a menu item to be a
+     * section.
+     * @param section - a #GMenuModel, or %NULL
+     */
     setSection(section) {
         call("libgio-2.0.so.0", "g_menu_item_set_section", [
             {
@@ -220,6 +441,16 @@ export class MenuItem extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets or unsets the "submenu" link of `menu_item` to @submenu.
+     *
+     * If `submenu` is non-%NULL, it is linked to.  If it is %NULL then the
+     * link is unset.
+     *
+     * The effect of having one menu appear as a submenu of another is
+     * exactly as it sounds.
+     * @param submenu - a #GMenuModel, or %NULL
+     */
     setSubmenu(submenu) {
         call("libgio-2.0.so.0", "g_menu_item_set_submenu", [
             {

package/dist/generated/gio/menu-link-iter.d.ts

@@ -1,12 +1,54 @@
 import { Ref } from "@gtkx/native";
 import { MenuModel } from "./menu-model.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * #GMenuLinkIter is an opaque structure type.  You must access it using
+ * the functions below.
+ */
 export declare class MenuLinkIter extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the name of the link at the current iterator position.
+     *
+     * The iterator is not advanced.
+     */
     getName(): string;
+    /**
+     * This function combines g_menu_link_iter_next() with
+     * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+     *
+     * First the iterator is advanced to the next (possibly first) link.
+     * If that fails, then %FALSE is returned and there are no other effects.
+     *
+     * If successful, `out_link` and `value` are set to the name and #GMenuModel
+     * of the link that has just been advanced to.  At this point,
+     * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
+     * same values again.
+     *
+     * The value returned in `out_link` remains valid for as long as the iterator
+     * remains at the current position.  The value returned in `value` must
+     * be unreffed using g_object_unref() when it is no longer in use.
+     * @param outLink - the name of the link
+     * @param value - the linked #GMenuModel
+     */
     getNext(outLink?: Ref<string> | null, value?: Ref<MenuModel> | null): boolean;
+    /**
+     * Gets the linked #GMenuModel at the current iterator position.
+     *
+     * The iterator is not advanced.
+     */
     getValue(): MenuModel;
+    /**
+     * Attempts to advance the iterator to the next (possibly first)
+     * link.
+     *
+     * %TRUE is returned on success, or %FALSE if there are no more links.
+     *
+     * You must call this function when you first acquire the iterator to
+     * advance it to the first link (and determine if the first link exists
+     * at all).
+     */
     next(): boolean;
     connect(signal: "notify", handler: (self: MenuLinkIter, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/menu-link-iter.js

@@ -2,6 +2,10 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { MenuModel } from "./menu-model.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * #GMenuLinkIter is an opaque structure type.  You must access it using
+ * the functions below.
+ */
 export class MenuLinkIter extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +21,11 @@ export class MenuLinkIter extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Gets the name of the link at the current iterator position.
+     *
+     * The iterator is not advanced.
+     */
     getName() {
         return call("libgio-2.0.so.0", "g_menu_link_iter_get_name", [
             {
@@ -25,6 +34,24 @@ export class MenuLinkIter extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * This function combines g_menu_link_iter_next() with
+     * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+     *
+     * First the iterator is advanced to the next (possibly first) link.
+     * If that fails, then %FALSE is returned and there are no other effects.
+     *
+     * If successful, `out_link` and `value` are set to the name and #GMenuModel
+     * of the link that has just been advanced to.  At this point,
+     * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
+     * same values again.
+     *
+     * The value returned in `out_link` remains valid for as long as the iterator
+     * remains at the current position.  The value returned in `value` must
+     * be unreffed using g_object_unref() when it is no longer in use.
+     * @param outLink - the name of the link
+     * @param value - the linked #GMenuModel
+     */
     getNext(outLink, value) {
         return call("libgio-2.0.so.0", "g_menu_link_iter_get_next", [
             {
@@ -43,6 +70,11 @@ export class MenuLinkIter extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the linked #GMenuModel at the current iterator position.
+     *
+     * The iterator is not advanced.
+     */
     getValue() {
         const ptr = call("libgio-2.0.so.0", "g_menu_link_iter_get_value", [
             {
@@ -52,6 +84,16 @@ export class MenuLinkIter extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, MenuModel);
     }
+    /**
+     * Attempts to advance the iterator to the next (possibly first)
+     * link.
+     *
+     * %TRUE is returned on success, or %FALSE if there are no more links.
+     *
+     * You must call this function when you first acquire the iterator to
+     * advance it to the first link (and determine if the first link exists
+     * at all).
+     */
     next() {
         return call("libgio-2.0.so.0", "g_menu_link_iter_next", [
             {

package/dist/generated/gio/menu-model.d.ts

@@ -5,12 +5,80 @@ import * as GObject from "../gobject/index.js";
 export declare class MenuModel extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Queries the item at position `item_index` in `model` for the attribute
+     * specified by @attribute.
+     *
+     * If `expected_type` is non-%NULL then it specifies the expected type of
+     * the attribute.  If it is %NULL then any type will be accepted.
+     *
+     * If the attribute exists and matches `expected_type` (or if the
+     * expected type is unspecified) then the value is returned.
+     *
+     * If the attribute does not exist, or does not match the expected type
+     * then %NULL is returned.
+     * @param itemIndex - the index of the item
+     * @param attribute - the attribute to query
+     * @param expectedType - the expected type of the attribute, or
+     */
     getItemAttributeValue(itemIndex: number, attribute: string, expectedType?: GLib.VariantType | null): GLib.Variant | null;
+    /**
+     * Queries the item at position `item_index` in `model` for the link
+     * specified by @link.
+     *
+     * If the link exists, the linked #GMenuModel is returned.  If the link
+     * does not exist, %NULL is returned.
+     * @param itemIndex - the index of the item
+     * @param link - the link to query
+     */
     getItemLink(itemIndex: number, link: string): MenuModel | null;
+    /**
+     * Query the number of items in @model.
+     */
     getNItems(): number;
+    /**
+     * Queries if `model` is mutable.
+     *
+     * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+     * signal. Consumers of the model may make optimisations accordingly.
+     */
     isMutable(): boolean;
+    /**
+     * Requests emission of the #GMenuModel::items-changed signal on @model.
+     *
+     * This function should never be called except by #GMenuModel
+     * subclasses.  Any other calls to this function will very likely lead
+     * to a violation of the interface of the model.
+     *
+     * The implementation should update its internal representation of the
+     * menu before emitting the signal.  The implementation should further
+     * expect to receive queries about the new state of the menu (and
+     * particularly added menu items) while signal handlers are running.
+     *
+     * The implementation must dispatch this call directly from a mainloop
+     * entry and not in response to calls -- particularly those from the
+     * #GMenuModel API.  Said another way: the menu must not change while
+     * user code is running without returning to the mainloop.
+     * @param position - the position of the change
+     * @param removed - the number of items removed
+     * @param added - the number of items added
+     */
     itemsChanged(position: number, removed: number, added: number): void;
+    /**
+     * Creates a #GMenuAttributeIter to iterate over the attributes of
+     * the item at position `item_index` in @model.
+     *
+     * You must free the iterator with g_object_unref() when you are done.
+     * @param itemIndex - the index of the item
+     */
     iterateItemAttributes(itemIndex: number): MenuAttributeIter;
+    /**
+     * Creates a #GMenuLinkIter to iterate over the links of the item at
+     * position `item_index` in @model.
+     *
+     * You must free the iterator with g_object_unref() when you are done.
+     * @param itemIndex - the index of the item
+     */
     iterateItemLinks(itemIndex: number): MenuLinkIter;
     connect(signal: "items-changed", handler: (self: MenuModel, position: number, removed: number, added: number) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: MenuModel, pspec: GObject.ParamSpec) => void, after?: boolean): number;