@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.10

package/types/src/movable/IFormControl.d.ts

@@ -0,0 +1,455 @@
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+import { ICellRange } from '../cellRange';
+import { IMovable } from './IMovable';
+/**
+ * What every form control shares — a button, a check box, a scroll bar placed on a sheet.
+ *
+ * @remarks
+ * A form control is a movable whose content is one of Excel's legacy controls: the movable places
+ * it and the content models what it is. Each kind is its own content type
+ * ({@link IFormControl.Type}) and its own interface, composed from this and two facets: the kinds
+ * that show text ({@link ICaptioned}) and the kinds that hold a value a cell can mirror
+ * ({@link ILinked}). A control owns its state — a check box with no linked cell is still checked
+ * or not.
+ *
+ * **PLACEHOLDER** - This is under development and not made public yet.
+ */
+export interface IFormControl extends IModel, IMovable.IContent {
+    /**
+     * Returns the id of the shape that draws this control, or `null` if it has none.
+     *
+     * @remarks
+     * The link to the shape in the sheet's legacy drawing, which is what keeps the two over the same
+     * cells when rows and columns move.
+     */
+    getShapeId(): number | null;
+    /**
+     * Returns the name of the macro the control runs when used, or `null` if it has none.
+     *
+     * @remarks
+     * Any kind may run one: a button when clicked, a check box when toggled, a scroll bar when moved.
+     */
+    getMacro(): string | null;
+    /**
+     * Sets the name of the macro the control runs when used.
+     *
+     * @param macro The name, or `null` for none.
+     */
+    setMacro(macro: string | null, options?: ITransaction.OperationOptions): this;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IFormControl.JSON | null;
+    /**
+     * Deletes the control, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /** For runtime type checking. */
+    readonly isIFormControl: true;
+}
+/**
+ * {@inheritDoc IFormControl}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFormControl}
+ */
+export declare namespace IFormControl {
+    /**
+     * The kinds of form control, which are the content types a movable reports for them.
+     */
+    const Type: {
+        /** {@link IButton}: runs its macro when clicked. */
+        readonly Button: "button";
+        /** {@link ICheckBox}: on, off or mixed; writes a boolean to its linked cell. */
+        readonly CheckBox: "checkBox";
+        /** {@link IOptionButton}: one of a group; the group's linked cell holds the chosen index. */
+        readonly OptionButton: "optionButton";
+        /** {@link IListBox}: a list of items; writes the index of the chosen one. */
+        readonly ListBox: "listBox";
+        /** {@link IDropDown}: a list that drops down; writes the index of the chosen one. */
+        readonly DropDown: "dropDown";
+        /** {@link IScrollBar}: a thumb in a trough; writes a number. */
+        readonly ScrollBar: "scrollBar";
+        /** {@link ISpinner}: two arrows; writes a number. */
+        readonly Spinner: "spinner";
+        /** {@link IGroupBox}: a frame around other controls. */
+        readonly GroupBox: "groupBox";
+        /** {@link ILabel}: text, nothing more. */
+        readonly Label: "label";
+        /** A text field. Dialog sheets only. {@link IFormControl} only. */
+        readonly EditBox: "editBox";
+        /** A dialog frame. Dialog sheets only. {@link IFormControl} only. */
+        readonly Dialog: "dialog";
+        /** A kind this version does not know. {@link IFormControl} only. */
+        readonly Unknown: "formControl";
+    };
+    type Type = typeof Type[keyof typeof Type];
+    /**
+     * What every kind saves. Each facet and each kind adds its own fields.
+     */
+    interface JSON {
+        /**
+         * The id of the shape that draws this control.
+         *
+         * @see {@link IFormControl.getShapeId}
+         */
+        shapeId?: number;
+        /**
+         * The name of the macro the control runs when used.
+         */
+        macro?: string;
+        /**
+         * The control's placement properties as the file spelled them, less the ones modeled and the
+         * anchor, which is the movable's own.
+         *
+         * @remarks
+         * Whether it prints, whether it is locked, how it sizes with its cell. Carried so a file keeps
+         * what it said until each has a model.
+         */
+        props?: Record<string, string>;
+        /**
+         * The control's own properties as the file spelled them, less the ones modeled.
+         *
+         * @remarks
+         * The 3-D look, text locking, the width of a drop-down's arrow. Carried so a file keeps what
+         * it said until each has a model.
+         */
+        formProps?: Record<string, string>;
+        /**
+         * Anything a producer wrote inside the placement properties besides the anchor, as markup.
+         * Empty for every file seen so far.
+         */
+        xml?: string;
+        /**
+         * Extensions a producer wrote on the control's own properties, as markup.
+         */
+        extLst?: string;
+    }
+    interface Events extends IModel.Events {
+    }
+    interface IListeners extends IListener.Callbacks<IFormControl, IFormControl.Events> {
+    }
+}
+/**
+ * A control that shows text: a button's label, the text beside a check box, a group box's title.
+ */
+export interface ICaptioned {
+    /**
+     * Returns the text written on the control, or `null` if it has none.
+     */
+    getCaption(): string | null;
+    /**
+     * Sets the text written on the control.
+     *
+     * @param caption The text, or `null` for none.
+     */
+    setCaption(caption: string | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the font the caption is drawn in, or `null` when the control has not said.
+     */
+    getFont(): ICaptioned.Font | null;
+}
+export declare namespace ICaptioned {
+    /**
+     * The font a caption is drawn in. Every field is optional; one the control has not said is the
+     * host's default.
+     */
+    interface Font {
+        /** The family name. */
+        name?: string;
+        /** The size in points. */
+        size?: number;
+        /** @defaultValue false */
+        bold?: boolean;
+        /** @defaultValue false */
+        italic?: boolean;
+        /** A hex color (`#RRGGBB`). */
+        color?: string;
+    }
+    interface JSON {
+        /** The text written on the control. */
+        caption?: string;
+        /** The font the caption is drawn in. */
+        font?: Font;
+    }
+}
+/**
+ * A control that can be linked to a cell. A linked control's state is the cell's: it reads the
+ * cell, and setting its state writes the cell.
+ */
+export interface ILinked {
+    /**
+     * Returns the address of the cell the control's state lives in, or `null` if it has none.
+     *
+     * @remarks
+     * It follows the cell through inserts, deletes and moves, and reads `#REF!` once the cell is
+     * deleted. A cell on the control's own sheet has no sheet name (`$A$1`); one on another sheet
+     * has its sheet's (`Data!$A$1`).
+     */
+    getLinkedCell(): string | null;
+    /**
+     * Returns the cell the control's state lives in, or `null` if it has none or it no longer
+     * exists.
+     */
+    getLinkedRange(): ICellRange | null;
+    /**
+     * Sets the cell the control writes its state to.
+     *
+     * @param address The address, or `null` for none.
+     */
+    setLinkedCell(address: string | null, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace ILinked {
+    interface JSON {
+        /** The address of the cell the control writes its state to. */
+        linkedCell?: string;
+    }
+}
+/**
+ * A button: runs its macro when clicked. Content type `'button'`.
+ */
+export interface IButton extends IFormControl, ICaptioned {
+}
+export declare namespace IButton {
+    interface JSON extends IFormControl.JSON, ICaptioned.JSON {
+    }
+}
+/**
+ * A check box: on, off or mixed. Content type `'checkBox'`.
+ */
+export interface ICheckBox extends IFormControl, ICaptioned, ILinked {
+    /**
+     * Returns `true` if the box is checked.
+     */
+    isChecked(): boolean;
+    /**
+     * Sets whether the box is checked. Clears {@link isMixed}.
+     */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns `true` if the box shows the mixed (neither) state.
+     */
+    isMixed(): boolean;
+    /**
+     * Sets whether the box shows the mixed state.
+     */
+    setMixed(mixed: boolean, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace ICheckBox {
+    interface JSON extends IFormControl.JSON, ICaptioned.JSON, ILinked.JSON {
+        /**
+         * `true` if the box is checked.
+         * @defaultValue false
+         */
+        checked?: boolean;
+        /**
+         * `true` if the box shows the mixed state. Wins over `checked`.
+         * @defaultValue false
+         */
+        mixed?: boolean;
+    }
+}
+/**
+ * An option button: one of a group, of which one is chosen. Content type `'optionButton'`.
+ */
+export interface IOptionButton extends IFormControl, ICaptioned, ILinked {
+    /**
+     * Returns `true` if this is the chosen button of its group.
+     */
+    isChecked(): boolean;
+    /**
+     * Sets whether this is the chosen button of its group.
+     */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace IOptionButton {
+    interface JSON extends IFormControl.JSON, ICaptioned.JSON, ILinked.JSON {
+        /**
+         * `true` if this is the chosen button of its group.
+         * @defaultValue false
+         */
+        checked?: boolean;
+    }
+}
+/**
+ * A group box: a frame around other controls. Content type `'groupBox'`.
+ */
+export interface IGroupBox extends IFormControl, ICaptioned {
+}
+export declare namespace IGroupBox {
+    interface JSON extends IFormControl.JSON, ICaptioned.JSON {
+    }
+}
+/**
+ * A label: text, nothing more. Content type `'label'`.
+ */
+export interface ILabel extends IFormControl, ICaptioned {
+}
+export declare namespace ILabel {
+    interface JSON extends IFormControl.JSON, ICaptioned.JSON {
+    }
+}
+/**
+ * What a scroll bar and a spinner share: a number between two bounds.
+ */
+export interface IRangedControl extends IFormControl, ILinked {
+    /** Returns the current value, or `null` if the control has not said. */
+    getValue(): number | null;
+    /** Sets the current value. */
+    setValue(value: number | null, options?: ITransaction.OperationOptions): this;
+    /** Returns the smallest value, or `null` if the control has not said. */
+    getMin(): number | null;
+    /** Sets the smallest value. */
+    setMin(min: number | null, options?: ITransaction.OperationOptions): this;
+    /** Returns the largest value, or `null` if the control has not said. */
+    getMax(): number | null;
+    /** Sets the largest value. */
+    setMax(max: number | null, options?: ITransaction.OperationOptions): this;
+    /** Returns how far one arrow click moves the value, or `null` if the control has not said. */
+    getIncrement(): number | null;
+    /** Sets how far one arrow click moves the value. */
+    setIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace IRangedControl {
+    interface JSON extends IFormControl.JSON, ILinked.JSON {
+        /** The current value. */
+        value?: number;
+        /** The smallest value. */
+        min?: number;
+        /** The largest value. */
+        max?: number;
+        /** How far one arrow click moves the value. */
+        increment?: number;
+    }
+}
+/**
+ * A scroll bar: a thumb in a trough. Content type `'scrollBar'`.
+ */
+export interface IScrollBar extends IRangedControl {
+    /** Returns how far a click in the trough moves the value, or `null` if the control has not said. */
+    getPageIncrement(): number | null;
+    /** Sets how far a click in the trough moves the value. */
+    setPageIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns `true` if the bar lies on its side.
+     *
+     * @remarks
+     * Decided by its shape, as Excel decides it: wider than tall is horizontal, and a resize
+     * decides again. There is no setter; resize the movable.
+     */
+    isHorizontal(): boolean;
+}
+export declare namespace IScrollBar {
+    interface JSON extends IRangedControl.JSON {
+        /** How far a click in the trough moves the value. */
+        pageIncrement?: number;
+        /**
+         * `true` if the bar lies on its side.
+         * @defaultValue false
+         */
+        horizontal?: boolean;
+    }
+}
+/**
+ * A spinner: two arrows. Content type `'spinner'`.
+ */
+export interface ISpinner extends IRangedControl {
+}
+export declare namespace ISpinner {
+    interface JSON extends IRangedControl.JSON {
+    }
+}
+/**
+ * What a list box and a drop-down share: items, one of which may be chosen.
+ */
+export interface IListControl extends IFormControl, ILinked {
+    /**
+     * Returns the items.
+     *
+     * @remarks
+     * Empty when the items come from {@link getListFillRange} rather than being held by the control.
+     */
+    getItems(): readonly string[];
+    /** Sets the items. */
+    setItems(items: readonly string[], options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the items the control shows: the values of its fill range when it has one, else its
+     * own items.
+     *
+     * @remarks
+     * A fill range is read down its first column, as shown, to its last cell with a value and at
+     * most 32,767 items (Excel's limit).
+     */
+    getListItems(): readonly string[];
+    /**
+     * Returns the address of the range the items come from, or `null` if the control holds them.
+     *
+     * @remarks
+     * It follows the range through inserts, deletes and moves, as {@link ILinked.getLinkedCell}
+     * does.
+     */
+    getListFillRange(): string | null;
+    /** Returns the range the items come from, or `null` if there is none or it no longer exists. */
+    getListSourceRange(): ICellRange | null;
+    /** Sets the range the items come from. */
+    setListFillRange(address: string | null, options?: ITransaction.OperationOptions): this;
+    /** Returns the index of the chosen item, or `null` if none is. */
+    getSelectedIndex(): number | null;
+    /** Sets the chosen item. */
+    setSelectedIndex(index: number | null, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace IListControl {
+    interface JSON extends IFormControl.JSON, ILinked.JSON {
+        /** The items held by the control itself. */
+        items?: string[];
+        /** The address of the range the items come from. */
+        listFillRange?: string;
+        /** The index of the chosen item. Absent when none is. */
+        selectedIndex?: number;
+    }
+}
+/**
+ * A list box. Content type `'listBox'`.
+ */
+export interface IListBox extends IListControl {
+}
+export declare namespace IListBox {
+    interface JSON extends IListControl.JSON {
+    }
+}
+/**
+ * A drop-down. Content type `'dropDown'`.
+ */
+export interface IDropDown extends IListControl {
+    /**
+     * Returns how the drop-down behaves: a list to pick from, a list that can also be typed into, or
+     * a plain list box. `null` if the control has not said.
+     */
+    getDropStyle(): IDropDown.DropStyle | null;
+    /**
+     * Returns how many items the drop-down shows at once, or `null` if the control has not said.
+     */
+    getDropLines(): number | null;
+}
+export declare namespace IDropDown {
+    /**
+     * How a drop-down behaves.
+     */
+    const DropStyle: {
+        /** A list to pick from. */
+        readonly Combo: "combo";
+        /** A list that can also be typed into. */
+        readonly ComboEdit: "comboEdit";
+        /** A list box that does not drop. */
+        readonly Simple: "simple";
+    };
+    type DropStyle = typeof DropStyle[keyof typeof DropStyle];
+    interface JSON extends IListControl.JSON {
+        /** How the drop-down behaves. */
+        dropStyle?: DropStyle;
+        /** How many items the drop-down shows at once. */
+        dropLines?: number;
+    }
+}
+//# sourceMappingURL=IFormControl.d.ts.map