Scroller
Version 0.250514

by Craig Hendricks
codefenix@conchaos.synchro.net

ConstructiveChaos BBS:
  https://conchaos.synchro.net
 telnet://conchaos.synchro.net
    ssh://conchaos.synchro.net



Description:

  This mod shows text files to your users using a scrollable interface. 
  The user uses the up, down, page up, page down, home, and end keys
  to scroll through the file.
  
  In addition to plain text files, it's also capable of displaying
  files containing ANSI as well as files containing CTRL-A colors, 
  and has support for iCE colors (i.e.: bright backgrounds) and font 
  switching (if the SAUCE data includes it), making it a great option 
  for viewing ANSI art and colorized bulletins.



Basic Instructions:

  IMPORTANT NOTE:
  
  This mod makes use of the graphic.js library in /sbbs/exec/load. If
  you find that ANSI files fail to load completely, the most likely
  reason is your graphic.js file is out of date, so make sure you have 
  the latest version from:
  https://gitlab.synchro.net/main/sbbs/-/tree/master/exec/load
  
  

  Create the path:
  
    /sbbs/xtrn/scroller

  Now simply place the scroller.js file into it.
  
  That's it.
                             
  The InterBBS OneLiners (ibol.js), NewsCenter (newscenter.js), and 
  Digital Showroom (dsr.js) scripts are all designed to use scroller.js 
  as the default text viewer, falling back to Synchronet's standard 
  console output with page pauses if it's not present in the 
  /sbbs/xtrn/scroller path.
  
  Optionally, place the included text_sec.js file into /sbbs/mods to 
  use Scroller as your default text viewer for your General Text Files 
  section.
  
  If the user is not using ANSI, then Synchronet's standard console
  output with page pauses will be used by default.
  


Advanced Instructions:

  To utilize Scroller in your own scripts, the syntax is as follows:
  
    ?../xtrn/scroller/scroller.js <path_to_file> [title] [top/bottom]

    path_to_file: Required. This is the fully qualified path 
                  to the text file to be shown.
                  
           title: This is the title to display in the line above
                  the file viewer. If left blank, the filename 
                  (without the directory) is used by default.
                  
      top/bottom: This is the starting position in the file when
                  displayed. Default is "top" (the only valid 
                  value here is "bottom", and anything else results
                  in the file starting at the top).
                  
  You must wrap path_to_file and title in double-quotes if they 
  contain spaces.
  
  Example: 
  
  bbs.exec('?../xtrn/scroller/scroller.js "c:\\bbs_bull.txt" "Latest Bulletin" top');

  Colors can be changed by modifying the C1 and C2 variables near the
  top of the script. C1 is the main text in the top & bottom bars, and 
  C2 is the secondary text color for symbols and such. I plan to make 
  this more easily modifiable in the future, with optional unique configs 
  for each script that calls it.

  ANSI files containing a lot of cursor movement sequences are assumed 
  to be animations (i.e.: ANSImations), in which case they are simply 
  output to the console instead of the Scroller window, since Scroller 
  would not be able to "scroll" the file.  
    
  If a file contains enough cursor movements, it could be falsely treated as
  an ANSImation. Increase the value of ansi_cursor_movement_limit to increase
  the number of cursor movements Scroller will tolerate.
  
  Similarly, if Scroller detects any ANSI Music sequences in the file, it will
  output it to the console so the ANSI Music can be played as expected.
   


Background and purpose:

  The idea for this script came about because I wanted an easy way to 
  let users view the InterBBS One Liner wall (IBOL) without having to 
  force the user to view the entire wall from the top, making them have
  to go through potentially many, many screen pauses to reach the end.
  
  Mystic BBS offers a nice scrollable text viewer out of the box, and I 
  wanted to do the same thing in Synchronet. While there *is* an optional 
  module for Synchronet (named bullshit) which does view files in such a 
  way very nicely, its true intent is for a selection of pre-defined 
  bulletins, rather than a single specific file on an ad hoc basis, which 
  is what I wanted.

  Once I got the basic logic working within IBOL, I realized it could be made
  portable and called by other scripts for displaying text files, and with
  not much more effort, would be nice for viewing ANSI files as well.
  
  I now use this as my main viewer for text and ANSI files all over my BBS.

  

Limitations:

  - ANSIs wider than the terminal width are limited to the leftmost columns
    that the terminal can display (e.g.: only the leftmost 80 columns will 
    be shown in an ANSI that is 80 columns wide). I considered implementing
    horizontal scrolling for wide ANSIs, but ultimately decided it would be
    difficult and not worth the effort. Also, forcing horizontal scrolling 
    just creates bad user experience in my opinion anyway (there's a reason
    websites scroll vertically, and seldom scroll horizontally). Maybe I'll 
    reconsider some day, but for now, Scroller will simply inform the user 
    about the width limitation and advise them to call back with a higher 
    terminal width that can better accommodate the ANSI.
  
  
  
Thanks & Greetz:

  Big thanks to the following for testing and providing feedback!
  
  StingRay @ A-Net Online:
    - a-net-online.lol  
    - mystic.a-net-online.lol 

  xbit @ The X-Bit BBS:
    - x-bit.org 

  Amessyroom @ Too Lazy BBS:
    - toolazy.synchro.net
    


Version History:  

v 0.250514 - May 14, 2025:

  + Improved detection for ANSI animations.
  + Added detection for ANSI music, file gets output to standard 
    console.printfile just like animations if detected.
  + Added important note regarding the graphic.js library to this readme file.
  + Fix to reset top and bottom margins in case an animation file changes them.

v 0.250509 - May 9, 2025:

  + Additional CTRL-A fixes to ensure proper color intensity.

v 0.250508 - May 8, 2025:

  + Fix for loss of CTRL-A colors while scrolling them out of range.

v 0.250410 - April 10, 2025:

  + Support for detecting files containing ANSI and loading it into a
    Graphic object.
  + Support for ANSI containing SAUCE data, for enabling iCE color mode
    and font switching (limited to Amiga Topaz).
  + Support for detecting ANSI file width and advising user accordingly.
  + Support for detecting cursor movements, and displaying the ANSI 
    animation if enough are detected.

v 0.20241105 - November 11, 2024:

  + Initial version. 
