Library: xapi

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview

X-Method Registry

X-Method Details

Array.each(callback)   <extends: Array>

This function calls a callback function on each item of the array.

Parameters:

• callback [Function] — a callback function to call for each item in the array, breaks the loop if the callback returns false

---

Array.first() → String   <extends: Array>

This function returns the first element of the array.

Returns:

• [String] — the first element of the Array

---

Array.last() → String   <extends: Array>

This function returns the last element of the array.

Returns:

• [String] — the last element of the Array

---

Array.removeIf(callback)   <extends: Array>

This function removes elements from the array based on the boolean results of the callback function.

Parameters:

• callback [Function] — a callback function to call to determine if an element should be removed

---

CustomElementRegistry.extends(tagName, jsClassName)   <extends: CustomElementRegistry>

This method is an alias for 'CustomElementRegistry.define', which creates a new custom element by extending from an existing element.

Parameters:

• tagName [String] — the tag name of the custom element to define
• jsClassName [String] — the Javascript class name of the class that defines the operation of the custom element

---

CustomElementRegistry.getClass(tagName) → Constructor   <extends: CustomElementRegistry>

This method is an alias for 'CustomElementRegistry.get'.

Parameters:

• tagName [String] — the tag name of the custom element to define

Returns:

• [Constructor] — the constructor of the Javascript class which was used to define the custom element

---

CustomElementRegistry.register(tagName, jsClassName)   <extends: CustomElementRegistry>

This method is an alias for 'CustomElementRegistry.define', which creates a new custom element w/o extending from an existing element.

Parameters:

• tagName [String] — the tag name of the custom element to define
• jsClassName [String] — the Javascript class name of the class that defines the operation of the custom element

---

Document.createElementWithAttributes(tag, attrs)   <extends: Document>

This method calls document.createElement and sets the attributes by walking the specified attr hash and using setAttribute on each.

Parameters:

• tag [String] — the element's tag name
• attrs [Hash] — the element's attributes represented by a key/value Hash object

---

Document.findStylesheet(basename) → StyleSheet or Null   <extends: Document>

This method returns a stylesheet based on the specified filename

Parameters:

• basename [String] — the pathless filename to search for

Returns:

• [StyleSheet or Null] — the stylesheet which has the basename as as the trailing part of its href

---

Document.htmlToElement(snippet) → HTMLElement or Null   <extends: Document>

This method creates an HTML element from the given snippet of HTML text.

Parameters:

• snippet [String] — the HTML snippet to convert to an HTMLElement

Returns:

• [HTMLElement or Null] — the HTMLElement (and subtree) described by the given valid HTML snippet

---

Document.loadImage(source)   <extends: Document>

This method does an asynchronous deferred load of an image from the specified source.

Parameters:

• source [String] — the source of the image

---

Document.qcfirst(name) → HTMLElement or Null   <extends: Document>

This method returns the first element of a specified class, if it exists

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLElement or Null] — the first element of the specified class

---

Document.qchildren(selector) → Array<HTMLNode>   <extends: Document>

This method filters a call to Document.qsall to direct children.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [Array<HTMLNode>] — the 'non-live' list of HTML Nodes which satisfy the query

---

Document.qclass(name) → HTMLCollection   <extends: Document>

This method is an alias for 'getElementsByClassName', which searches the document for elements with the specified tag.

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which are of the specified class

---

Document.qid(id) → HTMLElement or Null   <extends: Document>

This method is uses the built-in querySelector to find an element with the given id

Parameters:

• id [String] — the id attribute of the element to find

Returns:

• [HTMLElement or Null] — the HTML Element with the specified 'id' attribute value (or Null if not found)

---

Document.qsall(selector) → NodeList   <extends: Document>

This method is an alias for 'querySelectorAll', which searches the document for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [NodeList] — the 'non-live' list of HTML Nodes which satisfy the query

---

Document.qsel(selector) → HTMLElement or Null   <extends: Document>

This method is an alias for 'querySelector', which searches the document for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the first element of the document which satisfies the query (or Null if not found)

---

Document.qsfirst(selector) → HTMLElement or Null   <extends: Document>

This method uses qsall to return the array to find the first element

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the first element of the document which satisfies the query (or Null if not found)

---

Document.qslast(selector) → HTMLElement or Null   <extends: Document>

This method uses qsall to return the array to find the last element

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the last element of the document which satisfies the query (or Null if not found)

---

Document.qtag(tag) → HTMLCollection   <extends: Document>

This method is an alias for 'getElementsByTagName', which searches the document for elements with the specified tag.

Parameters:

• tag [String] — the tag of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which have the specified tag

---

Document.qxy(x, y, include_shadows) → Array<HTMLElement> or Null   <extends: Document>

This method returns a list of elements at the specified point in the document in topmost visible order.

Parameters:

• x [Number] — the document x-coordinate to be searched
• y [Number] — the document y-coordinate to be searched
• include_shadows [Boolean] — if true, will also include visible shadow DOM elements in the list <default: false>

Returns:

• [Array<HTMLElement> or Null] — the list of visible HTML Elements at the specified document coordinates (or Null if not found)

---

Document.walkElements(proc, xdata)   <extends: Document>

This method calls document.body.walkElements() to traverse the entire document tree.

Parameters:

• proc [Function] — the Javascript function to call for each element in the tree
• xdata [Data] — the optional external data element to pass to each proc call <default: Null>

---

Element.fqname() → String   <extends: Element>

This method creates a fully-qualified name for the element, consisting of its tagName (converted to lower case), class names (prefixed with '.') and id (if defined, prefixed with '#').

Returns:

• [String] — the fully qualified name of the element

---

Element.qcfirst(name) → HTMLElement or Null   <extends: Element>

This method returns the first element of a specified class, if it exists

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLElement or Null] — the first element of the specified class

---

Element.qchildren(selector) → Array<HTMLNode>   <extends: Element>

This method filters a call to Element.qsall to direct children.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [Array<HTMLNode>] — the 'non-live' list of HTML Nodes which satisfy the query

---

Element.qclass(name) → HTMLCollection   <extends: Element>

This method is an alias for 'getElementsByClassName', which searches the subtree for elements with the specified tag.

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which are of the specified class

---

Element.qid(id) → Element or Null   <extends: Element>

This method is an alias for 'querySelector', which searches the subtree for the element with the specified 'id' attribute value.

Parameters:

• id [String] — the id attribute of the element to find

Returns:

• [Element or Null] — the HTML Element with the specified 'id' attribute value (or Null if not found)

---

Element.qparent(tag) → Element or Null   <extends: Element>

This method locates an ancestor element with the given tag.

Parameters:

• tag [String] — the tag of the ancestor element to locate

Returns:

• [Element or Null] — the ancestor element with the given tag (or Null if not found)

---

Element.qsall(selector) → NodeList   <extends: Element>

This method is an alias for 'querySelectorAll', which searches the subtree for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [NodeList] — the 'non-live' list of HTML Nodes which satisfy the query

---

Element.qsel(selector) → Element or Null   <extends: Element>

This method is an alias for 'querySelector', which searches the subtree for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [Element or Null] — the first element of the document which satisfies the query (or Null if not found)

---

Element.qsfirst(selector) → HTMLElement or Null   <extends: Element>

This method uses qsall to return the array to find the first element

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the first element of the document which satisfies the query (or Null if not found)

---

Element.qtag(tag) → HTMLCollection   <extends: Element>

This method is an alias for 'getElementsByTagName', which searches the subtree for elements with the specified tag.

Parameters:

• tag [String] — the tag of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which have the specified tag

---

Element.walkElements(proc, xdata)   <extends: Element>

This method visits every element in the subtree and calls the given procedure with the given external data.

Parameters:

• proc [Function] — the Javascript function to call for each element in the subtree beginning with this element
• xdata [Data] — the optional external data element to pass to each proc call <default: Null>

---

Element.where() → Array<Element>   <extends: Element>

This method returns this element's ancestry list of elements in the document from most distant to its immediate parent.

Returns:

• [Array<Element>] — the array of this elements ancestry elements in order from most distant to its immediate parent

---

HTMLElement.appendHTML(snippet)   <extends: HTMLElement>

This method appends an element (and its subtree) as described by the given HTML snippet into this element's children list.

Parameters:

• snippet [String] — the HTML snippet

---

HTMLElement.detach() → HTMLElement   <extends: HTMLElement>

This method removes itself from its parent.

Returns:

• [HTMLElement] — this HTML Element

---

HTMLElement.getComputedStyle(properties) → Hash   <extends: HTMLElement>

Ths method retrieves computed styles from the element.

Parameters:

• properties [String or Array<String> or Null] — the properties to retrieve from the elements computed styles <default: null>

Returns:

• [Hash] — the requested style propertites, or all if null is specified

---

HTMLElement.hide()   <extends: HTMLElement>

This method hides this element by settings its style's display attribute to 'none'.

---

HTMLElement.insertAfterHTML(snippet)   <extends: HTMLElement>

This method inserts an element (and its subtree) as described by the given HTML snippet after this element in its parent's children list.

Parameters:

• snippet [String] — the HTML snippet

---

HTMLElement.insertBeforeHTML(snippet)   <extends: HTMLElement>

This method inserts an element (and its subtree) as described by the given HTML snippet before this element in its parent's children list.

Parameters:

• snippet [String] — the HTML snippet

---

HTMLElement.isNthChildOf(parent) → Integer or Null   <extends: HTMLElement>

This method checks to see if this element is a child of the specified parent and where in the parent's children list the element is.

Parameters:

• parent [HTMLElement] — the conjectured parent element

Returns:

• [Integer or Null] — the index within the parent's children list (or Null if the element is not a child of the specified parent)

---

HTMLElement.prependChild(child)   <extends: HTMLElement>

This method inserts the child element into the parent's children list as the new first element.

Parameters:

• child [HTMLElement] — the element to add as the element's first child

---

HTMLElement.prependHTML(snippet)   <extends: HTMLElement>

This method prepends an element (and its subtree) as described by the given HTML snippet into this element's children list.

Parameters:

• snippet [String] — the HTML snippet

---

HTMLElement.removeAllChildren(parent) → HTMLElememt   <extends: HTMLElement>

This method removes all of an element's children.

Parameters:

• parent [HTMLElement] — the conjectured parent element

Returns:

• [HTMLElememt] — the element

---

HTMLElement.removeElementsAfter()   <extends: HTMLElement>

This method removes child elements after this element in its parent's children list.

---

HTMLElement.removeElementsBefore()   <extends: HTMLElement>

This method removes child elements before this element in its parent's children list.

---

HTMLElement.reparent(newParent, at)   <extends: HTMLElement>

This method removes itself from its current parent and attaches itself to a new parent.

Parameters:

• newParent [HTMLElement] — the new parent element for this element
• at [Integer] — the optional index within the new parent's children list to insert this element <default: 0>

---

HTMLElement.replaceWithHTML(snippet)   <extends: HTMLElement>

This method replaces this element with an element (and its subtree) as described by the given HTML snippet in its parent's children list.

Parameters:

• snippet [String] — the HTML snippet

---

HTMLElement.rotateElements(firstToLast)   <extends: HTMLElement>

This method rotates an element's children. If firstToLast is true, the first child become the last child. Else, the last child becomes the first child.

Parameters:

• firstToLast [Boolean] — the direction of the rotation <default: true>

---

HTMLElement.show(type)   <extends: HTMLElement>

This method displays this element by setting its style's display property to the given type, or 'block'

Parameters:

• type [String] — the display style for this element <default: 'block'>

---

HTMLImageElement.load(source)   <extends: HTMLImageElement>

This method does an asynchronous deferred load of an image into the HTMLImageElement.

Parameters:

• source [String] — the source of the image

---

JSON.toString(obj) → String   <extends: JSON>

This method is an alias for 'JSON.stringify' if the Javascript's implementation of JSON does not have a toString method.

Parameters:

• obj [Object] — the object to convert to a JSON string

Returns:

• [String] — the JSON string which represents the given object

---

Object.eachKey(callback)   <extends: Object>

This function calls a callback function for each key/property of the Object. If the callback function returns false, the iteration is aborted.

Parameters:

• callback [Function] — a callback function to be called for each key/property of the Object

---

Object.eachValue(callback)   <extends: Object>

This function calls a callback function for each value of the Object. If the callback function returns false, the iteration is aborted.

Parameters:

• callback [Function] — a callback function to be called for each value of the Object

---

Object.first() → Array<Any>   <extends: Object>

This function returns the list of values in the Object.

Returns:

• [Array<Any>] — the list of values in the Object

---

Object.hasKey(key) → Boolean   <extends: Object>

This function returns true if the given key is defined within the Object.

Parameters:

• key [String] — the name of the key/property to test the existance of within the object

Returns:

• [Boolean] — true if the key exists within the Object

---

Object.key() → String   <extends: Object>

This function returns the name of the first key/property of the Object.

Returns:

• [String] — the first key/property of the Object

---

Object.klist() → Array<String>   <extends: Object>

This function returns the list of keys/properties in the object.

Returns:

• [Array<String>] — the list of keys/properties in the Object

---

Object.value() → String   <extends: Object>

This function returns the name of the first value of the Object.

Returns:

• [String] — the first element of the Object

---

ShadowRoot.qcfirst(name) → HTMLElement or Null   <extends: ShadowRoot>

This method returns the first element of a specified class, if it exists

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLElement or Null] — the first element of the specified class

---

ShadowRoot.qchildren(selector) → Array<HTMLNode>   <extends: ShadowRoot>

This method filters a call to ShadowRoot.qsall to direct children.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [Array<HTMLNode>] — the 'non-live' list of HTML Nodes which satisfy the query

---

ShadowRoot.qclass(name) → HTMLCollection   <extends: ShadowRoot>

This method is an alias for 'getElementsByClassName', which searches the shadow root for elements with the specified tag.

Parameters:

• name [String] — the class name of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which are of the specified class

---

ShadowRoot.qid(id) → HTMLElement or Null   <extends: ShadowRoot>

This method is an alias for 'querySelector', which searches the shadow root for the element with the specified 'id' attribute value.

Parameters:

• id [String] — the id attribute of the element to find

Returns:

• [HTMLElement or Null] — the HTML Element with the specified 'id' attribute value (or Null if not found)

---

ShadowRoot.qsall(selector) → NodeList   <extends: ShadowRoot>

This method is an alias for 'querySelectorAll', which searches the shadow root for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [NodeList] — the 'non-live' list of HTML Nodes which satisfy the query

---

ShadowRoot.qsel(selector) → HTMLElement or Null   <extends: ShadowRoot>

This method is an alias for 'querySelector', which searches the shadow root for elements using the specified selector.

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the first element of the document which satisfies the query (or Null if not found)

---

ShadowRoot.qsfirst(selector) → HTMLElement or Null   <extends: ShadowRoot>

This method uses qsall to return the array to find the first element

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the first element of the document which satisfies the query (or Null if not found)

---

ShadowRoot.qslast(selector) → HTMLElement or Null   <extends: ShadowRoot>

This method uses qsall to return the array to find the last element

Parameters:

• selector [String] — the query selector used for the search

Returns:

• [HTMLElement or Null] — the last element of the document which satisfies the query (or Null if not found)

---

ShadowRoot.qtag(tag) → HTMLCollection   <extends: ShadowRoot>

This method is an alias for 'getElementsByTagName', which searches the shadow root for elements with the specified tag.

Parameters:

• tag [String] — the tag of the elements to find

Returns:

• [HTMLCollection] — the 'live' collection of HTML Elements which have the specified tag

---

ShadowRoot.qxy(x, y) → Array<HTMLElement> or Null   <extends: ShadowRoot>

This method returns a list of elements at the specified point in the document in topmost visible order.

Parameters:

• x [Number] — the document x-coordinate to be searched
• y [Number] — the document y-coordinate to be searched

Returns:

• [Array<HTMLElement> or Null] — the list of visible HTML Elements at the specified document coordinates, including the shadow DOM of the given element (or Null if not found)

---

ShadowRoot.qxys(x, y, deep) → Array<HTMLElement> or Null   <extends: ShadowRoot>

This method returns a list of elements within a given element's shadow DOM at the specified point in the document in topmost visible order.

Parameters:

• x [Number] — the document x-coordinate to be searched
• y [Number] — the document y-coordinate to be searched
• deep [Boolean] — if true, add contained element's shadow DOMs as well

Returns:

• [Array<HTMLElement> or Null] — the list of visible HTML Elements in the hosting element's shadow DOM at the specified document coordinates (or Null if not found)

---

String.fmt() → String   <extends: String>

This function formats the incoming arguments into a string suitable for output, similar to the C function sprintf().

Returns:

• [String] — the formatted string

---

String.makeHtmlSnippet(tag, attrs, inner) → String   <extends: String>

This function formats the incoming arguments into a string suitable for output, similar to the C function sprintf().

Parameters:

• tag [String] — the name of the element to create
• attrs [String or Array<String> or Function] — a string, an array of attribute/value pairs or a function which will return the attr-string <default: ''>
• inner [String or Function] — a string or function which will return a string which will serve as the inner content of the element <default: ''>

Returns:

• [String] — the formatted string

---

Namespace: xapi.AJAX

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview

Function Registry

Function Details

AJAX.fetch(url, payload, method) → Promise

This method is a wrapper for the fetch API.

Parameters:

• url [String] — the URL of the server to communicate with
• payload [String] — the communications payload
• method [String] — the communications method <default: POST>

Returns:

• [Promise] — the Promise object which will resolve to a Response object

---

Namespace: xapi.AppLoader

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview

Function Registry

Function Details

AppLoader.load(callback, prime)

The AppLoader namespace encapsulates dynamic resource loading operations.

Parameters:

• callback [Function] — a function that loads app resources via multiple stages.
• prime [Varargs] — extra arguments that will get passed to the callback during the stage 0 pipeline priming step

---

Class: xapi.ArgumentError ← Error

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview

Namespace: xapi.ResLoader

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview

Function Registry

Function Details

ResLoader.load(src, async, callback)

This method loads a script into a script element and appends it to the document's head.

Parameters:

• src [String] — the script src
• async [Boolean] — if true, loads the script asynchronously <default: false>
• callback [Proc] — the callback to call when the script is loaded <default: null>

---

ResLoader.require(list)

This function loads a list of scripts asynchronously to the document's head. The pipeline ensures that downstream requirements are inserted at the head of the list.

Parameters:

• list [Varargs] — the list of resources to load

---

ResLoader.setChangeCallback(callback)

This function sets a callback function to be called whenever the internal requirements pipeline is added to.

Parameters:

• callback [Function] — the callback function, arguments are: the internal requirements array

---

ResLoader.setCompletionCallback(callback)

This function sets a callback function to be called whenever a resource has been processed, whether loaded successfully or not.

Parameters:

• callback [Function] — the callback function, arguments are: the item loaded and its process status (true if successful)

---

ResLoader.setFinishCallback(callback)

This function sets a callback function to be called whenever the requirements array is empty

Parameters:

• callback [Function] — the callback function, no arguments

---

Class: xapi.RuntimeError ← Error

File Manifest

File Manifest

File	Language	Author(s)	Copyright
xapi.js	Javascript	Kenneth F. Guerin	Copyright © 2020-2024, Brick Mill Games, LLC. All rights reserved.

Overview