@twip/web 0.0.0 → 0.1.0-alpha.1

package/dist/Editor.d.ts

@@ -0,0 +1,773 @@
+// generated by diplomat-tool
+import type { AccessibleNode } from "./AccessibleNode"
+import type { Alignment } from "./Alignment"
+import type { BorderEdges } from "./BorderEdges"
+import type { BorderStyle } from "./BorderStyle"
+import type { Bytes } from "./Bytes"
+import type { CaretPosition } from "./CaretPosition"
+import type { CellAlignment } from "./CellAlignment"
+import type { CellShift } from "./CellShift"
+import type { Clipboard } from "./Clipboard"
+import type { ColumnSide } from "./ColumnSide"
+import type { ControlKind } from "./ControlKind"
+import type { ControlLock } from "./ControlLock"
+import type { DocumentStatus } from "./DocumentStatus"
+import type { EditorMode } from "./EditorMode"
+import type { ElementKind } from "./ElementKind"
+import type { ElementList } from "./ElementList"
+import type { ElementText } from "./ElementText"
+import type { EventList } from "./EventList"
+import type { Fonts } from "./Fonts"
+import type { Highlight } from "./Highlight"
+import type { MarginPreset } from "./MarginPreset"
+import type { MarkSeverity } from "./MarkSeverity"
+import type { Modifiers } from "./Modifiers"
+import type { Modifiers_obj } from "./Modifiers"
+import type { OpenError } from "./OpenError"
+import type { Orientation } from "./Orientation"
+import type { PageNumber } from "./PageNumber"
+import type { PaperSize } from "./PaperSize"
+import type { ParagraphBorders } from "./ParagraphBorders"
+import type { PictureWrap } from "./PictureWrap"
+import type { PointerKind } from "./PointerKind"
+import type { Rect } from "./Rect"
+import type { RequestList } from "./RequestList"
+import type { RowHeightRule } from "./RowHeightRule"
+import type { RowSide } from "./RowSide"
+import type { SaveError } from "./SaveError"
+import type { SelectionInfo } from "./SelectionInfo"
+import type { TableAlignment } from "./TableAlignment"
+import type { TableSelection } from "./TableSelection"
+import type { TableWidthUnit } from "./TableWidthUnit"
+import type { TextUnit } from "./TextUnit"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * An editor for one document: input, commands, saving and drawing.
+ */
+export class Editor {
+    /** @internal */
+    get ffiValue(): pointer;
+
+
+    /**
+     * Opens .docx bytes in place of the current document; on an error the current one stays.
+     */
+    open(bytes: Uint8Array | Array<number>): void;
+
+    /**
+     * The document as .docx bytes.
+     */
+    save(): Bytes;
+
+    /**
+     * The document as PDF, laid out completely first.
+     */
+    exportPdf(title: string): Bytes;
+
+    /**
+     * Pages laid out so far (layout continues in the background: see `idle`).
+     */
+    get pageCount(): number;
+
+    /**
+     * A summary for logs: pages and whether there are unsaved changes.
+     */
+    describe(): string;
+
+    /**
+     * Runs background layout for a while; true while there is more to do.
+     */
+    idle(): boolean;
+
+    /**
+     * A key press (DOM `KeyboardEvent.code` names, e.g. `KeyB`, `ArrowLeft`); true if the editor handled it.
+     */
+    key(code: string, mods: Modifiers_obj): boolean;
+
+    /**
+     * Text typed or composed (an IME's committed text).
+     */
+    text(text: string): void;
+
+    /**
+     * A pointer event at (`x`, `y`) content pixels; true if the editor wants the pointer captured.
+     */
+    pointer(kind: PointerKind, x: number, y: number, clicks: number, mods: Modifiers_obj): boolean;
+
+    /**
+     * The visible part of the content, in content pixels, and the device pixel ratio.
+     */
+    setViewport(left: number, top: number, width: number, height: number, dpr: number): void;
+
+    /**
+     * Zoom: 1.0 = 100% (a point is 96/72 pixels).
+     */
+    setZoom(zoom: number): void;
+
+    undo(): void;
+
+    redo(): void;
+
+    selectAll(): void;
+
+    /**
+     * Copies the selection; `cut` deletes it too. `None` when nothing is selected.
+     */
+    copy(cut: boolean): Clipboard | null;
+
+    /**
+     * Pastes: the content `token` names when it came from a Twip editor (`Clipboard.token`), else `text` as
+     * plain text.
+     */
+    paste(text: string, token: string): void;
+
+    /**
+     * Inserts a row above or below the selected rows.
+     */
+    insertRow(side: RowSide): void;
+
+    /**
+     * Inserts a column left or right of the selected columns.
+     */
+    insertColumn(side: ColumnSide): void;
+
+    /**
+     * Deletes the selected rows.
+     */
+    deleteRows(): void;
+
+    /**
+     * Deletes the selected columns.
+     */
+    deleteColumns(): void;
+
+    /**
+     * Deletes the table around the selection.
+     */
+    deleteTable(): void;
+
+    /**
+     * Deletes the selected cells, moving the remaining cells left or up.
+     */
+    deleteCells(shift: CellShift): void;
+
+    /**
+     * Merges the selected cells into one.
+     */
+    mergeCells(): void;
+
+    /**
+     * Splits the cell into `columns` cells side by side.
+     */
+    splitCell(columns: number): void;
+
+    /**
+     * Splits the cell into `rows` cells stacked vertically.
+     */
+    splitCellIntoRows(rows: number): void;
+
+    /**
+     * Selects the current cells, rows, columns or the whole table.
+     */
+    selectInTable(part: TableSelection): void;
+
+    /**
+     * Gives the selected columns equal widths.
+     */
+    distributeColumns(): void;
+
+    /**
+     * Gives the selected rows equal heights.
+     */
+    distributeRows(): void;
+
+    /**
+     * Sets the vertical alignment of text in the selected cells.
+     */
+    setCellAlignment(alignment: CellAlignment): void;
+
+    /**
+     * Turns repeating the header rows at the top of each page on or off for the selected rows.
+     */
+    toggleHeaderRow(): void;
+
+    /**
+     * Sets the borders on the given edges of the selected cells, with `width` in points and `color` as 0xRRGGBB (above 0xFFFFFF for automatic).
+     */
+    setCellBorders(edges: BorderEdges, style: BorderStyle, width: number, color: number): void;
+
+    /**
+     * Sets the inner margins of the selected cells, in points.
+     */
+    setCellMargins(top: number, left: number, bottom: number, right: number): void;
+
+    /**
+     * Sets the height of the selected rows, in points (ignored for `Auto`).
+     */
+    setRowHeight(height: number, rule: RowHeightRule): void;
+
+    /**
+     * Turns allowing the selected rows to break across pages on or off.
+     */
+    toggleRowBreakAcrossPages(): void;
+
+    /**
+     * Sets the width of the selected columns, in points.
+     */
+    setColumnWidth(width: number): void;
+
+    /**
+     * Sets the table's preferred width, in points or as a percentage (ignored for `Auto`).
+     */
+    setTableWidth(width: number, unit: TableWidthUnit): void;
+
+    /**
+     * Aligns the table horizontally on the page.
+     */
+    setTableAlignment(alignment: TableAlignment): void;
+
+    /**
+     * Sets the table's indent from the margin, in points.
+     */
+    setTableIndent(indent: number): void;
+
+    /**
+     * Applies the table style with this style id to the table.
+     */
+    setTableStyle(styleId: string): void;
+
+    /**
+     * Sets which parts of the table get the table style's special formatting.
+     */
+    setTableStyleOptions(headerRow: boolean, totalRow: boolean, firstColumn: boolean, lastColumn: boolean, bandedRows: boolean, bandedColumns: boolean): void;
+
+    /**
+     * Sets the fill colour of the selected cells as 0xRRGGBB, or removes it for a value above 0xFFFFFF.
+     */
+    setCellShading(color: number): void;
+
+    /**
+     * Shows or hides gridlines on table cells that have no borders.
+     */
+    setTableGridlines(show: boolean): void;
+
+    /**
+     * Deletes the selected picture.
+     */
+    deletePicture(): void;
+
+    /**
+     * Sets how text wraps around the selected floating picture.
+     */
+    setPictureWrap(wrap: PictureWrap): void;
+
+    /**
+     * Locks or unlocks the selected floating picture's anchor.
+     */
+    togglePictureAnchorLock(): void;
+
+    /**
+     * Returns the selected picture to its original size.
+     */
+    resetPictureSize(): void;
+
+    /**
+     * Sets the alternative text of the selected picture.
+     */
+    setPictureAltText(text: string): void;
+
+    /**
+     * Sets the size of the selected picture, in points (both must be positive).
+     */
+    setPictureSize(width: number, height: number): void;
+
+    /**
+     * Inserts a field with this code and result text at the caret, or right after element `after` (empty for the caret).
+     */
+    insertField(code: string, display: string, showCode: boolean, after: string): void;
+
+    /**
+     * Changes a field's code and result text; an empty string keeps that part as it is.
+     */
+    setField(id: string, code: string, display: string): void;
+
+    /**
+     * Inserts an empty field showing its code with the caret inside it, or turns the selected text into a field code.
+     */
+    insertEmptyField(): void;
+
+    /**
+     * Asks the host to update field `id` and the fields inside it, or the fields at the selection when `id` is empty.
+     */
+    updateFields(id: string): void;
+
+    /**
+     * Sets the result text of field `id` after the host computed it.
+     */
+    setFieldResult(id: string, display: string): void;
+
+    /**
+     * Locks or unlocks field `id` and the fields inside it, or the fields at the selection when `id` is empty.
+     */
+    setFieldsLocked(id: string, locked: boolean): void;
+
+    /**
+     * Replaces field `id`, or the fields at the selection when `id` is empty, with its result text.
+     */
+    unlinkFields(id: string): void;
+
+    /**
+     * Sets the label shown in design mode for empty fields with this code; `replace_all` drops the other labels first, and an empty `code` with `replace_all` clears them all.
+     */
+    setFieldLabel(code: string, label: string, replaceAll: boolean): void;
+
+    /**
+     * Removes a field or content control together with its content.
+     */
+    removeElement(id: string): void;
+
+    /**
+     * Selects a field or content control, scrolling it into view when `reveal` is true.
+     */
+    selectElement(id: string, reveal: boolean): void;
+
+    /**
+     * Marks an element with a severity and a tooltip message; `clear_others` removes the other marks first, and an empty `id` with it clears all marks.
+     */
+    markElement(id: string, severity: MarkSeverity, message: string, clearOthers: boolean): void;
+
+    /**
+     * Replaces text in field codes or control tags or titles, in element `id` only or in all of them when `id` is empty.
+     */
+    replaceInElements(find: string, replace: string, within: ElementText, kind: ElementKind, id: string): void;
+
+    /**
+     * Inserts a content control at the caret or after element `after`, or around the selection with `wrap_selection` (rich text and group only); empty strings use the defaults.
+     */
+    insertControl(kind: ControlKind, tag: string, alias: string, placeholder: string, lock: ControlLock, binding: string, wrapSelection: boolean, multiLine: boolean, checked: boolean, dateFormat: string, after: string): void;
+
+    /**
+     * Changes a content control's tag, title, data binding, placeholder text and lock; empty strings and `Unchanged` keep what it has.
+     */
+    setControl(id: string, tag: string, alias: string, binding: string, placeholder: string, lock: ControlLock): void;
+
+    /**
+     * Removes a content control, keeping its content in the document when `keep_content` is true.
+     */
+    removeControl(id: string, keepContent: boolean): void;
+
+    /**
+     * Replaces the content of a plain-text, date or rich-text control with this text.
+     */
+    fillControl(id: string, text: string): void;
+
+    /**
+     * Wraps the selected table rows or paragraphs in a new repeating section, with an optional tag and title (empty for none).
+     */
+    wrapInRepeatingSection(tag: string, alias: string): void;
+
+    /**
+     * Writes an XML data part whose root is in `namespace`, replacing the part with that namespace (and `item_id` when not empty) or adding a new one.
+     */
+    writeDataPart(namespace: string, itemId: string, xml: string): void;
+
+    /**
+     * Removes the XML data part with this namespace (and `item_id` when not empty).
+     */
+    removeDataPart(namespace: string, itemId: string): void;
+
+    /**
+     * Toggles bold on the selection (or the next typed text).
+     */
+    bold(): void;
+
+    /**
+     * Toggles italic on the selection (or the next typed text).
+     */
+    italic(): void;
+
+    /**
+     * Toggles a single underline on the selection (or the next typed text).
+     */
+    underline(): void;
+
+    /**
+     * Toggles strikethrough on the selection (or the next typed text).
+     */
+    strikethrough(): void;
+
+    /**
+     * Toggles subscript on the selection (or the next typed text).
+     */
+    subscript(): void;
+
+    /**
+     * Toggles superscript on the selection (or the next typed text).
+     */
+    superscript(): void;
+
+    /**
+     * Sets the font family of the selection (or the next typed text).
+     */
+    setFont(family: string): void;
+
+    /**
+     * Sets the font size of the selection (or the next typed text), rounded to the nearest half point.
+     */
+    setFontSize(points: number): void;
+
+    /**
+     * Makes the selected text one step larger in the standard font size list.
+     */
+    growFont(): void;
+
+    /**
+     * Makes the selected text one step smaller in the standard font size list.
+     */
+    shrinkFont(): void;
+
+    /**
+     * Sets the text colour of the selection (or the next typed text).
+     */
+    setFontColor(color: number): void;
+
+    /**
+     * Gives the selection (or the next typed text) the automatic text colour.
+     */
+    setFontColorAutomatic(): void;
+
+    /**
+     * Highlights the selection (or the next typed text) in a colour, or removes the highlight.
+     */
+    setHighlight(color: Highlight): void;
+
+    /**
+     * Removes the direct character formatting from the selection.
+     */
+    clearFormatting(): void;
+
+    /**
+     * Applies a paragraph style to the selected paragraphs; nothing happens if the document has no such style.
+     */
+    setStyle(styleId: string): void;
+
+    /**
+     * Toggles a bulleted list on the selected paragraphs.
+     */
+    bullets(): void;
+
+    /**
+     * Toggles a numbered list on the selected paragraphs.
+     */
+    numbering(): void;
+
+    /**
+     * Moves the selected paragraphs' left indent in by half an inch.
+     */
+    increaseIndent(): void;
+
+    /**
+     * Moves the selected paragraphs' left indent out by half an inch, not below zero.
+     */
+    decreaseIndent(): void;
+
+    /**
+     * Aligns the selected paragraphs.
+     */
+    setAlignment(alignment: Alignment): void;
+
+    /**
+     * Sets the selected paragraphs' line spacing as a multiple of single spacing.
+     */
+    setLineSpacing(multiple: number): void;
+
+    /**
+     * Adds 12 points of space before the selected paragraphs, or removes it when the first one already has some.
+     */
+    toggleSpaceBefore(): void;
+
+    /**
+     * Removes the space after the selected paragraphs.
+     */
+    removeSpaceAfter(): void;
+
+    /**
+     * Toggles keeping the selected paragraphs on the same page as the next one.
+     */
+    keepWithNext(): void;
+
+    /**
+     * Sets the borders of the selected paragraphs.
+     */
+    setParagraphBorders(borders: ParagraphBorders): void;
+
+    /**
+     * Fills the background of the selected paragraphs with a colour.
+     */
+    setParagraphShading(color: number): void;
+
+    /**
+     * Removes the background colour of the selected paragraphs.
+     */
+    clearParagraphShading(): void;
+
+    /**
+     * Ends the paragraph at the caret and starts a new one, as pressing Enter does.
+     */
+    insertParagraph(): void;
+
+    /**
+     * Inserts a tab character at the caret.
+     */
+    insertTab(): void;
+
+    /**
+     * Redoes the last undone change, or else repeats the last edit at the selection.
+     */
+    repeat(): void;
+
+    /**
+     * Selects the word, sentence or paragraph at the caret.
+     */
+    select(unit: TextUnit): void;
+
+    /**
+     * Selects text within one paragraph and scrolls it into view.
+     */
+    selectRange(paragraph: bigint, start: number, end: number): void;
+
+    /**
+     * Replaces every occurrence of a text in the document body, as one undo step.
+     */
+    replaceAll(find: string, replacement: string, matchCase: boolean): void;
+
+    /**
+     * Inserts an empty table at the caret.
+     */
+    insertTable(rows: number, cols: number): void;
+
+    /**
+     * Inserts a picture at the caret at its own size, scaled down to the text width if wider, and selects it.
+     */
+    insertPicture(image: Uint8Array | Array<number>): void;
+
+    /**
+     * Inserts a 2 x 1 inch text box in front of the text at the caret and puts the caret in it.
+     */
+    insertTextBox(): void;
+
+    /**
+     * Inserts an unchecked checkbox content control at the caret.
+     */
+    insertCheckbox(): void;
+
+    /**
+     * Inserts a symbol character at the caret, optionally in a given font.
+     */
+    insertSymbol(symbol: string, font: string): void;
+
+    /**
+     * Inserts a footnote reference at the caret and moves the caret to the new note's text.
+     */
+    insertFootnote(): void;
+
+    /**
+     * Inserts an endnote reference at the caret and moves the caret to the new note's text.
+     */
+    insertEndnote(): void;
+
+    /**
+     * Inserts a page number field at the caret (in a header, footer or the body).
+     */
+    insertPageNumber(kind: PageNumber): void;
+
+    /**
+     * Inserts a page break at the caret.
+     */
+    insertPageBreak(): void;
+
+    /**
+     * Inserts a column break at the caret.
+     */
+    insertColumnBreak(): void;
+
+    /**
+     * Inserts a line break at the caret, starting a new line in the same paragraph.
+     */
+    insertLineBreak(): void;
+
+    /**
+     * Sets the page margins of the current section to a preset.
+     */
+    setMargins(preset: MarginPreset): void;
+
+    /**
+     * Turns the current section's pages to portrait or landscape, turning the margins with them.
+     */
+    setOrientation(orientation: Orientation): void;
+
+    /**
+     * Sets the paper size of the current section, keeping its orientation.
+     */
+    setPaperSize(size: PaperSize): void;
+
+    /**
+     * Lays out the current section in equal-width text columns.
+     */
+    setColumns(count: number): void;
+
+    /**
+     * Moves the caret into the current page's header, creating an empty one if there is none.
+     */
+    editHeader(): void;
+
+    /**
+     * Moves the caret into the current page's footer, creating an empty one if there is none.
+     */
+    editFooter(): void;
+
+    /**
+     * Leaves the header or footer and returns the caret to the body.
+     */
+    closeHeaderFooter(): void;
+
+    /**
+     * Toggles a different header and footer on the first page of the current section.
+     */
+    differentFirstPage(): void;
+
+    /**
+     * Switches between editing, template design and read-only viewing.
+     */
+    setMode(mode: EditorMode): void;
+
+    /**
+     * Zooms in by 10%, up to 400%.
+     */
+    zoomIn(): void;
+
+    /**
+     * Zooms out by 10%, down to 25%.
+     */
+    zoomOut(): void;
+
+    /**
+     * Sets how placeholders with a given key are drawn: a fill colour, a label and an icon.
+     */
+    setPlaceholderLook(key: string, color: number, label: string, iconSvg: string): void;
+
+    /**
+     * Restores the default look of placeholders with a given key.
+     */
+    clearPlaceholderLook(key: string): void;
+
+    /**
+     * Toggles code view for every field (`all`) or for the fields at the caret.
+     */
+    toggleFieldCodes(all: boolean): void;
+
+    /**
+     * Shows every field's code (`true`) or its result (`false`).
+     */
+    showFieldCodes(show: boolean): void;
+
+    /**
+     * Shows the drop caret where a dragged item would land, at (`x`, `y`) content pixels.
+     */
+    setDropCaret(x: number, y: number): void;
+
+    /**
+     * Hides the drop caret.
+     */
+    clearDropCaret(): void;
+
+    /**
+     * The status bar's numbers.
+     */
+    status(): DocumentStatus;
+
+    /**
+     * The selection.
+     */
+    selection(): SelectionInfo;
+
+    /**
+     * The document's reading structure, for assistive technology.
+     */
+    accessibleTree(): AccessibleNode;
+
+    /**
+     * The fields and content controls in document order; `kind` filters (`field`, `plain_text`, ...; empty for
+     * all).
+     */
+    elements(kind: string): ElementList;
+
+    /**
+     * What the editor asked of the host since the last call (scroll, cursor, clipboard, ...). Call after inputs.
+     */
+    takeRequests(): RequestList;
+
+    /**
+     * What happened that the application may act on since the last call.
+     */
+    takeEvents(): EventList;
+
+    /**
+     * As `paint`, into a new buffer (JavaScript can't lend one). `None` for an empty size.
+     */
+    paint(width: number, height: number, originX: number, originY: number, dpr: number): Bytes | null;
+
+    /**
+     * Browser: a WebGPU instance handle for `Module.WebGPU.importJsDevice` / `importJsQueue` (see the web
+     * package's `attachWebGpu` helper).
+     */
+    static webgpuInstance(): number;
+
+    /**
+     * Browser: adopts the page's WebGPU device for every editor (imported device and queue handles, and the
+     * instance from `webgpu_instance`). False when it can't be used: paint with WebGL instead.
+     */
+    static attachWebgpu(instance: number, device: number, queue: number): boolean;
+
+    /**
+     * Browser: paints the pages under the viewport into a WebGPU canvas texture (a handle from
+     * `importJsTexture`, released here); `height` is the texture's height in pixels. False if nothing was drawn.
+     */
+    paintWebgpu(texture: number, bgra: boolean, originX: number, originY: number, height: number, dpr: number): boolean;
+
+    /**
+     * Browser: adopts the current WebGL 2 context (made current with `Module.GL.makeContextCurrent`) for this
+     * editor's canvas.
+     */
+    attachWebgl(): boolean;
+
+    /**
+     * Browser: paints the pages under the viewport into this editor's WebGL canvas (`width` x `height` device
+     * pixels, its context current).
+     */
+    paintWebgl(originX: number, originY: number, width: number, height: number, dpr: number): boolean;
+
+    /**
+     * The caret, content pixels.
+     */
+    caret(): CaretPosition;
+
+    /**
+     * The size of all pages stacked with their gaps, content pixels (what the host scrolls).
+     */
+    contentSize(): Rect;
+
+    /**
+     * Fills the selected placeholder (`key` empty) or every unfilled one with `key`, with an image file's bytes;
+     * how many were filled.
+     */
+    fillPlaceholder(key: string, image: Uint8Array | Array<number>): number;
+
+    /**
+     * An editor holding a new, empty US Letter document.
+     */
+    constructor(fonts: Fonts);
+}