@gtkx/testing 1.0.0-rc.4 → 1.0.0

package/src/user-event/selection.ts

@@ -1,11 +1,23 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { formatRoleList } from "../role-helpers.js";
+import { getCallableMethod } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
+import {
+    getChildAtIndex,
+    hasIndexedChildren,
+    isChildSelected,
+    selectContainerChild,
+    unselectContainerChild,
+} from "./indexed-children.js";
 
 type CollectionWidget = Gtk.ListView | Gtk.GridView | Gtk.ColumnView;
-type ListBoxRowAction = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow) => void;
+type IndexedChildAction = (container: Gtk.Widget, child: Gtk.Widget) => void;
 
-const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
+const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([
+    Gtk.AccessibleRole.COMBO_BOX,
+    Gtk.AccessibleRole.GRID,
+    Gtk.AccessibleRole.LIST,
+]);
 
 const isSelectable = (widget: Gtk.Widget): boolean => {
     return SELECTABLE_ROLES.has(widget.getAccessibleRole());
@@ -44,42 +56,40 @@ const selectListViewItems = (
 const isListView = (widget: Gtk.Widget): widget is CollectionWidget =>
     widget instanceof Gtk.ListView || widget instanceof Gtk.GridView || widget instanceof Gtk.ColumnView;
 
-const selectComboBoxOption = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (valueArray.length > 1) {
-        throw new Error("Cannot select multiple options: ComboBox only supports single selection");
-    }
+const getIndexSelector = (widget: Gtk.Widget): ((position: number) => void) | null =>
+    getCallableMethod<[number], unknown>(widget, "setSelected");
 
-    const [selection] = valueArray;
+const selectDropDownOption = (widget: Gtk.Widget, valueArray: number[]): void => {
+    const setSelected = getIndexSelector(widget);
 
-    if (selection === undefined) {
-        return;
+    if (!setSelected) {
+        throw new TypeError("Cannot select options: the COMBO_BOX role needs a widget exposing setSelected");
     }
 
-    if (widget instanceof Gtk.DropDown) {
-        widget.setSelected(selection);
-    } else if (widget instanceof Gtk.ComboBox) {
-        widget.setActive(selection);
+    if (valueArray.length > 1) {
+        throw new Error("Cannot select multiple options: a drop-down only supports single selection");
     }
-};
 
-const selectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.selectRow(row);
-    row.activate();
+    const [selection] = valueArray;
+
+    if (selection !== undefined) {
+        setSelected(selection);
+    }
 };
 
-const unselectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.unselectRow(row);
+const unselectChildRow = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    if (isChildSelected(child)) {
+        unselectContainerChild(container, child);
+    }
 };
 
-const applyListBoxRows = (listBox: Gtk.ListBox, valueArray: number[], apply: ListBoxRowAction): void => {
+const applyIndexedChildren = (widget: Gtk.Widget, valueArray: number[], apply: IndexedChildAction): void => {
     for (const value of valueArray) {
-        const row = listBox.getRowAtIndex(value);
+        const child = getChildAtIndex(widget, value);
 
-        if (!row) {
-            continue;
+        if (child) {
+            apply(widget, child);
         }
-
-        apply(listBox, row);
     }
 };
 
@@ -102,18 +112,29 @@ const selectInListView = (widget: CollectionWidget, valueArray: number[]): void
     selectListViewItems(selectionModel, valueArray, !isMultiSelection);
 };
 
-const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+const requireSelectableRole = (widget: Gtk.Widget, verb: string): void => {
     if (!isSelectable(widget)) {
-        throw new Error(`Cannot select options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`);
+        throw new Error(
+            `Cannot ${verb} options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`,
+        );
     }
+};
 
+const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+    requireSelectableRole(widget, "select");
     const role = widget.getAccessibleRole();
 
     if (role === Gtk.AccessibleRole.COMBO_BOX) {
-        selectComboBoxOption(widget, valueArray);
-    } else if (widget instanceof Gtk.ListBox) {
-        applyListBoxRows(widget, valueArray, selectListBoxRow);
+        selectDropDownOption(widget, valueArray);
+
+        return;
+    }
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot select options: the widget exposes no children to select by index");
     }
+
+    applyIndexedChildren(widget, valueArray, selectContainerChild);
 };
 
 const runSelectionEvent = (
@@ -136,11 +157,13 @@ const runSelectionEvent = (
 
 /**
  * Selects the items at the given positions through a list, grid, or column view's selection model,
- * by setting the active item of a drop-down or combo box, or by selecting list box rows. An empty
- * array clears a view's selection.
+ * by setting the selected position of a widget with the COMBO_BOX role, or by selecting the indexed
+ * children of a list box or flow box through their container. An empty array clears a view's
+ * selection. The children are never activated, so no row-activated handler runs.
  *
- * @throws When a view has no selection model, when a combo box is given more than one position, or
- * when the widget is neither a view nor something with the combo box or list role.
+ * @throws When a view has no selection model, when a COMBO_BOX-role widget is given more than one
+ * position or exposes no `setSelected`, or when the widget's role is none of COMBO_BOX, GRID, or
+ * LIST.
  */
 const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, selectInListView, selectByRole);
@@ -154,19 +177,22 @@ const deselectInListView = (widget: Gtk.ListView | Gtk.GridView | Gtk.ColumnView
 };
 
 const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (!(widget instanceof Gtk.ListBox)) {
-        throw new TypeError("Cannot deselect options: only ListBox supports deselection");
+    requireSelectableRole(widget, "deselect");
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot deselect options: the widget exposes no children to deselect by index");
     }
 
-    applyListBoxRows(widget, valueArray, unselectListBoxRow);
+    applyIndexedChildren(widget, valueArray, unselectChildRow);
 };
 
 /**
- * Unselects the items at the given positions in a list, grid, or column view, or the rows at those
- * indices in a Gtk.ListBox.
+ * Unselects the items at the given positions in a list, grid, or column view, or unselects the
+ * indexed children of a list box or flow box through their container. A child that is not selected
+ * is left alone, and no child is activated.
  *
- * @throws When a view has no selection model, or when the widget is neither one of those views nor
- * a Gtk.ListBox.
+ * @throws When a view has no selection model, when the widget's role is none of COMBO_BOX, GRID, or
+ * LIST, or when it exposes no indexed children.
  */
 const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, deselectInListView, deselectByRole);

package/src/user-event/text.ts

@@ -1,10 +1,17 @@
 import * as Gdk from "@gtkx/gi/gdk";
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable } from "../editable.js";
+import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable, readEditableText } from "../editable.js";
 import { formatRoleList } from "../role-helpers.js";
+import { getWidgetSelection } from "../widget-accessible-properties.js";
+import { callBooleanGetter } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
 
+type SignalWatchTarget = {
+    on(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): unknown;
+    off(signal: string, handler: (...args: unknown[]) => unknown): unknown;
+};
+
 /** Options for `userEvent.type`. */
 type TypeOptions = {
     /** Focus the widget before typing; defaults to true. */
@@ -16,6 +23,7 @@ type TypeOptions = {
 };
 
 const EDITABLE_REQUIRED = `expected editable widget (${formatRoleList(EDITABLE_ROLES)})`;
+const CLEAR_REFUSED = "Cannot clear element: the widget refuses to delete part of its text";
 
 const insertEditableText = (widget: EditableTarget, text: string): void => {
     if (widget instanceof Gtk.TextView) {
@@ -37,18 +45,7 @@ const insertEditableText = (widget: EditableTarget, text: string): void => {
     widget.setPosition(newPosition);
 };
 
-const readSelection = (widget: EditableTarget): string => {
-    if (widget instanceof Gtk.TextView) {
-        const buffer = widget.getBuffer();
-        const [hasSelection, start, end] = buffer.getSelectionBounds();
-
-        return hasSelection ? buffer.getText(start, end, true) : "";
-    }
-
-    const [hasSelection, start, end] = widget.getSelectionBounds();
-
-    return hasSelection ? widget.getChars(start, end) : "";
-};
+const readSelection = (widget: EditableTarget): string => getWidgetSelection(widget) ?? "";
 
 const deleteSelection = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
@@ -60,14 +57,15 @@ const deleteSelection = (widget: EditableTarget): void => {
     widget.deleteSelection();
 };
 
-const setEditableText = (widget: EditableTarget, text: string): void => {
+const deleteAllText = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
-        widget.getBuffer().setText(text, text.length);
+        const buffer = widget.getBuffer();
+        buffer.deleteInteractive(buffer.getStartIter(), buffer.getEndIter(), widget.getEditable());
 
         return;
     }
 
-    widget.setText(text);
+    widget.deleteText(0, -1);
 };
 
 const applyTextViewSelection = (widget: Gtk.TextView, start: number, end: number): void => {
@@ -147,15 +145,88 @@ const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<
         insertEditableText(editable, text);
     });
 
+const isWidgetEditable = (widget: Gtk.Widget): boolean => callBooleanGetter(widget, "getEditable") ?? true;
+
+const hasNonEditableChar = (iter: Gtk.TextIter, isDefaultEditable: boolean): boolean => {
+    while (!iter.isEnd()) {
+        if (!iter.editable(isDefaultEditable)) {
+            return true;
+        }
+
+        if (!iter.forwardChar()) {
+            return false;
+        }
+    }
+
+    return false;
+};
+
+const hasProtectedText = (widget: EditableTarget): boolean =>
+    widget instanceof Gtk.TextView && hasNonEditableChar(widget.getBuffer().getStartIter(), widget.getEditable());
+
+const requireClearableText = (editable: EditableTarget): void => {
+    if (!isWidgetEditable(editable)) {
+        throw new Error("Cannot clear element: the widget is not editable");
+    }
+
+    if (hasProtectedText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
+
+const deletionSignalFor = (widget: EditableTarget): [SignalWatchTarget, string] =>
+    widget instanceof Gtk.TextView ? [widget.getBuffer(), "delete-range"] : [widget, "delete-text"];
+
+const isDeletionApplied = (emitter: SignalWatchTarget, signal: string, apply: () => void): boolean => {
+    let isApplied = false;
+
+    const watch = (): void => {
+        isApplied = true;
+    };
+
+    emitter.on(signal, watch, true);
+
+    try {
+        apply();
+    } finally {
+        emitter.off(signal, watch);
+    }
+
+    return isApplied;
+};
+
+const didDeleteAllText = (widget: EditableTarget): boolean => {
+    const [emitter, signal] = deletionSignalFor(widget);
+
+    return isDeletionApplied(emitter, signal, () => {
+        deleteAllText(widget);
+    });
+};
+
+const clearEditable = (editable: EditableTarget): void => {
+    requireClearableText(editable);
+    editable.grabFocus();
+
+    if (readEditableText(editable) === "") {
+        return;
+    }
+
+    if (!didDeleteAllText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
+
 /**
- * Replaces an editable widget's text with the empty string.
+ * Focuses an editable widget and deletes its whole text through the widget's own editing API, so the
+ * deletion emits the signals an edit made by hand emits. Text a tag protects is detected before the
+ * deletion runs, leaving such a widget untouched. A widget that writes a new value back in response
+ * to the deletion, as an input mask does, is cleared successfully and keeps whatever it wrote.
  *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView, when it refuses edits, when
+ * a tag protects part of its text, or when a handler blocks the deletion.
  */
 const clear = (widget: Gtk.Widget): Promise<void> =>
-    runEditableEvent(widget, "Cannot clear element", (editable) => {
-        setEditableText(editable, "");
-    });
+    runEditableEvent(widget, "Cannot clear element", clearEditable);
 
 /**
  * Writes an editable widget's selected text to its clipboard, or the empty string when nothing is selected.