Documentation - mpaperno/TouchPortal-Dynamic-Icons GitHub Wiki

NOTE - THIS DOCUMENTATION IS INCOMPLETE!
Many new actions and features have been added in recent versions which are not yet documented. We're working on it!

See also the Examples page.

• Available Actions
  • Draw - Simple Round Gauge
    • Properties
  • Draw - Simple Bar Graph
    • Properties
  • Draw - Image
    • Properties
    • Image Notes
• General Information

• Name: Can be any unique name for this image, it will become the State created by the plugin
• Shadow: On or Off - do you want a light shadow behind your round gauge
• Shadow Color: pick a color any color, only will display if Shadow is On
• Indicator Color: Color of the main round gauge indicator
• Highlight: On or Off - do you want a slight glow/highlight around the round guage (same color as indicator)
• Starting At Degree: 180 (default) - can be any number 0 - 360, 0 is right middle of circle
• Value: the value you want to represent - precentage 0 - 100
• Cap Style: butt|round|square - What do you want the end of the indicator to look like (round looks best)
• Background Color: pick a color any color, if you want no background, set Opacity to 0 in the color selector
• Direction: clockwise|counter clockwise - which way do you want the gauge to go around the circle.

• Name: Can be any unique name for this image, it will become the State created by the plugin
• Background: On or Off - do you want the graph on a background color
• Background Color: pick a color any color, only will display if Background is On
• Bar Color: pick a color any color, this is the color of the bars being drawn
• Value: the value you want to represent - percentage 0 - 100
• Bar Width: 10px (default) - any number of pixels you want the bar graph to look like, 1-256 px

This Action allow you to dynamically create icons from one or more source images. For example images can be "stacked," or overlaid, on top of each other, and/or be transformed at the same time to allow for rotation, movement, or scaling based on static or dynamic input values. In other words is allows for some basic animation effects using any image files which you provide. For example a clock face with 3 rotating hands on top.

• Icon Name: Can be any unique name for this image, it will become the State created by the plugin.
• Image File: Path to an image file. This can be a full (absolute) path on your system, or relative.
  • Relative paths are resolved according to this plugin's "Default Image Files Path" setting in Touch Portal. By default this is your user's Touch Portal "data" directory. This means a relative path with default settings gets you to the base data folder, so for example "iconpacks/Touch Portal Essentials Classics/CameraWhite.png" gets an image from one of the default icon packs.
  • Supported image formats are: PNG, JPEG, SVG, GIF, WebP, TIFF, AVIF
• Resize Fit: How to resize the source image to fit into the icon's final dimensions. The options are:
  • contain - Shrinks or expands the image to fit the image's largest dimension, keeping aspect ratio. The image may be "letterboxed" if not square.
  • cover - Shrinks or expands the image to fit the image's smallest dimension, keeping aspect ratio. The image may be clipped if it is not square.
  • fill - Shrinks or expands the image to completely cover the icon size, ignoring aspect ratio. The image may become distorted if it is not square.
  • scale-down - Same as contain option except it will never expand an image if it already fits into the icon dimensions.
  • none - Do not resize the source image at all.
• Image Transformation Options:
  • Offset: Moves (translates) the image left/right/up/down relative to the other images in the stack.
    • Two values can be provided separated by a colon (:), semicolon (;), single quote ('), or backtick (`).
    • The first value is for the X (horizontal) axis, the second for the Y (vertical) axis. If only one value is provided then it is used for both X and Y coordinates.
    • A value of 100 (%) is equivalent to one full dimension of the produced image (as specified in the Size field). Positive values move the image to the right/down, and negative values move it left/up. For example a translation of (50 : -50) will position the image in the upper right quarter of the resulting composition.
  • Rotate: Rotates the image around the center. A value of 100 (%) equals one full revolution of 360°. 0 means no rotation is applied (image is unchanged).
    • Positive values rotate clockwise, negative goes counter-clockwise.
    • Values greater or less than +/- 100 are allowed (they will just wrap back around to a valid angle).
  • Scale: Resizes the image width and/or height relative to the requested icon size.
    • Two values can be provided here as well (see "Translate" above for syntax). The first value scales the image horizontally, the second one vertically. If only one value is provided, it is used for both dimensions.
    • A value of 100 (%) is equivalent to one full dimension of the produced image (as specified in the Icon Size field). Positive values enlarge the image and negative values shrink it. For example a scale of (50 : -50) will make the image 1.5 times wider and half as tall as the Image Size value (the result would be clipped on the sides).
  • Order: Dictates the order in which the transformation steps (specified above) are applied to the image.
    • The order in which the image rotation/translation/scaling takes place can make a large difference in the result. Depending on what you are trying to achieve and the images you're using, it may be desirable to change this order on an image-by-image basis.
    • For example if you first rotate and then translate an image it effectively changes the center point around which the image rotates (eg. from its bottom edge vs. the default of center). But if you reverse the order, the image will still rotate around its center point, but will do so at whatever new coordinates you moved it to.
    • As another example if you scale an image before moving (translating) it, it effectively scales the movement amount as well. So if the image is downscaled to 50% then moved 100% to the right, its center point will be on the edge of the produced icon instead the whole image being completely out of the frame as it would be if you translated it first.

• The image overlay/stacking feature is designed to work best with images which are all the same size, ideally of square proportions. It is best that the images are prepared so when the overlay stack is constructed or animated, minimal transformation is needed to achieve the desired result. For example a clock hand image be should positioned within the overall square so that simply rotating the whole image around the center point will make it land at the right place on the clock face. Having to move (translate) the hand image into position before/after rotating it would be a lot less efficient and more difficult to set up.
• Input images are cached to improve performance. (Not to be confused with the resulting icons, which are not cached by the plugin.) This means if you modify an image used in one of these actions, the change will not show up until one of the following:
  1. The image file name or location (path) is changed (to a name/location that hasn't been cached yet).
  2. The requested Icon Size is changed (to a value that hasn't been cached yet).
  3. The cache is cleared with the provided plugin action: Dynamic Icons -> System Actions -> Clear the Source Image Cache
  4. The plugin (or Touch Portal) is restarted.

• Math operations in action value fields.
  Almost all the text data field types (with the + icon) will accept JavaScript expressions which are evaluated by the plugin itself (after TP sends the action data to the plugin).
  This is actually a pretty important feature and makes the whole thing a lot more practical.

  • Keep in mind/consider that any Touch Portal value (state, local or global Value, etc) can be used in the value expressions as inputs. So any of this math can be performed on those values right in the action data fields. First select the state/value(s) you want to calculate with, then add the math bits.
  • Supports the full range of basic arithmetic operations one may expect, but also logical, bitwise and conditional (ternary) operators, "regular expressions" (RegEx), and quite a bit more.
    • See the MSDN JavaScript Operators for a full reference
  • Supports JavaScrip's Math functions and constants, for rounding, min/max range control, algebra, trigonometry, and more.
    • See the MSDN Math documentation for a full reference. Function names must be prefixed with Math. as shown in the examples.
  • As a very basic example: A button which requests a new dynamic icon on each press with a random rotation value. After specifying the icon name, desired size, and an image file, you could put the following in the "Rotate" value field: Math.random() * 100. "Math.random()" produces a random number between 0 and 1, which we then multiply by 100 to get a random final value (percentage of 360°).

• Image processing can be quite "expensive" computationally and it is possible to overload even a very fast computer with a lot of image requests at the same time. Having a real GPU (graphics processor) installed will offload some of the work. And remember all that generated image data has to be sent to TP desktop and then to the client device (possibly over slow WiFi). Do not expect miracles. Do use a fast wired connection to your TP client device if you can.

• Have fun and experiment!!!