Additional global scope variables, classes, and utility functions which are available in the scripting environment.
The DI namespace object contains static utility functions, enumerations, and constructors for custom Dynamic Icons elements.
Point is a static/const container for helper functions to deal with PointType objects,
such as creating them or doing math operations. Benchmarks show 40x(!) faster performance
when creating plain objects vs. classes/function prototypes, although once any members are accessed,
the difference drops to "only" 2-3 improvement. The performance difference of using instance methods vs. static
functions (like provided here) is less significant. So in some cases the convenience may outweigh the creation cost.
Generally, read-only access if faster on plain objects vs. class instances, while changing property values is
faster on the latter.
Point could be converted to a class with static methods, which in some cases seems to perform (a little) better or
(much) worse depending on the operation and what is being operated on (plain object or Vect2d class instance), and perhaps other factors.
Stores a collection of ILayerElement types as layers and produces a composite image from all the layers when rendered.
Draws a values series as a basic vertical bar graph onto a canvas context.
Class for storing a fill or stroke style to use on a Canvas context.
Implementation of GaugeTicks for drawing ticks/labels along a circular/curved path.
Applies a clip(path) operation to the current canvas context using given path(s).
The mask can optionally be inverted against a given rectangle (eg. the drawing area).
It can also "release" a clipped canvas by redrawing the current contents onto a new unclipped canvas.
Applies a drawing style to a canvas context or Path2D objects, which includes all fill, stroke, and shadow attributes.
This class hold an image source (file path or b64 string) and associated data like processing options and a transformation to apply.
Creates a full or partial ellipse/circle/arc path of given diameter, start and end angle values,
draw direction, and optional rotation around center. Essentially a proxy for Path2D.ellipse() method.
The IValuedElement::setValue() interface sets the arc's ending angle.
An element for drawing paths/shapes, eg. for styled drawing or for clipping. A path can be specified with either an array of points or an SVG syntax path. When using arrays of points, multiple line segments can be specified by wrapping each segment in its own array.
Abstract base class for drawing "tick" marks and/or value labels, for use in a gauge indicator. Ticks can be split into "major" and "minor" divisions with separate spacing, size and styling options. Label text, font, color, and other presentation properties are configured independently from the tick marks.
A progress bar is essentially two rectangles, one inside the other, with the inner one changing length to represent a percentage value.
The outer container and inner value boxes can be fully styled with the embedded DrawingStyle properties.
This class inherits from StyledRectangle which is used for the outer container box, and holds additional properties to control the
inner value part. Any corner radius set on the outer container box will also be applied to the inner value part (after some adjustments for size).
Implementation of GaugeTicks for drawing ticks/labels along a linear path, either horizontally or vertically.
Base class for Path elements. Extends SizedElement with operation property and provides helper methods.
Creates a rectangle path with optional radii applied to any/all of the 4 corners (like CSS).
Draws an arc/circle extending from 0 to 360 degrees based on a given value onto a canvas context.
Stores properties for applying a shadow to a canvas context. Can also be used to save & restore context shadow properties.
Base class for any element needing size, alignment, and offset properties. Not drawable on its own and cannot be created directly.
Stores stroke (line) canvas context property definitions, which includes stroke ("pen") style, line width, cap, join, miter, and dash array properties. Line width can be defined as a relative % and scaled automatically in the render method.
Draws a rectangle shape on a canvas context with optional radii applied to any/all of the 4 corners (like CSS). The shape can be fully styled with the embedded DrawingStyle property.
Draws text on a canvas context with various options. The text can be fully styled with the embedded style DrawingStyle property.
Applies a matrix transformation to a canvas context.
Transform operations are specified as individual steps (eg. rotate, translate) and then combined in the specified order
into a DOMMatrix which can then be queried with toMatrix and getMatrix or
applied to a context or a Path2D path in the render or transformPaths methods, respectively.
The primary difference between this class and a regular DOMMatrix (or transforming a canvas directly) is that all the terms
used in Transformation are relative to a given size when queried or drawn. The values for all operations are specified as percentages,
not literal pixels. The query and drawing methods all require a rectangle (or size and origin point) to scale the final matrix into.
It employs a caching strategy to avoid re-computing the final matrix if input parameters and the drawing bounds do not change between
calls to the render(), transformPaths() or getMatrix() methods.
A rectangle type storing x, y, with, & height values. Convenience methods are provided for various operations.
The values are stored as origin (Vect2d type) and size (Size type) properties
which can be read or manipulated directly using their respective methods.
The Size class represents an object with width and height properties. Convenience properties and methods are provided for various operations.
It also provides static methods for working with any SizeType object (anything with width and height properties).
A numeric value with an associated unit type. Sort-of like CSSUnitValue. For now unit types are only "%" or "px", and this object just stores a flag indicating if the value is relative (%) or absolute (px).
Vect2d is a concrete implementation of a PointType class. It is generally slower to create and read than a
"plain" PointType object (eg. from Point.new()), but OTOH is usually faster when being updated/written.
Using Vect2d is generally recommended for stored objects that persist for some time and/or are likely to get modified.
Use logging.getLogger() method (from LogManager) to get a new instance of a Logger.
Returns a Path2D object containing a full or partial circle of tick marks, like a compass or speedometer. Each segment of the resulting path consists of a separate line for each "tick."
Returns a Path2D object containing a full or partial circle of labels, like the markings for a compass or speedometer.
Returns a Path2D object containing tick marks arranged along a straight line, like on a linear thermometer. Each segment of the resulting path consists of a separate line for each "tick."
Returns a Path2D object containing text labels arranged along a straight line, like the markings on a linear thermometer.
Constrain a numeric value between min and max, inclusive.
Rounds to 2 decimal places.
Rounds to 3 decimal places.
Rounds to 4 decimal places.
Rounds to 5 decimal places.
Rounds to 6 decimal places.
Compare 2 floating point values up to a maximum decimal precision represented by epsilon (a small decimal, eg. 0.0001 for 4 decimals).
Returns true if 2 numbers are equal within 3 decimal places of precision.
Returns true if 2 numbers are equal within 4 decimal places of precision.
Returns true if 2 numbers are equal within 5 decimal places of precision.
Returns true if 2 numbers are equal within 6 decimal places of precision.
Left-trims str to maxLen characters and adds an ellipsis at the start if the input string was shortened.
Right-trims str to maxLen characters and adds an ellipsis to the end if the input string was shortened.
Assigns property values in from object to values in the to object, but only if they already exist in to and have a matching typeof type.
Recurses up to recurseLevel nested objects, and skips assigning object-type properties beyond the recursion level. Arrays are copied by value.
If strToNum is true then source string types are considered compatible with destination numeric types (destination is responsible for conversion).
Compares two arrays for strict match on length and each member's value at the same index.
Evaluates a numeric expression within an arbitrary string. Returns zero if evaluation fails or value string was empty. Note that the number formats must be "language neutral," meaning always period for decimal separator and no thousands separators.
Decodes/converts/evaluates a text string sent from TP action data. TP sends all '' escape sequences with '\' so they no longer work automatically (\n, \t, \uNNNN). The Function trick with backticks resolves all that. This also allows embedding interpolated values into a string! Eg. user can send: "2 + 2 = ${2+2}" which will run the calculation in brackets. It even works with TP values embedded inside the {...} part, eg. "Half of a global TP Value = ${${value:dynamic_icon_value_2} / 2}"
Evaluates a string as an array (of any type). Returns an empty array if evaluation fails.
The input string is wrapped in an array before evaluation, so it must be valid JS array content,
otherwise evaluation fails. Any expressions within the array content are evaluated as well.
For example: "1, 2, 3+2" returns [1,2,5].
Parses a string of CSV numbers and inserts them into given dest array. Destination array is not cleared first.
Each individual value in the list is run through evaluateValue() function, allowing math, etc.
Commas inside parenthesis are ignored as separators, allowing use of functions which take multiple arguments.
e.g. "(45 * Math.PI / 2), 20, Math.pow(8, 10)" would result in an array of three values.
If evaluation fails for a value then a zero is used instead (see also evaluateValue()).
If maxCount is not zero then only up to this many values will be parsed.
Values can be optionally filtered by min/max range. Invalid values are silently skipped.
Returns true if any non-zero members were added, false otherwise.
Parses and evaluates up to two values out of a string. e.g. "(45 * Math.PI / 2), 20"
Results are assigned to the returned Vect2d's x and y members respectively.
If only one value is found in the string then it is assigned to the result's y member as well as to x.
An empty value string produces a default zero-length vector.
See also parseNumericArrayString()
Parses a string value into an Alignment enum type result and returns it.
Accepted string values (brackets indicate the minimum # of characters required):
Parses a string containing 1 or 2 alignment values into an Alignment enum type result and returns it.
See parseAlignmentFromValue() for accepted string values for each direction.
Parses a string into an ArcDrawDirection enum value. If no match is found then defaultValue is returned.
Strings must match one of: "Clockwise", "Counter CW", or "Automatic" (case-insensitive).
Returns true/false based on if a string value looks "truthy", meaning it contains "yes", "on", "true", "enable[d]", or any digit > 0.
Returns an integer value contained in string value, or the provded dflt default if value is blank/NaN or is "default".
Returns true if the string value is "truthy," or the provded default if value is blank or is "default".
Image compression options to use when rendering icon images for final output to Touch Portal.
All possible types for canvas fill/stroke style.
Defines how to resize images (or other block elements). Equivalent to CSS object-fit property.
A recursive version of Partial<> type. Accepts any existing property of this object, including child objects and their properties.
Requires at least one of specified properties to be present in an object.
The type of clipping to apply when using ClippingMask element.
Progress bar incremental direction.
Describes the orientation of a linear element.
Describes the drawing direction for a circular path (arc, ellipse, etc). Auto value meaning depends on implementation.
Describes the location of an element in relation to another.
Describes horizontal and vertical alignment values.
Path combining operations for Path type and subclasses.
Transformation operation type, used by Transformation.
Reference documentation for the Touch Portal Dynamic Icons Plugin scripting environment available with the "Run Custom Script" action.
Note that everything described here as being in the global "Variable" is actually just in the global scope of the scripting environment. Those variables and classes are available directly, w/out needing any import or prefix.
All the other types listed on this page are available either directly in the global scope or from the global DI namespace object. See the global reference for details.
The
skia-canvasmodule summary is included here for quick reference, but for complete documentation see http://skia-canvas.org/api.An exported definitions file is available to provide code hinting in compatible editors (such as
VSCode). The defintions describe everything available in the global scope, all skia-canvas types, and all custom types from this reference.Place this file somewhere "close" to your scripts and reference it using a "triple slash directive" at the top of your script, including a relative path. For example, if the declarations file is in the same folder as your script: