Marquee Text Example

Scrolls long text horizontally with only a portion visible at one time.

See the published documentation for a properly formatted version of this README.

This script's main function, marquee(), takes a line of text as input and updates a Touch Portal State with a portion of that text visible (up to a specified maximum length), pauses for some time, then sends the next set of characters that should be visible. This creates a scrolling animation like a marquee.

marquee() takes some optional parameters to specify how quickly the text should scroll, how long to delay before starting, or re-starting, the scroll, and whether to restart the scroll after showing the full text once. See comments in the script itself for more details.

Note

This code can also be found in the project's repository at
https://github.com/mpaperno/DSEP4TP/tree/main/resources/examples/Marquee/

/*
This script is designed to run in a Private engine instance
and will update the State Name of whichever action invoked the `marquee()` function.
 
`marquee()` function parameters:
 `text` - The full text to show.
 `maxLength` - The maximum number of characters to show at one time.
               If `text` length is <= `maxLength` then the whole text will be shown at once, with no scrolling.
 `scrollDelay` - This is the scroll delay in milliseconds; it dictates how quickly the text scrolls.
 `startDelay` - How many milliseconds to wait before (re)starting the scroll. This can create an extra pause at the start and at the end of the text.
 `restartAtEnd` - Whether to restart the scroll animation after all the text has been shown once.
*/
var marquee = function(text, maxLength = 32, scrollDelay = 200, startDelay = 0)
{
  marqueeStop();
 
  if (text.length <= maxLength)
    return text;
 
  // track the first character of the text to show in the scrolling marquee
  var start = 0;
  var firstCycle = true;
  text += " - " + "\u2000".repeat(maxLength);
 
  function update()
  {
    if (!_data.runMarquee)
        return;
 
    const result = text.slice(start, start + maxLength);
 
    TP.stateUpdate(result);
 
    if (start + maxLength >= text.length) {
      start = 0;  // Restart the counter at first character.
      if (firstCycle) {
        text = "\u2000".repeat(maxLength) + text;   //  <<<  EDIT
        firstCycle = false;
      }
    }
    else {
      ++start;  // Increment the starting character position.
    }
 
    _data.timerId = setTimeout(update, start > 1 ? scrollDelay : startDelay);
  }
 
  _data.runMarquee = true;
 
  update();
}
 
// This function can be used to stop/cancel the scrolling animation at any point.
// It is also called by `marquee()` to ensure any current animation is stopped before
// starting a new one.
var marqueeStop = function() {
  // Set flag for `update()` function
  _data.runMarquee = false;
  // Cancel any running timer
  if (_data.timerId > -1)
    clearTimeout(_data.timerId);
  // reset timer ID
  _data.timerId = -1;
}
 
// These variables are used internally to stop/cancel the marquee scroll.
var _data = _data || {
  timerId: -1,
  runMarquee: false
}

Example usage on a button

In an actual button/flow you would most likely put the action inside an event handler which reacts to a change in a State/Value you would like to display, and put that State/Value's macro inside the quotes of the marquee() call, instead of my static example. Eg.

marquee("${value:com.github.ChristopheCVB.TouchPortal.Spotify.TouchPortalSpotifyPlugin.BaseCategory.state.currentTrackName}")

Cancel marquee scroll

The script also has a function to cancel/stop the scroll animation on demand. Here is an example of a button for that.
The key point is that it uses the same State Name as the action which started the marquee to begin with (and also runs in a Private instance).