@gjsify/adwaita-core 0.36.0 → 0.38.0

package/lib/types/button-content.d.ts

@@ -1,9 +1,6 @@
-/**
- * The style class `AdwButtonContent` stamps on its parent button (:115) and
- * removes again on unroot (:126).
- */
+/** The style class `AdwButtonContent` stamps on its parent button, removed on unroot. */
 export declare const BUTTON_CONTENT_STYLE_CLASS = "image-text-button";
-/** The icon `GtkImage` falls back to for an empty `icon-name` (:355-356). */
+/** The icon `GtkImage` falls back to for an empty `icon-name`. */
 export declare const BUTTON_CONTENT_FALLBACK_ICON = "image-missing";
 /** How `can-shrink` reaches the label — `PangoEllipsizeMode` as a string union. */
 export type ButtonContentEllipsize = 'none' | 'end';
@@ -18,124 +15,88 @@ export interface AdwButtonContentProps {
     /** `can-shrink` — whether the label ellipsizes rather than widening the button. */
     canShrink: boolean;
 }
-/**
- * The property defaults a freshly constructed `AdwButtonContent` has, straight
- * from the `GParamSpec`s. All four are the empty/false end of their type.
- */
+/** The property defaults of a freshly constructed `AdwButtonContent`, from the `GParamSpec`s. */
 export declare const ADW_BUTTON_CONTENT_DEFAULTS: Readonly<AdwButtonContentProps>;
 /**
- * Whether the icon slot is empty — the `!icon_name[0]` test at :355.
- *
- * The one icon question that does not depend on how a renderer represents the
- * icon: a name is empty or it is not, an SVG string is empty or it is not. Kept
- * separate from {@link buttonContentIconName} so the NativeScript port, which
- * holds SVG source rather than theme names, has something in core to ask.
+ * Whether the icon slot is empty — the `!icon_name[0]` test. Separate from
+ * {@link buttonContentIconName} because it is the one icon question an SVG-holding
+ * renderer can also ask.
  */
 export declare function buttonContentIconIsEmpty(icon: string): boolean;
 /**
  * The icon-theme name the image is actually set from: `icon_name`, or
- * `image-missing` when it is empty (:355-358).
+ * `image-missing` when it is empty.
  *
- * UPSTREAM CONTRADICTION — the code and the docs disagree, and this follows the
- * CODE. Both doc comments say the icon "is not shown" when `icon-name` is empty
- * (:228 on the property, :343 on the setter), but nothing in the widget ever
- * hides `self->icon`: `gtk_widget_set_visible` is called on the LABEL (:300,
- * :398) and never on the image, `init` sets the image to `image-missing` while
- * `icon_name` is still `""` (:284, :294), and the setter re-applies that
- * fallback for every empty value (:355-356). A default-constructed
- * `AdwButtonContent` therefore draws the broken-image glyph. Both ports followed
- * the prose and hid the icon; a vector written from the prose would have pinned
- * that guess and shipped it under the word "conformance", which is the one thing
- * these tables must not do.
+ * UPSTREAM CONTRADICTION, resolved in favour of the CODE: both libadwaita doc
+ * comments say the icon "is not shown" when `icon-name` is empty, but
+ * `gtk_widget_set_visible` is only ever called on the LABEL, `init` sets the image to
+ * `image-missing` while `icon_name` is still `""`, and the setter re-applies that
+ * fallback for every empty value. A default-constructed `AdwButtonContent` therefore
+ * draws the broken-image glyph.
  */
 export declare function buttonContentIconName(iconName: string): string;
 /**
  * Whether the label node is in the tree: `gtk_widget_set_visible (self->label,
- * label[0])` (:398).
- *
- * First character, not truthiness and not a trim — `" "` is a label and its node
- * is shown, exactly as with the banner button.
+ * label[0])` — first character, not truthiness and not a trim, so `" "` is a label
+ * and its node is shown.
  */
 export declare function buttonContentLabelVisible(label: string): boolean;
 /**
- * Whether the icon takes the box's free space: `gtk_widget_set_hexpand
- * (self->icon, !label[0])` (:399), matching the `TRUE` init sets while the label
- * is still empty (:296).
- *
- * The complement of {@link buttonContentLabelVisible} by construction, and named
- * for what it DOES rather than derived at each call site: with no label the icon
- * expands and so centres itself inside the button; with a label the pair sits
- * together under the box's `halign: CENTER` (:289).
+ * Whether the icon takes the box's free space: `gtk_widget_set_hexpand (self->icon,
+ * !label[0])`. With no label the icon expands and so centres itself inside the
+ * button; with a label the pair sits together under the box's `halign: CENTER`.
  */
 export declare function buttonContentIconExpands(label: string): boolean;
 /**
- * The text painted on the label, with mnemonic markers removed when
- * `use-underline` is set (:442).
- *
- * Default FALSE (:253-256), so an underscore survives unless the app asked for
- * mnemonics — the opposite default to the banner's action button, which its
- * template pins to TRUE.
+ * The text painted on the label, with mnemonic markers removed when `use-underline`
+ * is set. Default FALSE, so an underscore survives unless the app asked for
+ * mnemonics — the opposite default to the banner's action button, whose template
+ * pins it to TRUE.
  */
 export declare function buttonContentLabelText(label: string, useUnderline: boolean): string;
-/**
- * The label's `PangoEllipsizeMode` for `can-shrink` — `END` or `NONE`
- * (:489-491), which is also how the getter reads the property back (:462).
- */
+/** The label's `PangoEllipsizeMode` for `can-shrink` — `END` or `NONE`. */
 export declare function buttonContentEllipsize(canShrink: boolean): ButtonContentEllipsize;
 /**
- * One entry of the ancestor chain `adw_button_content_root` walks, nearest
- * first, tagged by the only distinction the C makes.
+ * One entry of the ancestor chain `adw_button_content_root` walks, nearest first.
  *
- * `'button'` is a `GtkButton` (or any subclass); `'menu-button'` and
- * `'split-button'` are `GtkMenuButton` and `AdwSplitButton`, neither of which
- * derives from `GtkButton` — `AdwSplitButton` is a `GtkWidget`
- * (adw-split-button.c:112), which is exactly why it cannot be found by
- * `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` and needs the retarget.
- * `'other'` is any other container.
+ * Neither `'menu-button'` (`GtkMenuButton`) nor `'split-button'` (`AdwSplitButton`)
+ * derives from `GtkButton`, so neither is found by
+ * `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` — which is why the retarget exists.
  */
 export type ButtonContentAncestor = 'button' | 'menu-button' | 'split-button' | 'other';
 /**
  * Which ancestor receives {@link BUTTON_CONTENT_STYLE_CLASS}, as an INDEX into
  * `ancestors` (nearest first), or `null` when there is no button ancestor.
  *
- * `adw_button_content_root` (:108-116) takes the nearest `GtkButton`, then makes
- * ONE substitution: if that button's DIRECT parent is an `AdwSplitButton`, the
- * class goes on the split button instead (:112-113), because the split button is
- * the node the stylesheet styles (`splitbutton.image-text-button > button`,
- * _buttons.scss:499-507). Inside a `GtkMenuButton` no substitution happens, so
- * the menu button's INTERNAL button keeps the class — which is what the class
- * docs describe (:56-59).
+ * `adw_button_content_root` takes the nearest `GtkButton`, then makes ONE
+ * substitution: if that button's DIRECT parent is an `AdwSplitButton`, the class goes
+ * on the split button instead, because that is the node the stylesheet styles
+ * (`splitbutton.image-text-button > button`). Inside a `GtkMenuButton` no
+ * substitution happens, so the menu button's INTERNAL button keeps the class.
  *
- * `null` is this port's answer to a case the C does not survive: with no button
- * ancestor at all `gtk_widget_get_ancestor` returns `NULL`, and the very next
- * lines call `gtk_widget_get_parent (NULL)` and `gtk_widget_add_css_class (NULL,
- * …)` (:112-115), which are two `CRITICAL`s. A renderer has nothing to style,
- * and saying so is better than reproducing a crash.
+ * MODIFICATION: `null` where the C does not survive — with no button ancestor
+ * `gtk_widget_get_ancestor` returns `NULL` and the next lines call
+ * `gtk_widget_get_parent (NULL)` / `gtk_widget_add_css_class (NULL, …)`, two
+ * `CRITICAL`s. A renderer has nothing to style; saying so beats reproducing a crash.
  */
 export declare function buttonContentStyleTargetIndex(ancestors: readonly ButtonContentAncestor[]): number | null;
 /** What one button-content derivation tells a renderer to draw. */
 export interface AdwButtonContentRenderState {
-    /** The icon-theme name the image node shows (:355-358). */
     iconName: string;
     /** Whether {@link iconName} is the empty-slot fallback rather than an app value. */
     iconIsFallback: boolean;
-    /** Whether the icon takes the box's free space (:399). */
+    /** Whether the icon takes the box's free space. */
     iconExpands: boolean;
-    /** Whether the label node is in the tree (:398). */
     labelVisible: boolean;
-    /** The label text, mnemonic markers resolved (:442). */
+    /** The label text, mnemonic markers resolved. */
     labelText: string;
-    /** The label's ellipsize mode (:489-491). */
     ellipsize: ButtonContentEllipsize;
-    /** The style class the parent button carries while this content is rooted (:115). */
+    /** The style class the parent button carries while this content is rooted. */
     parentClass: string;
 }
 /**
  * The full render state for a button content, filling every unset property from
- * {@link ADW_BUTTON_CONTENT_DEFAULTS}.
- *
- * `parentClass` is constant, and is in the state anyway so a renderer takes the
- * class from the same call that gives it the rest — the whole defect this module
- * fixes was a renderer never being handed that string at all.
+ * {@link ADW_BUTTON_CONTENT_DEFAULTS}. `parentClass` is constant but travels in the
+ * state anyway, so a renderer cannot get everything else and still miss the class.
  */
 export declare function buttonContentRenderState(props?: Partial<AdwButtonContentProps>): AdwButtonContentRenderState;