` will be added to DOM; a missing id is created the same way. Use css to customize its appearance if needed. - `callback` (` Fn(bound:Bound, elem:Element)`) — an optional callback `function(boundingBox, spaceElement)` to be called when element is appended and ready. Alternatively, a "ready" event will also be fired from the element when it's appended, which can be traced with `spaceInstance.element.addEventListener("ready")` **Example** ```ts new DOMSpace( "#myElementID" ) ``` #### Accessors ##### `autoResize` ```ts get autoResize(): boolean set autoResize(auto: boolean): void ``` Set whether the canvas element should resize when its container is resized. ##### `background` ```ts get background(): string set background(bg: string): void ``` Set a background color on the container element. ##### `element` ```ts get element(): Element ``` Get this DOM element. ##### `parent` ```ts get parent(): Element ``` Get the parent DOM element that contains this DOM element. ##### `ready` ```ts get ready(): boolean ``` A property to indicate if the Space is ready. #### Methods ##### `clear` *overrides `MultiTouchSpace.clear`* ```ts clear(bg: string): this ``` Clear the element's contents, and optionally set a new background color. This overrides Space's `clear` function. **Parameters** - `bg` (`string`) — Optionally specify a custom background color in hex or rgba string, or "transparent". If not defined, it will use its `bgcolor` property as background color to clear the canvas. ##### `dispose` ```ts dispose(): this ``` Dispose of browser resources held by this space and remove all players. Call this before unmounting the DOM, eg in a framework component's unmount/cleanup callback. Dispose is idempotent, and a new Space can be created on the same element afterwards. ##### `getForm` *overrides `MultiTouchSpace.getForm`* ```ts getForm(): Form ``` Not implemented. See SVGSpace and HTMLSpace for implementation. ##### `resize` *overrides `MultiTouchSpace.resize`* ```ts resize(b: Bound, evt: Event | null): this ``` This overrides Space's `resize` function. It's used as a callback function for window's resize event and not usually called directly. You can keep track of resize events with `resize: (bound, evt)` callback in your player objects (See [`Space.add`](#space-space-add) function). **Parameters** - `b` (`Bound`) — a Bound object to resize to - `evt` (`Event | null`) — Optionally pass a resize event ##### `setup` ```ts setup(opt: { bgcolor:string, resize:boolean }): this ``` Set up various options for DOMSpace. This is usually set during instantiation, eg `new DOMSpace(...).setup( {opt} )`. **Parameters** - `opt` (`{ bgcolor:string, resize:boolean }`) — an object with these optional properties: **bgcolor** is a hex or rgba string to set initial background color of the canvas, or use `false` or "transparent" to set a transparent background; **resize** a boolean to set whether `` size should auto resize to match its container's size, which can also be set using `autoSize()`. **Example** ```ts space.setup({ bgcolor: "#f00", resize: true }) ``` ##### `style` ```ts style(key: string, val: string, update: boolean = false): this ``` Add or update a style definition, and optionally update that style in the Element. **Parameters** - `key` (`string`) — style name - `val` (`string`) — style value - `update` (`boolean`; default `false`) — a boolean to update the element's style immediately if set to `true`. Default is `false`. ##### `styles` ```ts styles(styles: Record, update: boolean = false): this ``` Add of update a list of style definitions, and optionally update those styles in the Element. **Parameters** - `styles` (`Record`) — a key-value objects of style definitions - `update` (`boolean`; default `false`) — a boolean to update the element's style immediately if set to `true`. Default is `false`. **Returns:** this ##### `createElement` *static* ```ts static createElement(elem: string = "div", id: string, appendTo: Element): Element ``` Helper function to create a DOM element. **Parameters** - `elem` (`string`; default `"div"`) — element tag name - `id` (`string`) — element id attribute - `appendTo` (`Element`) — Optional, if specified, the created element will be appended to this element ##### `getInlineStyles` *static* ```ts static getInlineStyles(data: Record): string ``` A static helper function to compose an inline style string from a object of styles. **Parameters** - `data` (`Record`) — an object with key-value pairs **Example** ```ts DOMSpace.getInlineStyles( {width: "100px", "font-size": "10px"} ) ``` ##### `setAttr` *static* ```ts static setAttr(elem: Element, data: Record): Element ``` A static helper function to add or update Element attributes. **Parameters** - `elem` (`Element`) — Element to update - `data` (`Record`) — an object with key-value pairs **Returns:** this DOM element #### Properties ##### `id` *overrides `MultiTouchSpace.id`* ```ts id: string ``` #### Inherited API - From [`Space`](#space-space): [`center`](#space-space-center), [`customRendering`](#space-space-custom-rendering), [`height`](#space-space-height), [`innerBound`](#space-space-inner-bound), [`isPlaying`](#space-space-is-playing), [`outerBound`](#space-space-outer-bound), [`size`](#space-space-size), [`width`](#space-space-width), [`add`](#space-space-add), [`minFrameTime`](#space-space-min-frame-time), [`pause`](#space-space-pause), [`play`](#space-space-play), [`playItems`](#space-space-play-items), [`playOnce`](#space-space-play-once), [`refresh`](#space-space-refresh), [`remove`](#space-space-remove), [`render`](#space-space-render), [`replay`](#space-space-replay), [`resume`](#space-space-resume), [`stop`](#space-space-stop), [`bound`](#space-space-bound), [`playerCount`](#space-space-player-count), [`players`](#space-space-players). - From [`MultiTouchSpace`](#space-multitouchspace): [`pointer`](#space-multitouchspace-pointer), [`bindCanvas`](#space-multitouchspace-bind-canvas), [`bindDoc`](#space-multitouchspace-bind-doc), [`bindKeyboard`](#space-multitouchspace-bind-keyboard), [`bindMouse`](#space-multitouchspace-bind-mouse), [`bindTouch`](#space-multitouchspace-bind-touch), [`removeAll`](#space-multitouchspace-remove-all), [`touchesToPoints`](#space-multitouchspace-touches-to-points), [`track`](#space-multitouchspace-track), [`unbindCanvas`](#space-multitouchspace-unbind-canvas), [`unbindDoc`](#space-multitouchspace-unbind-doc), [`untrack`](#space-multitouchspace-untrack). ### `HTMLForm` **Kind:** Class · **Source:** [`src/Dom.ts:423`](https://github.com/williamngan/pts/blob/master/src/Dom.ts#L423) **Extends:** `VisualForm` #### Constructors ##### Constructor ```ts new HTMLForm(space: HTMLSpace): HTMLForm ``` Create a new `HTMLForm`. Alternatively, you can use [`HTMLSpace.getForm`](#dom-htmlspace-get-form) function to get an instance of HTMLForm. **Parameters** - `space` (`HTMLSpace`) — the space to use #### Accessors ##### `space` ```ts get space(): HTMLSpace ``` Get the corresponding space for this form ##### `domID` *static* ```ts get domID(): number set domID(n: number): void ``` ##### `groupID` *static* ```ts get groupID(): number set groupID(n: number): void ``` #### Methods ##### `alpha` *overrides `VisualForm.alpha`* ```ts alpha(a: number): this ``` Set current alpha value. **Parameters** - `a` (`number`) — alpha value between 0 and 1 **Example** ```ts form.alpha(0.6) ``` ##### `arc` *overrides `VisualForm.arc`* ```ts arc(pt: PtLike, radius: number, startAngle: number, endAngle: number, cc: boolean): this ``` Arc is not implemented in HTMLForm. **Parameters** - `pt` (`PtLike`) - `radius` (`number`) - `startAngle` (`number`) - `endAngle` (`number`) - `cc` (`boolean`) ##### `circle` *overrides `VisualForm.circle`* ```ts circle(pts: GroupLike | number[][]): this ``` Draw a circle. **Parameters** - `pts` (`GroupLike | number[][]`) — usually a Group of 2 Pts, but it can also take an array of two numeric arrays [ [position], [size] ] **See also:** [`Circle.fromCenter`](#op-circle-static-from-center) ##### `cls` ```ts cls(c: string | boolean): HTMLForm ``` Add custom class to the created element. **Parameters** - `c` (`string | boolean`) — custom class name or `false` to reset it **Example** ```ts form.fill("#f00").cls("myClass").rects(r)` `form.cls(false).circles(c) ``` ##### `fill` *overrides `VisualForm.fill`* ```ts fill(c: string | boolean): this ``` Set current fill style. Provide a valid color string or `false` to specify no fill color. **Parameters** - `c` (`string | boolean`) — fill color **Example** ```ts form.fill("#F90")`, `form.fill("rgba(0,0,0,.5")`, `form.fill(false) ``` ##### `fillText` ```ts fillText(c: string): this ``` Set current text color style. Provide a valid color string. **Parameters** - `c` (`string`) — fill color **Example** ```ts form.fill("#F90")`, `form.fill("rgba(0,0,0,.5")`, `form.fill(false) ``` ##### `font` *overrides `VisualForm.font`* ```ts font(sizeOrFont: number | Font, weight: string, style: string, lineHeight: number, family: string): this ``` Set the current font. **Parameters** - `sizeOrFont` (`number | Font`) — either a number to specify font-size, or a `Font` object to specify all font properties - `weight` (`string`) — Optional font-weight string such as "bold" - `style` (`string`) — Optional font-style string such as "italic" - `lineHeight` (`number`) — Optional line-height number suchas 1.5 - `family` (`string`) — Optional font-family such as "Helvetica, sans-serif" **Example** ```ts form.font( myFont )`, `form.font(14, "bold") ``` ##### `line` *overrides `VisualForm.line`* ```ts line(pts: GroupLike | number[][]): this ``` Line is not implemented in HTMLForm. **Parameters** - `pts` (`GroupLike | number[][]`) ##### `log` ```ts log(txt: any): this ``` A convenient way to draw some text on canvas for logging or debugging. It'll be draw on the top-left of the canvas as an overlay. **Parameters** - `txt` (`any`) — text ##### `nextID` ```ts nextID(): string ``` Get next available id in the current group. **Returns:** an id string ##### `point` *overrides `VisualForm.point`* ```ts point(pt: PtLike, radius: number = 5, shape: string = "square"): this ``` Draws a point. **Parameters** - `pt` (`PtLike`) — a Pt object - `radius` (`number`; default `5`) — radius of the point. Default is 5. - `shape` (`string`; default `"square"`) — The shape of the point. Defaults to "square", but it can be "circle" or a custom shape function in your own implementation. **Example** ```ts form.point( p )`, `form.point( p, 10, "circle" ) ``` ##### `polygon` *overrides `VisualForm.polygon`* ```ts polygon(pts: GroupLike | number[][]): this ``` Polygon is not implemented in HTMLForm. **Parameters** - `pts` (`GroupLike | number[][]`) ##### `rect` *overrides `VisualForm.rect`* ```ts rect(pts: PtLikeIterable): this ``` Draw a rectangle. **Parameters** - `pts` (`PtLikeIterable`) — a Group or an Iterable with 2 Pt specifying the top-left and bottom-right positions. ##### `reset` *overrides `VisualForm.reset`* ```ts reset(): this ``` Reset the context's common styles to this form's styles. This supports using multiple forms on the same canvas context. ##### `scope` ```ts scope(item: IPlayer): DOMFormContext ``` Set the current group scope to an item added into space, in order to keep track of any point, circle, etc created within it. The item must have an `animateID` property, so that elements created within the item will have generated IDs like "item-{animateID}-{count}". **Parameters** - `item` (`IPlayer`) — a "player" item that's added to space (see `space.add(...)`) and has an `animateID` property **Returns:** this form's context ##### `square` ```ts square(pt: PtLike, halfsize: number): this ``` Draw a square, given a center and its half-size. **Parameters** - `pt` (`PtLike`) — center Pt - `halfsize` (`number`) — half-size ##### `stroke` *overrides `VisualForm.stroke`* ```ts stroke(c: string | boolean, width: number, linejoin: string, linecap: string): this ``` Set current stroke style. Provide a valid color string or `false` to specify no stroke color. **Parameters** - `c` (`string | boolean`) — stroke color which can be as color, gradient, or pattern. (See [canvas documentation](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/strokeStyle)) - `width` (`number`) — Optional value (can be floating point) to set line width - `linejoin` (`string`) — not implemented in HTMLForm - `linecap` (`string`) — not implemented in HTMLForm **Example** ```ts form.stroke("#F90")`, `form.stroke("rgba(0,0,0,.5")`, `form.stroke(false)`, `form.stroke("#000", 0.5, 'round', 'square') ``` ##### `styleTo` *protected* ```ts styleTo(k: string, v: any, unit: string = ""): void ``` Usually not used directly. This updates a style in `_ctx` context or throw an Error if the style doesn't exist. **Parameters** - `k` (`string`) — style key - `v` (`any`) — style value - `unit` (`string`; default `""`) — Optional unit like 'px' to append to value ##### `text` *overrides `VisualForm.text`* ```ts text(pt: PtLike, txt: string): this ``` Draw text in a DOM element. **Parameters** - `pt` (`PtLike`) — a Pt or numeric array to specify the anchor point - `txt` (`string`) — text ##### `updateScope` ```ts updateScope(group_id: string, group: Element): DOMFormContext ``` Set this form's group scope by an ID, and optionally define the group's parent element. A group scope keeps track of elements by their generated IDs, and updates their properties as needed. See also `scope()`. **Parameters** - `group_id` (`string`) — a string to use as prefix for the group's id. For example, group_id "hello" will create elements with id like "hello-1", "hello-2", etc - `group` (`Element`) — Optional DOM element to define this group's parent element **Returns:** this form's context ##### `circle` *static* ```ts static circle(ctx: DOMFormContext, pt: PtLike, radius: number = 10): Element ``` A static function to draw a circle. **Parameters** - `ctx` (`DOMFormContext`) — a context object of HTMLForm - `pt` (`PtLike`) — center position of the circle - `radius` (`number`; default `10`) — radius of the circle ##### `getID` *static* ```ts static getID(ctx: DOMFormContext): string ``` A static function to generate an ID string based on a context object. **Parameters** - `ctx` (`DOMFormContext`) — a context object for an HTMLForm ##### `point` *static* ```ts static point(ctx: DOMFormContext, pt: PtLike, radius: number = 5, shape: string = "square"): Element ``` A static function to draws a point. **Parameters** - `ctx` (`DOMFormContext`) — a context object of HTMLForm - `pt` (`PtLike`) — a Pt object or numeric array - `radius` (`number`; default `5`) — radius of the point. Default is 5. - `shape` (`string`; default `"square"`) — The shape of the point. Defaults to "square", but it can be "circle" or a custom shape function in your own implementation. **Example** ```ts HTMLForm.point( p )`, `HTMLForm.point( p, 10, "circle" ) ``` ##### `rect` *static* ```ts static rect(ctx: DOMFormContext, pts: PtLikeIterable): Element | undefined ``` A static function to draw a rectangle. **Parameters** - `ctx` (`DOMFormContext`) — a context object of HTMLForm - `pts` (`PtLikeIterable`) — a Group or an Iterable with 2 Pt specifying the top-left and bottom-right positions. ##### `rectStyle` *static* ```ts static rectStyle(ctx: DOMFormContext, pt: PtLike, size: PtLike): DOMFormContext ``` A helper function to set top, left, width, height of DOM element. **Parameters** - `ctx` (`DOMFormContext`) — the HTMLForm context whose style is updated - `pt` (`PtLike`) — left and top position - `size` (`PtLike`) — width and height ##### `scopeID` *static* ```ts static scopeID(item: IPlayer): string ``` A static function to generate an ID string for a scope, based on a "player" item in the Space. **Parameters** - `item` (`IPlayer`) — a "player" item that's added to space (see `space.add(...)`) and has an `animateID` property ##### `square` *static* ```ts static square(ctx: DOMFormContext, pt: PtLike, halfsize: number): HTMLElement ``` A static function to draw a square. **Parameters** - `ctx` (`DOMFormContext`) — a context object of HTMLForm - `pt` (`PtLike`) — center position of the square - `halfsize` (`number`) — half size of the square ##### `style` *static* ```ts static style(elem: Element, styles: Record): Element ``` A static function to help adding style object to an element. This put all styles into `style` attribute instead of individual attributes, so that the styles can be parsed by Adobe Illustrator. **Parameters** - `elem` (`Element`) — A DOM element to add to - `styles` (`Record`) — an object of style properties **Returns:** DOM element **Example** ```ts HTMLForm.style(elem, {fill: "#f90", stroke: false}) ``` ##### `text` *static* ```ts static text(ctx: DOMFormContext, pt: PtLike, txt: string): Element ``` A static function to draw text. **Parameters** - `ctx` (`DOMFormContext`) — a context object of HTMLForm - `pt` (`PtLike`) — a Point object to specify the anchor point - `txt` (`string`) — a string of text to draw ##### `textStyle` *static* ```ts static textStyle(ctx: DOMFormContext, pt: PtLike): DOMFormContext ``` A helper function to set the top and left position styling of text DOM context. **Parameters** - `ctx` (`DOMFormContext`) — context to add style to - `pt` (`PtLike`) — a Pt object or numeric array determining the top-left position of the text #### Inherited API - From [`VisualForm`](#form-visualform): [`currentFont`](#form-visualform-current-font), [`filled`](#form-visualform-filled), [`stroked`](#form-visualform-stroked), [`circles`](#form-visualform-circles), [`fillOnly`](#form-visualform-fill-only), [`lines`](#form-visualform-lines), [`points`](#form-visualform-points), [`polygons`](#form-visualform-polygons), [`rects`](#form-visualform-rects), [`squares`](#form-visualform-squares), [`strokeOnly`](#form-visualform-stroke-only). - From [`Form`](#form-form): [`ready`](#form-form-ready). ### `HTMLSpace` **Kind:** Class · **Source:** [`src/Dom.ts:352`](https://github.com/williamngan/pts/blob/master/src/Dom.ts#L352) **Extends:** `DOMSpace` #### Methods ##### `getForm` *overrides `DOMSpace.getForm`* ```ts getForm(): Form ``` Get a new `HTMLForm` which provides visualization functions in html elements. **See also:** `HTMLForm` ##### `remove` *overrides `DOMSpace.remove`* ```ts remove(player: IPlayer): this ``` Remove an item from this space. **Parameters** - `player` (`IPlayer`) — a player item with an auto-assigned `animateID` property ##### `removeAll` *overrides `DOMSpace.removeAll`* ```ts removeAll(): this ``` Remove all items from this space. This clears the contents of the space's element but never touches its container. ##### `htmlElement` *static* ```ts static htmlElement(parent: Element | null | undefined, name: string, id: string, autoClass: boolean = true): HTMLElement ``` A static function to add a DOM element inside a node. Usually you don't need to use this directly. See methods in [`HTMLForm`](#dom-htmlform) instead. **Parameters** - `parent` (`Element | null | undefined`) — the parent element, or `null` to use current `

` container in which a new `

` will be added to DOM. Use css to customize its appearance if needed. - `callback` (` Fn(bound:Bound, elem:Element)`) — an optional callback `function(boundingBox, spaceElement)` to be called when canvas is appended and ready. Alternatively, a "ready" event will also be fired from the `