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 = 1000, restartAtEnd = true)
{
  // Make sure any currently running marquee animation is stopped.
  marqueeStop();
 
  // If text fits into maximum length then just return the text as-is
  // (this automatically sends the correct State update to Touch Portal).
  if (text.length <= maxLength)
    return text;
 
  // track the first character of the text to show in the scrolling marquee
  var start = 0;
 
  // This function sends the State update to TP with a portion of the full text.
  function update()
  {
    // Bail out if animation stop has been requested.
    if (!_data.runMarquee)
      return;
 
    // Get just the portion of the text to send this time.
    const result = text.slice(start, start + maxLength);
    // And send it.
    TP.stateUpdate(result);
 
    // Check if end of text is visible
    if (start + maxLength >= text.length)
      start = 0;  // Restart the counter at first character.
    else
      ++start;  // Increment the starting character position.
 
    // if we're at the end of the text and restart wasn't requested then exit now.
    if (!start && !restartAtEnd)
      return;
 
    // Schedule a timer for next scroll animation "frame."
    // If we're at the start or end of the text then use the startDelay, otherwise the scrollDelay.
    _data.timerId = setTimeout(update, start > 1 ? scrollDelay : startDelay);
  }
 
  // Set the "run" flag (the animation can be cancelled with `marqueeStop()`)
  _data.runMarquee = true;
  // Send the first part of the text now.
  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).