Namespace: low

low

Module ID: shellfish/low

This module provides the low-level Shellfish API for working directly on the HTML DOM and CSS.

When working with Shui or the declarative-level API, you normally do not have to deal directly with this low-level API.

Examples

Importing in JavaScript

shRequire("shellfish/low", low =>
{
    ...
});

Importing in Shui

require "shellfish/low" as low;

Object {
    ...
}

Classes

FetchManager
Tag

Methods

low.activeFrameHandlers ()Array.<string> static low.js:863

Returns the annotations of the currently active frame handlers.

See:

low.addFrameHandler

Returns:

Type	Description
Array.<string>	The annotations of the frame handlers.

low.addFrameHandler (handler, annotation)low.FrameHandle static low.js:803

Adds a repeating frame handler and returns a handle for cancelation.

If the system load and the screen refresh rate permit, 60 frames are rendered per second.

For handlers that should only run once, invoke cancel() in the handler function itself.

Multiple frame handlers may be active at the same time.

Note: The HTML environment decides when to run the frame handlers. Browser windows or tabs may not invoke frame handlers at all while being invisible or without focus.

Name	Type	Default	Description
`handler`	function		The handler function.
`annotation`	string	"<no annotation>"	optional An optional annotation for identifying the handler for debugging purposes.

Returns:

Type	Description
low.FrameHandle	The handle with a `cancel()` method.

Examples

Adding a repeating frame handler

const handle = low.addFrameHandler(() =>
{
    console.log("next frame");
});

Running a one-shot frame handler

const handle = low.addFrameHandler(() =>
{
    handle.cancel(); // run only once
    console.log("the frame handler was called");
});

low.createElementTree (html)HTMLElement static low.js:348

Creates a DOM element tree from a string of HTML code.

Name	Type	Description
`html`	string	The HTML code.

Returns:

Type	Description
HTMLElement	The root node of the DOM element tree.

Example

low.createElementTree("<div><h1>Title</h1><p>This is some text</p></div>");

low.css (target, key)string static low.js:322

Returns the current value of a CSS property.

Name	Type	Description
`target`	HTMLElement	The target DOM element.
`key`	string	The CSS property key.

Returns:

Type	Description
string	The current value.

low.css (target, key, value) static low.js:322

Sets the value of a CSS property.

Name	Type	Description
`target`	HTMLElement	The target DOM element.
`key`	string	The CSS property key.
`value`	string	The new value.

low.escapeHtml (text)string Deprecated : Use html.Object#escapeHtml instead. static low.js:89

Escapes a text string for HTML output.

This function replaces certain characters in the text string by entities (for example, "<" becomes "<") so that the string may safely be output in HTML.

Name	Type	Description
`text`	string	The text to escape.

Returns:

Type	Description
string	The escaped text.

low.escapeMarkup (text)string Deprecated : Use html.Object#escapeMarkup instead. static low.js:168

Escapes a text string for literal output.

Name	Type	Description
`text`	string	The text to escape.

Returns:

Type	Description
string	The escaped text.

low.focusables ()Array.<HTMLElement> static low.js:621

Returns a list of all focusable HTML elements in the document. An element is focusable, if it has the data role sh-focusable and is visible and not disabled.

Returns:

Type	Description
Array.<HTMLElement>	The focusable elements.

low.focusNext () static low.js:664

Moves the keyboard focus to the next focusable element.

low.focusPrevious () static low.js:639

Moves the keyboard focus to the previous focusable element.

low.fullscreenEnter (target) static low.js:708

Enters fullscreen mode with the given target element.

Name	Type	Description
`target`	HTMLElement	The DOM element to show fullscreen.

low.fullscreenExit () static low.js:735

Leaves fullscreen mode.

low.fullscreenStatus ()bool static low.js:691

Returns whether fullscreen mode is currently active.

Returns:

Type	Description
bool	Whether fullscreen mode is active.

low.isFrameUpdate () static low.js:878

Returns if a frame update is currently ongoing, i.e. the program execution is currently in the context of a frame handler.

See:

low.addFrameHandler

low.pxToRem (px)number static low.js:282

Converts pixels to rem units according to the current user settings.

A CSS rem unit is the width of the character m in the document's global font, font size, and display scale.

Name	Type	Description
`px`	number	The pixel value to convert.

See:

low.remToPx

Returns:

Type	Description
number	The amount in rem units.

low.registerTopDownEvent (node, name, cb) static low.js:896

Registers a custom topdown-event handler on the given DOM node.

A top-down event trickles down from parent to children, instead of bubbling up from child to parent.

Name	Type	Description
`node`	object	The DOM node.
`name`	string	The name of the event.
`cb`	function	The callback function.

low.remToPx (rem)number static low.js:298

Converts rem units to pixels according to the current user settings.

Name	Type	Description
`rem`	number	The rem units to convert.

See:

low.pxToRem

Returns:

Type	Description
number	The amount of pixels.

low.resolveIcons (text)string Deprecated : Resolving icons is handled by html.Label internally. static low.js:124

Resolves icons in a text string.

Icons are encoded by [icon:<name>] where <name> is the name of the icon to show. See the Icon Gallery in the Shellfish UI-Gallery for the icons available.

The icons come from a web font and are rendered as font glyphs.

Name	Type	Description
`text`	string	The text to resolve.

Returns:

Type	Description
string	HTML code containing the icons.

Example

const output = low.resolveIcons("This is an [icon:bug] icon.");

low.resolveMarkup (text)string Deprecated : Resolving markup is handled by html.Label internally. static low.js:190

Resolves inline markup in a text string. Use the character \ to escape the succeeding character.

Supported markups are:

*italic*
**bold**
_underlined_

Name	Type	Description
`text`	string	The text to resolve.

Returns:

Type	Description
string	HTML code containing the formatting.

low.saveBlob (blob, filename) static low.js:938

Offers the given blob for saving. This function may only be triggered by a user action. Depending on the browser settings, a file dialog may or may not appear for the user to choose a filename, even if you provided a filename.

Name	Type	Description
`blob`	Blob	The blob to save.
`filename`	string	The filename to save to.

low.tag (t)low.Tag static low.js:606

Creates a new HTML tag tree node.

Node trees are built by chaining commands.

Name	Type	Description
`t`	string	The tag name.

Returns:

Type	Description
low.Tag	The new node.

Example

const tree = low.tag("div").class("item")
             .style("background-color", "black")
             .content(
                 low.tag("ol")
                 .content(
                     low.tag("li")
                     .content("First Item")
                 )
                 .content(
                     low.tag("li")
                     .content("Second Item")
                 )
             );

low.triggerTopDownEvent (node, name) static low.js:920

Triggers the given custom topdown-event on a DOM node.

Name	Type	Description
`node`	object	The DOM node.
`name`	string	The name of the event.

Type Definitions

low.FrameHandle Object

A handle for controlling a frame handler.

Properties:

Name	Type	Description
`cancel`	function	Cancels the frame handler.

See:

low.addFrameHandler