====== How to use Display Codes ======

Mystic Display Codes are found throughout the BBS in various prompts and display files.  The purpose of these codes is to replace the code with a corresponding value for that code.  For example, if you wanted to display the user's name, there is a code which when parsed in a prompt or file would be replaced with the current logged in user name.

The format for all codes consists of a starting pipe character (|) followed by two characters which are used to represent what data Mystic will replace the code with.  These codes are **CASE SENSITIVE** although currently almost all codes use upper-cased letters.

An example of an MCI code and how it would be processed by Mystic would be:

     Welcome the BBS, |UH.

In the above example, |UH is the MCI code for the user's handle.  If the current user online had a account handle of "Joe User", then the result of the above example after being processed by Mystic would be:

     Welcome to the BBS, Joe User.

**NOTE:** Certain display codes require additional data to be provided after the code.  These types of codes are used to do many advanced things such as text formatting, changing the way input fields look and work, saving/restoring the remote user's screen, terminal cursor manipulation, all the way through to popping up confirmation windows and performing various other BBS functions.

The additional data required for these types of codes will vary and will be documented specifically within the sections that follow.

====== Display Code Formatting ======

Text formatting codes are most often used within the prompts file to create aligned lists of data, for things such as the user list or who's online, etc.  These codes, like many other display codes, set up the circumstances in which the display code after it are displayed.

Note: ## should be replaced by the number noted in the description, and must always be two characters.

<code>
   $C##  - Centers the value of the next display code with a width of ##
   $D##C - Duplicates character C ## times
   $L##  - Left pad the next display code with spaces to ## characters
   $R##  - Right pad the next display code with spaces to ## characters
   $T##  - Trim a value to ## length. Do nothing if its less than ## length
   $X##C - Duplicate character C until column ##
   $c##C - Centers the value of the next display with a width of ## using
           character C
   $l##C - Left pad the next display code with character <C> to ## characters
   $r##C - Right pad the next display code with character <C> to ## chars
   PD    - Pad the next MCI code value with a single space ie |PD|MB
</code>

Examples:

<code>
      |UN translates to........: "User Name"

      |$R30|UN translates to...: "User Name                     "
      |$C30|UN translates to...: "          User Name           "
      |$L30|UN translates to...: "                     User Name"

      |$D30- translates to.....: "------------------------------"
      |$X30- translates to.....: "------------------------------"

      |UN|$X30. translates to..: "User Name....................."

      |$c30.|UN translates to...: ".........User Name..........."
      |$r30.|UN translates to..: "User Name....................."
      |$l30.|UN translates to..: ".....................User Name"
</code>

The difference between $D and $X is that D duplicates a set number of characters, while $X duplicates that character until a certain column is reached.  If you use $X30- on column 10, it will create 20 characters so it is dependent on the current location of the cursor, while $D will always create the same length of data regardless.

====== BBS and User Information Codes ======

   AG - User's age in years
   AS - User's auto signature (On or Off)
   AV - User's chat availability for user to user chat (Yes or No)
   BD - User's baud rate (returns TELNET or LOCAL) (may be removed)
   BI - User's birth date in their selected date format
   BL - BBS location as set in System Configuration
   BN - BBS name from System configuration
   CM - User's full screen node chat setting (On or Off)
   CS - User's total number of calls to the BBS
   CT - User's total number of calls to the BBS today
   DA - Current date in the user's selected date format
   DK - User's total downloads in kilobytes
   DL - User's total number of downloaded files
   DN - Returns the configured BBS domain name
   DP - User's default protocol or blank if one is not set
   DT - User's total number of downloads today
   FB - User's current file base name
   FDxx Returns the flag description where xx defines the set and the flag.
        For example FD1A would return the description for flag set 1, flag A.
   FG - User's current file group name
   FK - User's total uploads in kilobytes 
   FLxx Returns the ON/OFF prompt depending on the user flag state. The xx
        defines the set and the flag, for example: FL1A would return on/off
        state of the user's A flag in flag set 1.
   FO - User's first call date in their selected date format
   FS - User's file group (short name)
   FT - Total number of files in current file base (dynamic)
   FU - User's total number of files uploaded
   HK - User's hotkey setting (On or Off)
   IL - User's node status invisibility (On or Off)
   KT - User's downloads in kilobytes today
   LO - User's last call date in their selected date format
   MB - User's current message base name
   MD - Menu description of the current menu (from menu flags)
   ME - User's total number of e-mails sent
   MF - Shows number of draft messages saved for the current user
   MG - User's current message group name
   ML - User's lightbar message index setting (On or Off)
   MN - Network description of the current message base
   MP - User's total number of message posts
   MS - User's message group (short name)
   MT - Total number of messages in current message base (dynamic)
   MU - Total unread personal messages *
   MW - Total personal messages *
   NA - number of active users currently logged in
   ND - Current node number
   NE - Minutes until next BBS-type event
   NT - maximum number of allowed nodes/terminal connections
   OS - Operating system (Windows, Linux, Raspberry Pi, etc)
   PC - User's current post to calls ratio
   PW - Configured number of days before required password change
   QA - User's selected archive format (QWK, etc)
   QE - User's Generate QWKE setting (Yes or No)
   QL - User's Include QWK file listing setting (Yes or No)
   RD - User's download ratio for their current security level (files)
   RK - User's download ratio for their current security level (kilobytes)
   SB - User's max allowed minutes in time bank for current security level
   SC - User's max calls per day allowed for current security level
   SD - User's current security level description
   SK - User's max allowed download kilobytes per day for current sec level
   SL - User's current security level number
   SN - Configured Sysop name
   SP - Configured post call ratio for the current security level
   ST - Configured allowed minutes per day for current security level
   SX - User's max allowed downloaded files per day for current security level
   TB - User's timebank minutes
   TC - Total number of calls to the BBS system (as of your call)
   TE - User's terminal emulation (Ansi or Ascii)
   TI - Current time of day in 12 hour format
   TL - User's time left in minutes
   TO - User's time spent online this session (in minutes)
   TM - Displays current time in HH:MM 24-hour format
   TS - Displays current time in HH:MM:SS 24-hour format
   U# - User's number (aka permanent user index)
   U1 - User's optional data answer for question #1
   U2 - User's optional data answer for question #2
   U3 - User's optional data answer for question #3
   UA - User's address
   UB - User's file listing type (Normal or Lightbar)
   UC - User's city, state
   UD - User's data phone number
   UE - User's message editor type (Line, Full, or Ask)
   UF - User's Date input format (MM/DD/YY, DD/MM/YY, YY/DD/MM)
   UG - User's gender (Male or Female)
   UH - User's handle (alias)
   UI - User's User information field
   UJ - User's message reader type (Normal or Lightbar)
   UK - User's email address
   UL - User's selected theme description
   UM - User's lightbar message index setting (On of Off)
   UN - User's real name
   UO - User's country of origin (as detected by IP/Country blocking)
   UP - User's Home phone number
   UQ - User's full screen editor quote mode (Standard or Lightbar)
   US - User's screen size lines (ie 25)
   UX - User's computer/router/internet host name
   UY - User's IP address
   UZ - User's zip (postal) code  
   VR - Mystic BBS version number
   XD - Days left before the user's account expires (or 0 if none)
   XS - Security level in which the user's account will expire to
   
  * The MW/MU code values are only populated after the MC menu command is executed.
   
====== Color Codes (Pipe Colors) ======

The typical pipe format of <pipe>## where ## is one of the following:

**Setting Foreground color:**

   00 : Sets the current foreground to Black
   01 : Sets the current foreground to Dark Blue
   02 : Sets the current foreground to Dark Green
   03 : Sets the current foreground to Dark Cyan
   04 : Sets the current foreground to Dark Red
   05 : Sets the current foreground to Dark Magenta
   06 : Sets the current foreground to Brown
   07 : Sets the current foreground to Grey
   08 : Sets the current foreground to Dark Grey
   09 : Sets the current foreground to Light Blue
   10 : Sets the current foreground to Light Green
   11 : Sets the current foreground to Light Cyan
   12 : Sets the current foreground to Light Red
   13 : Sets the current foreground to Light Magenta
   14 : Sets the current foreground to Yellow
   15 : Sets the current foreground to White

**Setting Background color:**

   16 : Sets the current background to Black
   17 : Sets the current background to Blue
   18 : Sets the current background to Green
   19 : Sets the current background to Cyan
   20 : Sets the current background to Red
   21 : Sets the current background to Magenta
   22 : Sets the current background to Brown
   23 : Sets the current background to Grey

Depending on the terminal the 24-31 codes can have different results.  Some terminals will use what is often referred to as "ICE colors" which are the non-blinking brighter backgrounds.  Others may use blinking foreground text instead.

**TERMINALS THAT USE BRIGHT BACKGROUNDS (ICE COLORS):**

   24 : Sets the current background to Dark Grey
   25 : Sets the current background to Light Blue
   26 : Sets the current background to Light Green
   27 : Sets the current background to Light Cyan
   28 : Sets the current background to Light Red
   29 : Sets the current background to Light Magenta
   30 : Sets the current background to light Yellow
   31 : Sets the current background to light White

**TERMINALS THAT USE BLINKING:**

   24 : Sets the current background to black with blinking foreground
   25 : Sets the current background to blue with blinking foreground
   26 : Sets the current background to green with blinking foreground
   27 : Sets the current background to cyan with blinking foreground
   28 : Sets the current background to red with blinking foreground
   29 : Sets the current background to magenta with blinking foreground
   30 : Sets the current background to brown with blinking foreground
   31 : Sets the current background to grey with blinking foreground

Each Theme in Mystic BBS can also have a set of custom colors configured specifically for that theme.  These can be accessed by using the following codes:

   T1 : Sets current color to theme's color #1
   T2 : Sets current color to theme's color #2
   T3 : Sets current color to theme's color #3
   T4 : Sets current color to theme's color #4
   T5 : Sets current color to theme's color #5
   T6 : Sets current color to theme's color #6
   T7 : Sets current color to theme's color #7
   T8 : Sets current color to theme's color #8
   T9 : Sets current color to theme's color #9
   T0 : Sets current color to theme's color #0

====== Screen/Cursor Related Codes ======

The following codes found in this section are used to manipulate the cursor location and/or various other terminal specific codes.  The majority of these codes will require that the user has an ANSI-BBS capable terminal or better.  Mystic will simply filter out codes that require ANSI and do nothing when they are encountered if the user does not have a capable terminal.

Note: ## should be replaced by the number noted in the description, and must always be two characters.  For example, to move to column 1 on the current line you would use "|[X01" (without the quotation marks, of course).

   [0   - Sends terminal hide cursor (support will depend on terminal)
   [1   - Sends terminal show cursor (support will depend on terminal)
   [A## - Move the cursor up ## lines
   [B## - Move the cursor down ## lines
   [C## - Move the cursor forward (to the right) ## columns
   [D## - Move the cursor backwards (to the left) ## columns
   [K   - Clear from the current cursor position to the end of the line
   [L   - Move cursor and erase data backwards from current column to column ##
   [X## - Move cursor to X coordinate ##
   [Y## - Move cursor to Y coordinate ##
   BS   - Sends 1 destructive backspace sequence (ASCII 8-32-8)
   CD   - Resets the remote terminal color mode to the theme default
   CL   - Clears the screen (ANSI 1,1 locate and [2J or ASCII 12)
   CN   - Turns iCE colors OFF (if terminal supports it)
   CR   - Send a carrage return and line feed (move to next line)
   CY   - Turns iCE colors ON (if terminal supports it)
   LC   - Loads the last color mode (ICE/Blinking)
   LF   - Loads the last font
   RA   - Restore the saved text attribute color
   RS   - Restore the saved user's terminal screen
   SA   - Save the current text attribute color
   SS   - Save the entire user's terminal screen'
   
Each theme can optionally have a font type defined for it.  When a theme
font type is defined, Mystic will swap to that font when the theme is
loaded (support depends on the terminal used).  There are also a few codes
that can be used for font manipulation:

   SF## - Set the current terminal font where ## is:
   
     01 - Default      > Sends the "set default font" sequence
     02 - IBM CP437    > Switch to IBM CP437 font
     03 - Topaz        > Switch to Amiga Topaz
     04 - Topaz+       > Switch to Amiga Topaz Plus
     05 - MicroKnight  > Switch to Amiga MicroKnight
     06 - MicroKnight+ > Switch to Amiga MicroKnight+
     07 - mo'sOul      > Switch to Amiga mo'sOul
     08 - p0t NOoDLE   > Switch to Amiga p0t NOoDLE
   
   TF - Resets terminal font to theme's default (if one has been configured)
   
====== Input Field Manipulation Codes ======

Input field codes affect the next input field of its type, and are generally used in prompts that are displayed to the user prior to asking the user for input.

<code>
   -N   - Forces the next Yes/No prompt to default to a No answer
   -Y   - Forces the next Yes/No prompt to default to a Yes answer
   IB   - Turns off input barrier for the next string input
   IF   - Turns off the input field background color for the next input
          prompt.
   IN## - Sets the scrolling input field size for the next input prompt to
          ## characters.  If the maximum size of the input field is larger
          than this, Mystic will scroll the text inside so that it can
          accept more characters without taking up more than ## columns on
          the screen.
   IS## - Limits the actual maximum number of characters allow for an
          input prompt to ## characters.
</code>

====== Text Box / Pick List Codes ======

Text Box codes are used to pop up a quick notification box, using the configured ANSI box style which is configured in each theme.  Pick lists create a horizontal or vertical list of options that are presented to the user to select via hotkey or lightbars.

In addition to just displaying a box, Mystic is able to use its remote screen imaging to save what the user's screen looks like before displaying the box, and then restore the user's screen after the box is closed.  This screen restoration prevents the user's screen from being "corrupted" regardless of what they are doing when the box is displayed.

User and BBS data MCI codes, along with pipe color codes can be used within these boxes!

**#B<style>#<Y position>#<header>#<text>#**

The #B code opens a <style> notification box with a <header> and <text> string, at <Y position> following by an "OK" prompt for the user to press a key.  After the user pressed a key, Mystic will automatically restore the user's original screen content that was overwritten by the box.  The <style> option is one of the four different styles found in the themes menu.

Example:
<code>
         |#B#1#12#This is a header#This is a test notification box!#
</code>

**#H#<color>#<high_Color>#<desc_color>#<selected>#<options#**
  
  Create a horizontal menu with an optional description line below it
  similar to the "Lightbar/Prompt" style menus in Mystic or prompts
  similar to what might be found in Searchlight BBS.
  
  The <color> represents the text color attribute for the standard text
  of the selection.  The <high_color> represents the highlighted color when
  the item is selected.  <desc_color> is used only when a description is
  assigned to a selection and represents the color of the description text.
  
  As with other places where an attribute number is defined the value can
  be calculated be the following formulate FG + (BG * 16) so FG color of white
  (16) or a blue (1) background would be 15 + (1 * 16) which is 31.
  
  <options> consists of a comma-separated list of key/text pairs defined as
  key-text where key is the hotkey and text is what is lightbar selectable.
  
  A horizontal lightbar menu with two light bar options would look like this:
  
     <pipe>#H#7#31#14#2A-Option A,B-Option B#
  
  The above would create a horizontal lightbar menu with two options called
  "Option A" and "Option B" with the first having a hotkey of A and the second
  a hotkey of B.  The text would be attribute 7 (grey) and the highlighted
  text would be white on blue background (attr 31).  The third field would
  not be used because there is no description defined for any of the options
  and the fourth option is says to default to the second option (Option B)
  when opening the menu.
  
  Descriptions can be applied to each option by putting those values in
  brackets in the item name.  The description will be displayed on the line
  under the lightbar menu:
  
     <pipe>#H#7#31#14#2A-Option A[Option A description here],B-Option B#
  
  Pipe color codes can be used in the option names and will be rendered as
  expected when the item is not highlighted.

**#I#<style>#<Y position>#<header>#<text>#**

This box is similar to the #B notification, except that it does not restore the user's screen content after displaying, and it does not wait for the user to press a key.  One use for this might be during a new message scan "Scanning" prompt, for example.
       
Example:
<code>       
         |#I#1#12#New Message Scan#Scanning: |&1...#
</code>

**#V#<style#>#<X position>#<Y pos>#<header>#<commands>#**

Performs a pop up vertical selection box, with the selected item hotkey being pushed into the input buffer, and the screen restored to its original state after selection.  This only works with ANSI graphics. The format is:

  Syntax: |#V#<style#>#<X position>#<Y pos>#<header>#<commands>#

<Commands> is a comma separated list of commands in the format of <hotkey>-<text>.  If <text> is blank, the hotkey will be allowed by not shown in the list.  If the entire entry is blank a blank line will be inserted into the list.

Example:

  |#V#2#30#10# Header #A-Selection A,B-Selection B,C-Selection C#

Creates a pop up lightbar box in style 2, starting at X30 Y10 that has three options:

<code>
        .----- Header ----.
        |  A Selection A  |
        |  B Selection B  |
        |  C Selection C  |
        `-----------------'
</code>
When an item is selected, Mystic sets the color to black on black and pushes the hotkey into the input buffer, so that the prompt it replaced gets the input key.


**#X#<style>#<header>#<x1>#<y1>#<x2>#<y2>#**

Draws a box using a specific theme style.  It does not take input or erase itself at all.
<code>
     Format  : |#X#<style>#<header>#<x1>#<y1>#<x2>#<y2>#
     Example : |#X#2# My Header #20#10#60#16#
     Result  : Opens a box at X20 Y10 to X60 Y16 using style 2 and
               header " My Header "
</code>
**#Y#<style #>#<Y position>#<header>#<text>#**

Performs a popup Yes/No box and the result will be used as the following YES/NO answer.  Mostly to be used in the "prompt" of a yes/no question.  The format is:

<code>
Syntax:  |#Y#<style #>#<Y position>#<header>#<text>#
Example: |#Y#2#10#Confirm#Do you want to do this?#
</code>

The above example will pop up a Y/N box using style 2 with a header of "Confirm" and a message box text of "Do you want to do this?".

After the YES/NO box, Mystic will restore the screen to the original state before the box was shown.  This function only works with ANSI graphics.


====== Miscellaneous Codes ======

This section contains codes that are the special snowflakes of Mystic BBS!  They do not fit well into any of the other categories of codes, so they find a home here.  While they may be different, it does not mean that they're any less capable!

   AA   - Used in display files to enable aborting of the display file
   AO   - Used in display files to disable aborting of the display file
   BE   - Sends a ^G character (causes some but not all terminals to beep)
   CHx  - Sends character x for example |CH| would send a pipe character
   DE   - Delay for half a second
   HXxx - Sends a hex byte. For example ASCII 254 is FE in hex so HXFE would send 
          out ASCII 254.
   PA   - Send the pause prompt and wait for a key to be pressed
   PB   - Purge the current input buffer
   PE   - Pause and wait for the ENTER button (no prompt)
   PI   - Display a pipe symbol (|)
   PN   - Wait for a key to be pressed without prompting
   PO   - Used in display files to disable pausing for that display file
   RP## - Sets the internal screen pause line counter to ##
   SI   - returns the "ID" of the server that the user connected through 
          (as defined in the Server Configuration) or blank if the connection did
          not source through MIS.
   XX   - Returns no value.  Seriously.  None.

   DF<file>| Send display file <file>.  Note the trailing pipe code which must be
             used if there is any text to be parsed after the DF code is encountered.
             Example: |DFmyansi|

   DI## - Sets the baud rate emulation of the current display file, using the
          following scale:
  
            00      = No baud emulation (full speed)
            01 - 09 = 300 baud
            10 - 19 = 1200 baud
            20 - 29 = 2400 baud
            30 - 39 = 4800 baud
            40 - 49 = 9600 baud
            50 - 59 = 19200 baud
            60 - 69 = 28800 baud
            70 - 79 = 38460 baud
            80 - 89 = 57600 baud
            90 - 99 = 115200 baud

   QO - Replaced with a randomly generated Quote of the Day
   
   Mystic will select and display a random chunk of text from quotes.dat in the DATA
   directory.  The format of quotes.dat is a text file which contains lines of text
   separated by a single asterisk before each quote.  For example:
   
     *
     This is sample Mystic BBS quote #1.
     This is also quote #1
     *
     This is sample Mystic BBS quote #2.
     *
     This is sample Mystic BBS quote #3. 

====== Prompt Information Codes ======

Prompt Information codes are used within the prompts found in a theme's prompt file.  The value of each Prompt Information Code is dynamic, meaning it's value changes depending on each specific prompt.

The prompt editor and the prompt file itself will have comments that show what each code translates to for that particular prompt.  For an example, lets look at prompt #334:

     ; &1 = Current message number  &2 = Total messages
     334 Jump to which message? (1-|&2):
 
In this prompt, |&1 is replaced by the current message number, and |&2 is replaced by the total number of messages in the message base.  These values are noted in the comments for that particular prompt in both the prompt editor and the text-based prompt file itself.

Prompt Information codes can range from |&0-|&9, and from |&A-|&Z

====== Screen Info Codes (Depreciated) ======

Screen Info codes follow the format of |!# where # is a number between 0 and 9.  These codes are found in the old style of ANSI templates used within various "full screen ANSI" functions of Mystic BBS, and they are used to define screen location and attributes used within that specific function.

These codes are not going to be documented here, as they have been depreciated.  Each template that uses these types of codes is slowly being removed in favor of the "newer" style of template, which uses an .INI file to define screen locations, attributes, prompts, and other options specific to that BBS function.

In other words they are still used in the old-style templates but moving forward they will no longer be used in any new functions added into Mystic BBS.