@sheetxl/sdk 0.8.0-beta.7 → 0.8.0-beta.9

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

@@ -0,0 +1,206 @@
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { IFormControl, ICaptioned, ILinked, IButton, ICheckBox, IOptionButton, IGroupBox, ILabel, IRangedControl, IScrollBar, ISpinner, IListControl, IListBox, IDropDown } from './IFormControl';
+import { AbstractMovableContent } from './AbstractMovableContent';
+interface State<J extends IFormControl.JSON> extends AbstractMovableContent.State {
+    data?: J;
+}
+/**
+ * Implementation for {@link IFormControl}: what every kind shares. On its own it is the kinds with
+ * nothing of their own (edit box, dialog, and a kind this version does not know), told apart by
+ * the type they are created with.
+ */
+export declare class FormControl<J extends IFormControl.JSON = IFormControl.JSON> extends AbstractMovableContent<State<J>, J> implements IFormControl {
+    private readonly _type;
+    private readonly _typeDescription;
+    constructor(options: FormControl.ConstructorOptions<J>);
+    /** {@inheritDoc IModel.getType} */
+    getType(): string;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    getTypeDescription(): string;
+    /** {@inheritDoc IFormControl.getShapeId} */
+    getShapeId(): number | null;
+    /** {@inheritDoc IFormControl.getMacro} */
+    getMacro(): string | null;
+    /** {@inheritDoc IFormControl.setMacro} */
+    setMacro(macro: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc Movable.Content.toJSON} */
+    toJSON(_toResourceId?: (resource: IResource) => number | null): J | null;
+    /** {@inheritDoc IFormControl.isIFormControl} */
+    get isIFormControl(): true;
+    protected _data(): J | null;
+    /**
+     * Writes fields into the control's data as one operation. A field set to `undefined` is
+     * removed, so the JSON only ever says what differs from the default.
+     */
+    protected _set(fields: Partial<J>, message: string, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * The kinds that show text ({@link ICaptioned}): a button, a group box, a label.
+ */
+export declare abstract class CaptionedControl<J extends IFormControl.JSON & ICaptioned.JSON> extends FormControl<J> implements ICaptioned {
+    /** {@inheritDoc ICaptioned.getCaption} */
+    getCaption(): string | null;
+    /** {@inheritDoc ICaptioned.setCaption} */
+    setCaption(caption: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICaptioned.getFont} */
+    getFont(): ICaptioned.Font | null;
+}
+/**
+ * The kinds a cell mirrors ({@link ILinked}) that show no text: scroll bars, spinners, lists.
+ */
+export declare abstract class LinkedControl<J extends IFormControl.JSON & ILinked.JSON> extends FormControl<J> implements ILinked {
+    /** {@inheritDoc ILinked.getLinkedCell} */
+    getLinkedCell(): string | null;
+    /** {@inheritDoc ILinked.setLinkedCell} */
+    setLinkedCell(address: string | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * The kinds that both show text and are mirrored by a cell: a check box, an option button.
+ */
+export declare abstract class CaptionedLinkedControl<J extends IFormControl.JSON & ICaptioned.JSON & ILinked.JSON> extends CaptionedControl<J> implements ILinked {
+    /** {@inheritDoc ILinked.getLinkedCell} */
+    getLinkedCell(): string | null;
+    /** {@inheritDoc ILinked.setLinkedCell} */
+    setLinkedCell(address: string | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IButton}.
+ */
+export declare class Button extends CaptionedControl<IButton.JSON> implements IButton {
+    constructor(options: FormControl.KindOptions<IButton.JSON>);
+}
+/**
+ * Implementation for {@link IGroupBox}.
+ */
+export declare class GroupBox extends CaptionedControl<IGroupBox.JSON> implements IGroupBox {
+    constructor(options: FormControl.KindOptions<IGroupBox.JSON>);
+}
+/**
+ * Implementation for {@link ILabel}.
+ */
+export declare class Label extends CaptionedControl<ILabel.JSON> implements ILabel {
+    constructor(options: FormControl.KindOptions<ILabel.JSON>);
+}
+/**
+ * Implementation for {@link ICheckBox}.
+ */
+export declare class CheckBox extends CaptionedLinkedControl<ICheckBox.JSON> implements ICheckBox {
+    constructor(options: FormControl.KindOptions<ICheckBox.JSON>);
+    /** {@inheritDoc ICheckBox.isChecked} */
+    isChecked(): boolean;
+    /** {@inheritDoc ICheckBox.setChecked} */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICheckBox.isMixed} */
+    isMixed(): boolean;
+    /** {@inheritDoc ICheckBox.setMixed} */
+    setMixed(mixed: boolean, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IOptionButton}.
+ */
+export declare class OptionButton extends CaptionedLinkedControl<IOptionButton.JSON> implements IOptionButton {
+    constructor(options: FormControl.KindOptions<IOptionButton.JSON>);
+    /** {@inheritDoc IOptionButton.isChecked} */
+    isChecked(): boolean;
+    /** {@inheritDoc IOptionButton.setChecked} */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * What {@link ScrollBar} and {@link Spinner} share.
+ */
+export declare abstract class RangedControl<J extends IRangedControl.JSON> extends LinkedControl<J> implements IRangedControl {
+    /** {@inheritDoc IRangedControl.getValue} */
+    getValue(): number | null;
+    /** {@inheritDoc IRangedControl.setValue} */
+    setValue(value: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IRangedControl.getMin} */
+    getMin(): number | null;
+    /** {@inheritDoc IRangedControl.setMin} */
+    setMin(min: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IRangedControl.getMax} */
+    getMax(): number | null;
+    /** {@inheritDoc IRangedControl.setMax} */
+    setMax(max: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IRangedControl.getIncrement} */
+    getIncrement(): number | null;
+    /** {@inheritDoc IRangedControl.setIncrement} */
+    setIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IScrollBar}.
+ */
+export declare class ScrollBar extends RangedControl<IScrollBar.JSON> implements IScrollBar {
+    constructor(options: FormControl.KindOptions<IScrollBar.JSON>);
+    /** {@inheritDoc IScrollBar.getPageIncrement} */
+    getPageIncrement(): number | null;
+    /** {@inheritDoc IScrollBar.setPageIncrement} */
+    setPageIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IScrollBar.isHorizontal} */
+    isHorizontal(): boolean;
+}
+/**
+ * Implementation for {@link ISpinner}.
+ */
+export declare class Spinner extends RangedControl<ISpinner.JSON> implements ISpinner {
+    constructor(options: FormControl.KindOptions<ISpinner.JSON>);
+}
+/**
+ * What {@link ListBox} and {@link DropDown} share.
+ */
+export declare abstract class ListControl<J extends IListControl.JSON> extends LinkedControl<J> implements IListControl {
+    /** {@inheritDoc IListControl.getItems} */
+    getItems(): readonly string[];
+    /** {@inheritDoc IListControl.setItems} */
+    setItems(items: readonly string[], options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IListControl.getListFillRange} */
+    getListFillRange(): string | null;
+    /** {@inheritDoc IListControl.setListFillRange} */
+    setListFillRange(address: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IListControl.getSelectedIndex} */
+    getSelectedIndex(): number | null;
+    /** {@inheritDoc IListControl.setSelectedIndex} */
+    setSelectedIndex(index: number | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IListBox}.
+ */
+export declare class ListBox extends ListControl<IListBox.JSON> implements IListBox {
+    constructor(options: FormControl.KindOptions<IListBox.JSON>);
+}
+/**
+ * Implementation for {@link IDropDown}.
+ */
+export declare class DropDown extends ListControl<IDropDown.JSON> implements IDropDown {
+    constructor(options: FormControl.KindOptions<IDropDown.JSON>);
+    /** {@inheritDoc IDropDown.getDropStyle} */
+    getDropStyle(): IDropDown.DropStyle | null;
+    /** {@inheritDoc IDropDown.getDropLines} */
+    getDropLines(): number | null;
+}
+/**
+ * Interfaces for creating form controls.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link FormControl}
+ */
+export declare namespace FormControl {
+    /**
+     * Options for creating a kind of form control, which knows its own type.
+     */
+    interface KindOptions<J extends IFormControl.JSON> extends AbstractMovableContent.ConstructorOptions<J> {
+    }
+    /**
+     * Options for creating a form control of a kind with nothing of its own.
+     */
+    interface ConstructorOptions<J extends IFormControl.JSON> extends KindOptions<J> {
+        /** The content type ({@link IFormControl.Type}). */
+        type: string;
+        /** What the kind is called to a person: `Edit Box`. */
+        typeDescription?: string;
+    }
+}
+export {};
+//# sourceMappingURL=FormControl.d.ts.map

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

@@ -0,0 +1,424 @@
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+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 whose state a cell mirrors: the control writes to the cell when used, and reads it
+ * back when the cell changes.
+ */
+export interface ILinked {
+    /**
+     * Returns the address of the cell the control writes its state to, or `null` if it has none.
+     *
+     * @remarks
+     * As the file spelled it, which may name a sheet (`Sheet1!$A$1`).
+     */
+    getLinkedCell(): string | 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. */
+    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 address of the range the items come from, or `null` if the control holds them. */
+    getListFillRange(): string | 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