AnsiCmd Class Link Library

Table of Public Methods

The following is a list of AnsiCmd public methods, grouped by function.
Most public methods begin with the letters “ac” (Ansi Command).

The basic methods use ANSI escape sequences directly. Some of these methods use C-library function calls to perform terminal configuration.

A few methods are implemented at a higher abstraction level (API level). These are referred to in the documentation as Application-Program-Interface API methods. These methods typically do not use the ANSI escape sequences directly, but instead call a sequence of low-level (primitive) methods to provide a less cluttered interface between the application and the AnsiCmd library.

See also the ACWin Class in the next chapter which provides a more sophisticated user interface whose functionality lies somewhere between the raw ANSI escape sequences and the dialog-oriented interface of the author’s NcDialog API.
Please see By the Same Author for more information.

Configuration Methods

• AnsiCmd ( void );

    Input  : none
  
    Returns: implicitly returns a pointer to object
  

  Default Constructor: Terminal configuration parameters are set to default values.
  Please see TermConfig Class for details on default values.

  The usefulness of the default constructor is miniscule, and possibly full of surprises for the programmer and the user alike. It is strongly recommended that the initialization constructor (see below) be used for all non-trivial applications.

  
  
• AnsiCmd ( const TermConfig& tCfg );

    Input  : tCfg : (by reference) terminal configuration parameters 
  
    Returns: implicitly returns a pointer to object
  

  Initialization Constructor: Terminal configuration parameters are passed in the TermConfig object.

  Configuration options can be established directly by the application startup code, or if preferred, can be specified by the user as command-line options, see Invoking.

  Please see TermConfig Class for details on parameter values passed to the constructor.

  Programmer’s Note: The AnsiCmd class should be instantiated before any data is sent to the terminal’s output stream. This is because the first output may override any subsequent output-stream width designation for the current session. Note that the wide (32-bit character) stream is strongly recommended for all modern applications. The narrow stream is outdated due to its close ties to ASCII text (and to 1970).

  
  
• virtual ~AnsiCmd ( void );

    Input  : none
  
    Returns: nothing
  

  Destructor. Return all resources to the system before exit.

  The destructor is invoked either by deleting the object:
      AnsiCmd *ansicmdPtr = new AnsiCmd( termConfig );
    delete ansicmdPtr;
  OR when the object goes out-of-scope.

  
  
• WinSize acGetTermSize ( void );

    Input  : none
  
    Returns: current terminal dimensions in a WinSize object
  

  Returns the terminal dimensions in both character cells and pixels.

  The WinSize structure is defined in /usr/include/bits/ioctl-types.h, and is one of the many system configuration parameters handled by the C-library ioctl function.

     struct winsize
     {
        unsigned short int ws_row;
        unsigned short int ws_col;
        unsigned short int ws_xpixel;
        unsigned short int ws_ypixel;
     };
  

  Note on terminal dimensions: Although the environment may contain the terminal dimensions when the application was invoked, this is a _copy_ of the environment, not the active environment, and therefore will not reflect user changes to the terminal window size while the application is active.

  The $LINES and $COLUMNS are available from the environment at the command line (“echo $LINES” and “echo $COLUMNS”), but are not exported to programs running in the terminal window.

  Note also that the pixel dimensions will probably be returned as zeros because under Wayland, the terminal program likely doesn’t know the screen resolution.

  
  
• bool acGetTermDimensions ( short& rows, short& cols );

    Input  : rows  : (by reference) receives number of terminal rows
             cols  : (by reference) receives number of terminal columns
  
    Returns: 'true'  if terminal dimensions are known
             'false' if system call to get terminal dimensions failed
  

  Reports the dimensions of the terminal window in rows and columns.

  
  
• bool acGetTermInfo ( TermStream tStream, TermIos& tIos, bool orig = false );

    Input  : tStream : one of stdIn, stdOut, stdErr
             tios    : (by reference) receives settings
             orig    : (optional, 'false' by default)
                       'false': the current terminal settings are returned
                       'true' : the original terminal settings are returned
  
    Returns: 'true'  if settings captured
             'false' if system error
  

  Get a copy of the current terminal I/O stream configuration (or the original settings captured on application start-up).

  This is a pass-through to the private TermSet method.

  (This method is primarily for development and debugging.)

  Terminal I/O Setting structure (defined in C library, termios.h) struct termios { tcflag_t c_iflag ; /* input mode flags */ tcflag_t c_oflag ; /* output mode flags */ tcflag_t c_cflag ; /* control mode flags */ tcflag_t c_lflag ; /* local mode flags */ cc_t c_line ; /* line discipline */ cc_t c_cc[NCCS] ; /* control characters */ } ; tcflag_t is an unsigned integer (uint16_t) bit-field type. cc_t is an unsigned integer type (uint8_t) representing characters associated with various terminal control functions. 'NCCS' is a macro indicating the number of elements in the c_cc[] array. (this is 19 in /usr/include/asm-generic/termbits.h
  
  
• bool acSetLocale ( const char * localeName = NULL );

    Input  : (optional, null pointer by default)
              If specified, pointer to name of UTF-8 compliant locale filename.
              If null pointer (or empty string: "\0"), set locale from terminal
              environment.
  
    Returns: 'true'
              Currently, we do not verify that 'localeName' is a valid UTF-8
              compliant locale filename.
  

  Set the "locale" for the application.
  By default, the application locale is taken from terminal environment.

  Type: echo $LANG at the command prompt to get the terminal’s locale. If desired, an alternate locale may be specified.

  For a complete listing of locales supported by your system, at the command prompt, type: locale -a

  
  
• const char* acGetLocale ( void );

    Input  : none
  
    Returns: pointer to locale name
  

  Returns a pointer to the name of the current locale.

  
  
• bool acSetStreamWidth ( bool widechar );

    Input  : widechar : select 'true' (wide stream) or 'false' (narrow stream)
  
    Returns: current state of character-width flag
  

  Set input/output streams’ character width.
  This determines which input/output streams will be used:

  wide stream: wcin/wcout narrow stream: cin/cout

  IMPORTANT NOTE: This method will have no effect if called after the application has performed I/O.
  The first input or output performed by the application locks in the character-stream width used for the application.
  C++ offers a way to set stream width directly (std::freopen), but it’s better to get it right the first time.

  
  
• bool acBufferedInput ( bool buffered, EchoOpt echoType, bool block = true );

    Input  : buffered : if 'true',  enable input buffering by the terminal
                        if 'false', disable buffering and allow local control
                                    over the input stream
             echoType : member of enum EchoOpt:
                        referenced ONLY when 'buffered' == false
                        noEcho  : data from the stdin stream will not be echoed
                                  to the terminal window
                        termEcho: terminal echoes all stdin data to the window
                        softEchoA, softEchoC, softEchoD, softEchoE:
                                  terminal echo is disabled, but the acRead()
                                  methods will echo PRINTING characters to the
                                  terminal window according to the specific
                                  soft-echo sub-option.
             block    : (optional, 'true' by default)
                        enable or disable blocking-read of input stream
                        referenced ONLY when 'buffered' == false
                        if 'true',  enable blocking read of stdin
                        if 'false', disable blocking read of stdin
  
    Returns: current state of the 'buffered-input' flag (inpBuf).
  

  Disable buffering so each keystroke can be received as soon as the key is pressed, or restore terminal’s control over input buffering.

  Normally, user input to the terminal (stdin) is buffered. That is, typed characters are stored in the terminal’s private input buffer and are returned to the application only when the ENTER key is pressed.

  In some circumstances, however, when a “Press any key to continue...” functionality is desired. Local control of the input buffer is also necessary when capturing ANSI sequences transmitted from the terminal in order to prevent cluttering the window with data which is meaningless to the user.
  See acRead for additional info.

  IMPORTANT NOTE: When buffering is enabled (buffered!=false), then the 'echoType' and 'block' parameters are ignored.

  • When buffering is enabled, termEcho is always enabled.
  • When buffering is enabled, blocking read of input is always enabled. Consequently, if modifying the echo option (acSetEchoOption) and/or the input-blocking option (acBlockingInput), then input buffering must have been disabled.

  Notes:

  1. The ’ICANON’ flag actually controls whether the terminal references 'VTIME' and 'VMIN' and how those values are interpreted.
  2. Buffering has no direct dependence on whether or not the characters are echoed when they arrive, and again, the ’ICANON’ flag determines whether the terminal references the ’ECHO’ flag’.
  3. Traditionally (and logically) echo is disabled when buffering is disabled. However, we provide an option to keep echo active while buffering is disabled.
  4. Echo should be disabled if the system is queried for a response in the form of an escape sequence (for instance, asking for the current cursor position). If echo is active, then it is likely that the printing characters in the the escape sequence will inappropriately be echoed to the screen.

     To bake a cake and eat it too, see the soft-echo option.

  
  
• bool acSetEchoOption ( EchoOpt echoType );

    Input  : echoType: member of enum EchoOpt: 
                       noEcho   : data from the stdin stream will not be
                                  echoed to the terminal window
                       termEcho : terminal echoes all stdin data to the window
  
                       For the soft-echo options, terminal echo is disabled,
                       and echo of input characters to the display is
                       handled locally by the acRead() methods which will
                       echo all PRINTING characters to the display, and
                       will decode the "special keys" (cursor keys, etc.)
                       according to the specific soft-echo sub-option.
                       softEchoA: all special keys (default soft-echo option)
                       softEchoB: basic set of special keys
                       softEchoC: cursor-movement keys only
                       softEchoD: disable all special keys
                       softEchoE: edit keys only: Backspace, Delete, Insert,
                                  plus the Tab and Shift+Tab keys
  
    Returns: 'true'  if echo option modified
             'false' if input buffering currently enabled (or invalid type)
  

  Select the input character echo type. (enum EchoOpt).

  Echo of user keyboard input (writing the received keycode to the display can be handled in a number of ways as listed above. The terminal can be allowed to decide what key input is echoed to the display, or the application can take control of key input to provide a smoother user interface.

  The “soft-echo” options are available for customizing the user interface.
  Please see Decoding the Special Keys for more information on the soft-echo options.

  This option is available ONLY when input buffering has been disabled. Please see acBufferedInput method for additional information.

  
  
• EchoOpt acGetEchoOption ( void );

    Input  : none
  
    Returns: current echo option: member of enum EchoOpt
  

  Get the current input-echo setting which describes how data from the input stream is processed.
  See TermConfig Class for a discussion of input-stream configuration options.

  
  
• bool acBlockingInput ( bool block );

    Input  : block : if 'true',  enable blocking read of input stream
                     if 'false', disable blocking read of input stream
  
    Returns: current state of the inpBlk flag
             'true'  == blocking-read of stdin
             'false' == non-blocking read of stdin
    Returns: 
  

  Enable or disable blocking read from the input stream (stdin).
  This is a pass-through method for the TermSet function which sets/resets The blocking/non-blocking functionality.

  IMPORTANT NOTE: Non-blocking input requires that unbuffered input be enabled. If not already enabled, unbuffered input (with ’noEcho’) will be automatically enabled.

  
  
• bool acCaptureSignals ( EchoOpt eopt = softEchoA );

    Input  : eopt  : (optional, softEchoA by default)
                      specify one of the soft-echo options (enum EchoOpt)
  
    Returns: 'true'  if all settings successful
             'false' if one or more settings failed
  

  Disable input buffering and capture all system signals generated by keyboard input.

  This method is provided as a housekeeping convenience, performing a common sequence of terminal setup operations:

  1. If input buffering has not yet been disabled, it will be disabled using the specified soft-echo option, and with non-blocking read of the input stream.
  2. The output flow control signals will be disabled.
     The Ctrl+S (stop flow) and Ctrl+Q (resume flow) control codes become ordinary keycodes: wcsCTL_S and wcsCTL_Q, respectively.
  3. The Break signal will be captured and converted to an ordinary keycode:
        Break Signal  : SIGINT  - Ctrl+C becomes wcsCTL_C
  4. The Suspend signal will be captured and converted to an ordinary keycode:
        Suspend Signal: SIGTSTP - Ctrl+Z becomes wcsCTL_Z
  5. The Quit signal will be captured so that the application will be terminated in an orderly manner.
        Quit Signal : SIGQUIT - Ctrl+4 performs an orderly application shutdown
  Refer to the individual capture methods for details: acBufferedInput() acCaptureBreakSignal() acCaptureSuspendSignal() acCaptureQuitSignal()
  
  
• void acReleaseSignals ( void );

    Input  : none
  
    Returns: nothing
  

  Release all captured signals. Return control to the terminal software.

  Releases the following signals: 1) Break Signal : SIGINT - Ctrl+C 2) Suspend Signal: SIGTSTP - Ctrl+Z 3) Quit Signal : SIGQUIT - Ctrl+4
  
  
• bool acCaptureBreakSignal ( bool enable, CCH_Type handlerType, bool alert, void* handlerAddr = NULL );

    Input  : enable : if 'true',  enable application capture of the break key
                      if 'false', disable application capture of the break key
                                  terminal handles the break signal
             handlerType: (optional, cctDefault by default)
                          member of enum CCH_Type, specify the break-handler type.
             alert      : (optional, 'false' by default)
                          Referenced only when 'handlerType' == cchIgnore.
                          Optionally sound a beep when the break signal is
                          received and discarded.
                          if 'false', silently discard the break signal.
                          if 'true',  beep when discarding the break signal.
             handlerAddr: (optional, null pointer by default)
                          - by default, the internal AnsiCmd method,
                            BreakSignal_Handler() will provide an orderly response
                            to receipt of the break signal. See below for details.
                          - if the address of a handler method is specified, that
                            method will be activated by the break signal. That
                            method controls the response (if any) to the signal.
                            Note: The name of the target method is the address of
                                  that method.
                          This argument is referenced only if 'enable' is set.
  
    Returns: current state of capture flag
             'true'  break key will be captured by the application
             'false' break key will be handled by the terminal program
  

  Enable or disable application-level capture and processing of the BREAK key (CTRL+C).

  By default, the terminal software processes the break signal by immediately killing the application which is running in the terminal window. While this is certainly an efficient and reliable way to terminate an application, it is grossly messy and potentially dangerous. For instance, what if the application is editing a critical system file when it is terminated in mid-update? Chaos.

  In contrast, if the application itself captures the break signal, the application can shut down in an orderly manner, ask the user what to do, or simply ignore the break signal.

  ---

  
  When local capture of the break signal is active, by default, the signal will be handled by the default (non-member) method, BreakSignal_Handler().

  The handler type is specified by the ’ccType’ member variable which is initialized here.

  Valid Handler Types:

  • cchtIgnore: Ignore the Ctrl+C key (default, cctDefault)
    Application will continue as if the signal had not been received.
  • cchtExit : Exit the application in an orderly way:
    1. the cursor will be placed on the bottom row of the terminal window and the row will be cleared,
    2. the terminal bell will sound,
    3. a short message will be displayed,
    4. the AnsiCmd destructor will be called, and
    5. the application will be terminated with a minus-one (-1) exit code.
  • cchtUser : Ask the user if they really want to exit the application:
    1. the terminal bell will sound,
    2. Clear a small area in the upper-right-hand corner of the terminal window. (This is assumed to be the least cluttered, least used area of the window.)
    3. Display a message asking the user to answer:
          Exit? 'y'es or 'n'o: _
    4. Wait for the user’s response.
  • cchtCopy : Convert the break signal to an ordinary keycode (wcsCTL_C) which may then be used in the common copy-and-paste sequence: Ctrl+C --> Ctrl+V.
  • cchtTerm : Local handler is disabled, so the local handler is not called.
  
  
• bool acCaptureQuitSignal ( bool enable );

    Input  : enable : if 'true',  enable application capture of the quit key
                      if 'false', disable application capture of the quit key
                                  terminal handles the signal
  
    Returns: current state of capture flag
             'true'  quit key will be captured by the application
             'false' quit key will be handled by the terminal program
  

  Pressing the CTRL+4 key (or the CTRL+\ key) generates the system Quit signal. If the system receives the Quit signal, it will immediately terminate the application and generate a “core dump” file.

  Core dump files are created in /var/lib/systemd/coredump by default. The format of the file should be ELF (Executable and Linkable) format, but could be an older format. An explanation of core dump files is beyond the scope of this document, but see the 'gdb' (GNU Debugger) utility, which may be used to decode the contents of core-dump files.

  The Quit Signal is captured by default during configuration of the AnsiCmd class and its derived classes. Then when the Quit signal is received, (CTRL+4 key) the application is shut down in an orderly manner, and a core dump is not generated.
  The local Quit signal handler deletes the temporary files, releases dynamic memory allocations and performs general housekeeping chores. Before exiting the application, the bottom two rows of the terminal window are cleared and a message is written indicating that the application has been terminated.
  After all, we’re not just wild animals pooping in the forest. (well, most of us anyway :-)

  See Q option for specifying this option as a command line parameter.

  Technical Note:
  This signal is sometimes referred to as the Kill signal, but note that the Quit signal is technically different from the Kill signal in that the Kill signal cannot be captured or modified. It is an absolute command, and in fact, failure to respond to the Kill signal would be considered as a major system bug.

  
  
• bool acCaptureSuspendSignal ( bool enable );

    Input  : enable : if 'true',  enable application capture of the suspend key
                      if 'false', disable application capture of the suspend key
                                  terminal handles the suspend signal
  
    Returns: current state of capture flag
             'true'  suspend key will be captured by the application
             'false' suspend key will be handled by the terminal program
  

  Enable or disable application-level capture and processing of the SUSPEND key CTRL+Z. Signal name: SIGTSTP.

  If this signal is seen by the terminal program, it will suspend the active process. That is, it will put the process into the background and disable direct access to it. A different process may then occupy the foreground, interacting with the input and output streams.
  Use the ’fg’ utility to restore the hibernating process.

  Because Ctrl+Z is often used as a command (undo) within an application, this signal is captured by default and converted to an ordinary keycode: wcsCTL_Z.

  
  
• bool acRestoreTermInfo ( bool restoreAll );

    Input  : restoreAll : (optional, 'false' by default)
                          if 'false' this method restores input buffering,
                             input echo, and blocking-read settings only.
                             Break-handler, cursor style, and other terminal
                             configuration options are not affected.
                          if 'true',  all terminal setting under control of
                             the TermSet object will be returned to the states
                             when the object was instantiated. (see list below)
  
    Returns: 'true' if settings restored
             'false' if original settings not previously saved
                     or if system error
  

  Restore terminal stream settings to original values captured during the first access to the terminal settings. This probably occurred during creation of the TermSet-class object which is done as part of the AnsiCmd-class constructor sequence. The TermSet object manages the the current terminal settings. The settings restored depend on the state of the 'restoreAll' flag, and include:

  1. Buffering of input stream.
  2. Echo option (see enum EchoOpt).
  3. Blocking vs. non-blocking read of input stream.
  4. Disable local break-key handler, if active.
  5. Set cursor style to terminal default.
  
  
• void breaksignalReceived ( int sigNum );

    Input  : sigNum: signal number to be handled
                     Currently, only the SIGINT (interrupt) is handled.
    Returns: nothing
  

  When the break signal has been captured, (see Capturing the Break Signal), this method is called by a non-member method specified as the dedicated CTRL+C signal handler. The handler type is specified by the ’ccType’ member variable which is set to one of the following:

  cchtIgnore: Ignore the Ctrl+C key (default, cctDefault) cchtExit : Exit the application in an orderly way. cchtUser : Ask the user if they really want to exit the application. cchtCopy : Push the literal value for Ctrl+C (0x03) back into the input stream. cchtTerm : Local handler is disabled, so this method is not called.
  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

  This is technically a public method; however, it is called ONLY by the non-member method which handles receipt of the break-signal (CTRL+C).

  
  
• void suspendsignalReceived ( int sigNum );

    Input  : sigNum: signal number to be handled
                     Currently, only the SIGSTP (suspend) is handled.
    Returns: nothing
  

  When the suspend signal has been captured, (see acCaptureSuspendSignal), this method is called by a non-member method specified as the dedicated CTRL+Z signal handler.

  This method captures the signal and converts it to an ordinary keycode: wcsCTL_Z.

  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

  This is technically a public method; however, it is called ONLY by the non-member method which handles receipt of the suspend-signal (CTRL+Z).

  
  
• void quitsignalReceived ( int sigNum );

    Input  : sigNum: signal number to be handled
                     Currently, only the SIGQUIT (quit) is handled.
    Returns: nothing
  

  When the quit signal has been captured, (see acCaptureQuitSignal), this method is called by a non-member method specified as the dedicated CTRL+4 signal handler. The handler will then perform an orderly shutdown of the application, returning all resources to the system.

  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

  This is technically a public method; however, it is called ONLY by the non-member method which handles receipt of the quit-signal (CTRL+4 or CTRL+\).

Color Attributes

• bool acSetFg ( aeSeq fg );

    Input  : fg   : foreground color attribute (member of aeSeq)
  
    Returns: 'true'  if valid color attributes specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set text foreground color attribute (3-bit and 4-bit color).

  This includes both the standard 3-bit and 4-bit attributes, as well as the non-standard IBM Corp. AIX extensions.

  Note: The AIX color attributes were defined by IBM to provide interoperability of the terminal interface between their proprietary systems (Aixterm) and the Linux/UNIX world. Although these attributes are not part of the ANSI standard, they are widely supported and provide basic foreground and background colors using a slightly different (brighter) combination of Red/Green/Blue register values. The differences are demonstrated in the color-attribute tests included with the AnsiCmd library. See Development and Testing for more information.
  
  
• bool acSetBg ( aeSeq bg, bool synth );

    Input  : bg   : background color attribute (member of aeSeq)
             synth: (optional, 'true' by default)
                    if 'true',  use synthesized background color attributes
                    if 'false', use standard ANSI background color attributes
  
    Returns: 'true'  if valid color attributes specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set text background color attribute (3-bit and 4-bit color).

  This includes both the standard 3-bit and 4-bit attributes, as well as the non-standard IBM Corp. AIX extensions.
  (See note on AIX attributes, above.)

  Note on synthesis of intense background color attributes

  The default color attributes for intense (bold) backgrounds are inadequate because the
  'intense' ('bold') bit affects only the foreground color.

  “Synthesized” bold backgrounds are used by default, which bypasses the ’bold’ flag problem by
  using a member from the color lookup table which is outside the basic sixteen color (4-bit) group.

  
  
• bool acSetFgBg ( aeSeq fg, aeSeq bg );

    Input  : fg   : foreground color attribute (member of aeSeq)
             bg   : background color attribute (member of aeSeq)
  
    Returns: 'true'  if valid color attributes specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set text foreground AND background colors (3-bit and 4-bit color).

  This includes both the standard 3-bit and 4-bit attributes, as well as the non-standard IBM Corp. AIX extensions.
  (See note on AIX attributes, above.)

  
  

  Programmer’s Note: The foreground is set AFTER the background so that if the ‘bold’ flag is used in the foreground escape sequence, it will not be masked by a subsequent non-bold background. Note also that bold background color escape sequences include the ‘bold’ flag, but unfortunately, because of the way the terminal interprets this flag, it affects only the foreground attribute. Exception: "synthesized" bold backgrounds are used by default, which bypasses the ’bold’ flag problem by using a different member from the color lookup table which is outside the basic sixteen (4-bit) color group.

  
  
• bool acSetFgBg ( acAttr fgbg );

    Input  : 
       fgbg : foreground/background/modifiers 
              encoded as an acAttr bitfield
  
    Returns: 'true'
  

  Set text foreground/background colors using a value encoded as an acAttr bitfield value.
  Although the acAttr group of color attribute bitfields is defined for use within the AnsiCmd API; this method allows for color attributes to be specified using these encoded bitfield attributes regardless of whether the API code is compiled into the library.

  The specified value may be created directly as a logical OR of multiple members of the “acAttr” enumerated type.
  Example: acAttr( acaFG_GREEN | acaBG_BLACK | acaUNDERLINE)

  The bitfield value may also be built by a call to one of the acaExpand-class methods. See acaExpand class, for details.

  Note that this is a simplified version of the API method: ’acSetAttributes’, which is preferred when the API methods are available. This method should be used only if the library has been compiled without the API method group.

  
  
  
• bool acSet8bitFg ( uint8_t fg );

    Input  : fg : index into the lookup table for 8-bit color attributes
  
    Returns: 'true'  if valid color attribute specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set foreground color from 8-bit-color lookup table.
  Select an index number between min8BIT through max8BIT (16-231).

  
  
• bool acSet8bitBg ( uint8_t bg );

    Input  : bg : index into the lookup table for 8-bit color attributes
  
    Returns: 'true'  if valid color attribute specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set background color from 8-bit-color lookup table.
  Select an index number between min8BIT through max8BIT (16-231).

  
  
• bool acSetRgbFg ( uint8_t rReg, uint8_t gReg, uint8_t bReg );

    Input  : rReg : red value
             gReg : green value
             bReg : blue value
  
    Returns: 'true'  if valid R/G/B registers specified and set
             'false' if specified parameters are out-of-range
                     (attribute will not be modified)
  

  Set foreground color using R/G/B register numbers.

  Each of the basic Red, Green and Blue color attributes may be displayed in any of 216 shades, and the color values may be in any combination.

  Each of the values may be specified as any register number between minRGB (16) and maxRGB (231).

  Smaller values indicate less saturation (darker colors), and larger values indicate greater saturation (lighter, more intense colors). If desired, the special value zero (0) may be used to indicate minimum saturation.

  
  
• bool acSetRgbBg ( uint8_t rReg, uint8_t gReg, uint8_t bReg );

    Input  : rReg : red value
             gReg : green value
             bReg : blue value
  
    Returns: 'true'  if valid R/G/B registers specified and set
             'false' if specified parameters are out-of-range
                     (attribute will not be modified)
  

  Set background color using R/G/B register numbers.

  Each of the basic Red, Green and Blue color attributes may be displayed in any of 216 shades, and the color values may be in any combination.

  Each of the values may be specified as any register number between minRGB (16) and maxRGB (231).

  Smaller values indicate less saturation (darker colors), and larger values indicate greater saturation (lighter, more intense colors).

  If desired, the special value zero (0) may be used to indicate minimum saturation.

  
  
• bool acSetWebFg ( WebSafeRGB hue, uint8_t shade );

    Input  : hue   : member of enum WebSafeRGB
                     wsrgbBLACK   : black color index
                     wsrgbRED     : base color index (red color block)
                     wsrgbGREEN   : base color index (green color block)
                     wsrgbBLUE    : base color index (blue color block)
                     wsrgbBROWN   : base color index (brown color block)
                     wsrgbMAGENTA : base color index (magenta color block)
                     wsrgbCYAN    : base color index (cyan color block)
                     wsrgbGREY    : base color index (grey color block)
                     Remaining members of WebSafeRGB are reserved for other
                     purposes.
             shade : intensity of the color specified by 'hue'
                     wsrgbSHADE_MIN <= shade <= wsrgbSHADE_MAX
                     where:
                     wsrgbSHADE_MIN == minimum saturation (subdued)
                     wsrgbSHADE_MAX == maximum saturation (brightest)
  
    Returns: 'true'  if valid hue and shade values specified
             'false' if specified parameters are out-of-range
                     (attribute not be modified)
  

  Set foreground color using "web-safe" R/G/B register value combinations.

  What's a Web Safe? Spiderman's closet?

  In the early days of the internet and using early versions of color display hardware, it was necessary to define a set of color attributes that could be reliably duplicated on any standard hardware with any of the early graphics-based web browsers. (Yes, we used to surf the web using text-only browsers; but you must remember that like Mister Spock, we were trying to build a mnemonic memory circuit using stone knives and bear skins.)

  The solution was to create the so-called “web-safe” set of color attributes. This was done by creating a 6 x 6 x 6 matrix of Red/Green/Blue register values yielding 216 discrete colors. Conceptually, each color can take one of six hex values: 00 33 66 99 CC FF. For each color, the actual index into the 256 entry color lookup table is selected according to this model. See enum WebSafeRGB for the way this mapping is done.

  In the modern world of “true-color” computing, the idea of web-safe colors is a bit outdated, but it is still a valid concept in the simpler world of console applications, where we are limited to the palette specified by the terminal configuration.

  Please see Development and Testing for a fuller discussion of the color attributes available to console applications.

  
  
• bool acSetWebBg ( WebSafeRGB hue, uint8_t shade );

    Input  : hue   : member of enum WebSafeRGB
                     wsrgbBLACK   : black color index
                     wsrgbRED     : base color index (red color block)
                     wsrgbGREEN   : base color index (green color block)
                     wsrgbBLUE    : base color index (blue color block)
                     wsrgbBROWN   : base color index (brown color block)
                     wsrgbMAGENTA : base color index (magenta color block)
                     wsrgbCYAN    : base color index (cyan color block)
                     wsrgbGREY    : base color index (grey color block)
                     Remaining members of WebSafeRGB are reserved for other
                     purposes.
             shade : intensity of the color specified by 'hue'
                     wsrgbSHADE_MIN <= shade <= wsrgbSHADE_MAX
                     where:
                     wsrgbSHADE_MIN == minimum saturation (subdued)
                     wsrgbSHADE_MAX == maximum saturation (brightest)
  
    Returns: 'true'  if valid hue and shade values specified
             'false' if specified parameters are out-of-range
                     (attribute not be modified)
  

  Set background color using "web-safe" R/G/B register value combinations.

  See acSetWebFg, above for a description of “web-safe” colors.

  
  
• bool acSetGreyscaleFg ( uint8_t shade );

    Input  : shade : brightness of grey color: minGSCALE <= shade <= maxGSCALE
                     example: acSetGreyscaleFg ( minGSCALE + 2 ) ;
  
    Returns: 'true'  if valid greyscale attribute specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set Greyscale foreground color attribute. (background unchanged)

  For systems that have at least 256 colors, 24 shades of greyscale intensity are available.
  These are accessed through indices 232-255 of the terminal’s 256-color lookup table.

  
  
• bool acSetGreyscaleBg ( uint8_t shade );

    Input  : shade : brightness of grey color: minGSCALE <= shade <= maxGSCALE
                     example: acSetGreyscaleBg ( minGSCALE + 2 ) ;
  
    Returns: 'true'  if valid greyscale attribute specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Set Greyscale background color attribute. (foreground unchanged)

  For systems that have at least 256 colors, 24 shades of greyscale intensity are available.
  These are accessed through indices 232-255 of the terminal’s 256-color lookup table.

  
  
• bool acSetAixFg ( aeSeq fg );

    Input  : fg   : AIX foreground color attribute (member of aeSeq)
  
    Returns: 'true'  if valid color attributes specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  NOTE: This method is obsolete. See acSetFg.

  
  
• bool acSetAixBg ( aeSeq bg );

    Input  : bg   : AIX background color attribute (member of aeSeq)
  
    Returns: 'true'  if valid color attributes specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  NOTE: This method is obsolete. See acSetBg.

  
  
• bool acReset ( void );

    Input  : none
  
    Returns: 'true'
  

  Return all ANSI attributes to terminal defaults. Set all tracking members to their default values. Flush the input and output buffers.

  This method does not modify the terminal configuration. It resets only the ANSI control environment as defined by the set of escape sequences.

  Programmer’s Note: It is not possible to programatically check whether each attribute was actually reset; however, the ANSI reset escape sequence should be trustworthy.

Text Modifiers

• bool acSetMod ( aeSeq mod );

    Input  : mod  : text modification attribute (member of aeSeq)
  
    Returns: 'true'  if valid modifier attributes specified and set
             'false' if invalid parameter(s) specified
                   (attributes will not be modified)
  

  Set or reset the specified text modifier.

  Any text written after setting a modifier using this command will be displayed using the specified modifier (bold, italic, etc.). Any text written after resetting a modifier will be displayed without the specified modifier.

  See acResetMods method below for a list of valid text modifiers.

  
  
• void acResetMods ( bool full );

    Input  : full: (optional, 'false' by default)
                   if 'true',  write a reset command instead of writing 
                               the ANSI modifier-off sequences.
                               This option is available in case the host 
                               terminal does not support some or all of the 
                               modifier-off sequences.
                               NOTE: this ALSO resets the color attributes.
                   if 'false', write only the individual modifier commands,
                               do not write the reset command
  
    Returns: nothing
  

  Reset all text modifiers, leaving the base foreground and background color attributes unchanged.

  The text modifier attributes are:

    aesBOLD,          // bold (increase intensity)
    aesFAINT,         // faint/dim (decrease intensity)
    aesITALIC,        // italic (or inverse)
    aesUNDERLINE,     // underline
    aesBLINK_SLOW,    // slow blink
    aesBLINK_FAST,    // fast blink
    aesREVERSE,       // reverse foreground and background colors
    aesCONCEAL,       // hide text
    aesXOUT,          // crossed out text (marked for deletion)
    aesFRACTUR,       // a variety of German calligraphy
    aesDBL_UNDERLINE, // double-underline (or bold off)
    aesFRAMED,        // "frame" the text
    aesENCIRCLE,      // "encircle" the text
    aesOVERLINE,      // overlined text
  

  Calling this method is equivalent to calling acSetMod() nine times, once for each of the modifer resets.

    aesBOLD_OFF,      // normal intensity (neither bold nor faint)
    aesITALIC_OFF,    // italic off (and Fractur off)
    aesUNDERLINE_OFF, // not underlined
    aesBLINK_OFF,     // not blinking
    aesREVERSE_OFF,   // not reversed
    aesCONCEAL_OFF,   // conceal off
    aesXOUT_OFF,      // not crossed out
    aesFRM_ENC_OFF,   // not framed, not encircled
    aesOVERLINE_OFF,  // overline off
  

  
  
• bool acFullReset ( bool enable );

    Input  : enable : 'true' to enable full reset for attribute modifications
                      'false' to disable full reset and rely upon the
                              setting/resetting the flag which controls the
                              specific attribute being modified
  
    Returns: current state of the full-reset flag
  

  Enable or disable reset of all ANSI display attributes before modifying a text attribute.

  The AnsiCmd class is constructed so that when modifying an ANSI parameter other parameters will be affected as little as possible. Specifically, when enabling or disabling an attribute such as Bold, Underline, etc., the intent is to avoid disturbing the existing forground and background color settings.

  However, some console software or their underlying system software may not support all of the single-attribute commands such as aesBOLD_OFF, aesITALIC_OFF, aesUNDERLINE_OFF, aesBLINK_OFF aesREVERSE_OFF, aesCONCEAL_OFF, aesXOUT_OFF, aesFRM_ENC_OFF, aesOVERLINE_OFF, aesIDEO_OFF.

  If these reset commands are not supported on a given platform, then set the ’fullReset’ flag, and the AnsiCmd class will use the full reset command, aesRESET when changing terminal settings. The aesRESET command is supported by nearly all terminal emulators.

  See Invoking - Terminal Setup (-A option) which enables the full-reset flag as part of the startup sequence.

Cursor Positioning

Important Note On Cursor Positioning

Cursor positions within a terminal window are always defined as offsets from some reference position. In general, offsets are relative to the upper-left corner of the terminal window, also known as the “origin”.
The terminal window origin is defined as position 1:1 (not the logically correct 0:0).

Unfortunately, the developers of terminal software and the authors of the ANSI commands and other utilities are not always on the same page regarding whether cursor offsets should be 0-based or 1-based. Be aware that a zero(0) value may be silently converted to a one(1) value, OR it may cause an operation to fail, or worse, produce unexpected results.

The AnsiCmd cursor-positioning methods will accept an “absolute” value of zero and silently convert it to a one(1). This prevents artifacts such as unexpected scrolling or pushing text out of the window. However, be aware that not all utilities are so user friendly. Be aware!

• bool AnsiCmd::acSetCursor ( aeSeq curcmd, short arga, short argb ) const;

    Input  : curcmd: one of the members of the cursor-positioning group which
                     are included in enum aeSeq.
                     Example: acSetCursor ( aesCUR_HOME ) ;
             arga  : (optional, 1 by default)
                     for options which require arguments, 'arga' specifies the
                     first argument.
                     Example: acSetCursor ( aesCUR_ABSCOL, 30 ) ;
             argb  : (optional, 1 by default)
                     for options which require arguments, 'argb' specifies the
                     second argument.
                     Example: acSetCursor ( aesCUR_ABSPOS, 12, 60 ) ;
  
    Returns: 'true'  if valid cursor command (and valid arguments, if required)
             'false' if invalid parameter(s) specified
                     (position will not be modified)
  

  Set cursor position within terminal window.

  Some ANSI cursor commands perform cursor movements relative to the current position, while other commands set the cursor at an absolute position within the terminal window.

  See cursor offsets above regarding 1-based vs. 0-based cursor positioning.

  This method invokes the specified ANSI escape sequence directly; however, there are two variations on this method, described below, which may also be used to set the cursor position. Please choose the one that best suits your needs.

  NOTE: One member of the cursor-positioning group: aesCUR_REPORT, is not handled by this method.
  Instead please see acGetCursor. If aesCUR_REPORT is received, it will be ignored and ’false’ will be
  returned to indicate that the request was not handled.

  Also:
  Digital Equipment Corporation (DEC) and the SCO Group (UnixWare) defined some of the
  cursor-management commands differently. On our test systems, the SCO commands work correctly,
  while the DEC commands do not. Your mileage may vary.

  
  
• bool AnsiCmd::acSetCursor ( short row, short col ) const;
• bool AnsiCmd::acSetCursor ( const WinPos& wp ) const;

    Input  : One of the following:
                row : target row 
                col : target column
             or:
                wp  : (by reference) target row and column
  
    Returns: 'true'  if specified row/column are within the terminal window
             'false' if invalid position (cursor position not modified)
  

  Set absolute cursor position within terminal window.

  These methods reformat the parameters and call the low-level acSetCursor method described above.

  
  
• WinPos acGetCursor ( void ) const;

    Input  : none
  
    Returns: an initialized WinPos object
             (If system error or parsing error, window origin is returned.)
  

  Get the current cursor position within terminal window.

  Technical Notes

  This method requires that input buffering be disabled and that input echo be set to ’noEcho’. The reason for this is that when buffering is active, the response from the terminal will not become available to the application until the Enter key is detected in the input stream.
  In addition, echo of input characters to the terminal window must also be disabled because when the system writes the response to the position query, it is written to stdin, which if echo were enabled would likely trash the currently-displayed text, or at minimum would move the cursor, causing a big surprise at the application level. While setting and restoring the buffering/echo options is an expensive operation in terms of CPU cycles, it is necessary for smooth operation at the application level.

  -- Write the ANSI sequence requesting the current cursor position.
  -- Read the response (binary data) from stdin.
  -- Decode the response which is of the form: 1B 5B (row) 3B (col) 52
       1B       escape character
       5B       left square bracket
       row      one or more ASCII numeric chars indicating row number
       3B       ';' (ASCII semicolon)
       col      one or more ASCII nummeric chars indicating column number
       52       ASCII 'R'
  

  
  
• bool acSetCursorStyle ( CurStyle style, aeSeq color );

    Input  : style : member of enum CurStyle
             color : (optional, default from terminal profile)
                     member of aeSeq, foreground attribute group: aesFG_xxx
                     color attribute for cursor [CURRENTLY IGNORED]
  
    Returns: 'true' if valid argument(s), else 'false'
  

  Set cursor type i.e. the shape of the cursor.

  Three basic cursor shapes are available in either a steady state or blinking:
   Block:'█'  Underline:'▁'  Vertical Bar:'▎'

  In addition, the cursor can be made invisible. The style is specified as a member of enum CurStyle which is the parameter for the escape sequence to be transmitted. (Note that cursor style settings are not part of the ANSI standard.)

    csBblock = 0,  // Full-character cell, blinking block
    csDflt   = 1,  // Cursor type defined by terminal configuration
    csSblock = 2,  // Full-character cell, steady (non-blinking) block
    csBuline = 3,  // Blinking underline
    csSuline = 4,  // Steady underline
    csBvbar  = 5,  // Blinking vertical bar
    csSvbar  = 6,  // Steady vertical bar
    csHide   = 7,  // Hide cursor (make it invisible)
    csShow   = 8,  // Show cursor (make it visible)
  

  Note on cursor blink timeout: Although the cursor shape and blinking/steady status can be specified using this method, the terminal settings specify a timeout on the blinking status. For instance, the Gnometerm terminal emulator specifies a default timeout on the cursor’s blink status of ten(10) seconds. This timeout can be adjusted using the “gsettings” utility. Example: Get current settings:    gsettings get org.gnome.desktop.interface cursor-blink-timeout Report the range of valid values:    gsettings range org.gnome.desktop.interface cursor-blink-timeout Set a new timeout of 25 seconds:    gsettings set org.gnome.desktop.interface cursor-blink-timeout 25

  Note: The cursor color attribute is automatically set by the terminal to the same color as the text. Theoretically, the "gsettings" utility and other utilities can also be used to set the cursor color, but early testing shows that such commands are ignored. Testing continues.

Input Methods

• short acRead ( gString& gsIn, short limit ) const;

    Input  : gsIn  : (by reference) receives captured text (null terminated)
             limit : (optional, size of gString object by default)
                     If specified, 'limit' indicates the maximum number of
                     characters (wide-stream input) OR the maximum number of
                     bytes (narrow-stream input) that will be extracted from
                     the stdin buffer.
                     Important Note: This argument is referenced only when
                     unbuffered input is active. This argument is ignored
                     when input-stream buffering is enabled.
  
    Returns: number of characters captured (NOT the number of bytes)
  

  Capture user input as a sequence of characters terminated by the Enter key, OR when input buffering is disabled and the number of characters specified by the 'limit' parameter has been reached.

  Internally, this method loops a call to the single-character acRead (see below). The called method contains most of the intelligence of the operation.

  Note on capture of the Enter key

  • If the Enter key is the first and only keycode captured, the Enter keycode is returned and the character count returned will be one(1).
  • If the input is terminated by the Enter key, the characters captured before the Enter key are returned. The Enter keycode will not be returned and is not included in the character total.

  Please see Soft Echo Options for a discussion of when and how key input is echoed to the display.

  
  
• wchar_t  acRead ( void ) const;

    Input  : none
  
    Returns: keycode from user
  

  Capture a single keystroke from the user.

  The functionality of this method is dependent upon three factors:
   1) Whether input buffering is enabled,
      (see acBufferedInput)
   2) The active input echo option,
      (see Soft Echo Options)
   3) Whether input is configured for blocking or non-blocking read.
      (see acBlockingInput)
  Please study these options carefully and configure the input stream according to the needs of your application. A good place to start would be with 1) unbuffered input, 2) softEchoA, and 3) blocking read.

  
  
• wchar_t acPause ( bool nl = false ) const;

    Input  : nl : (optional, default: false)
                  if 'true',  after user keypress, output a newline character
                  if 'false', no output will be written to display
  
    Returns: keycode from user
  

  Wait for user to press a key. This is an unbuffered read, with no echo of the keycode to the display. Typically, this method would be used after the application displays a ’press any key’ or similar message.

  The optional 'nl' parameter may be used to write a newline character (NEWLINE (0x000A) to the display after the user presses any key. This will move the cursor to the leftmost column of the next row. This option should be used only when the application is writing directly to the terminal window, and not when formatted (ACWin-class) data are being displayed.

  Technical Note: After the keycode is received, the input stream is flushed, that is, any data remaining in the input buffer is read and discarded. This is done to protect against stale data being left in the buffer in case the key pressed by the user generates an escape sequence or another multi-byte sequence. If the initial keycode received is the Escape keycode (0x001B), the keycode for the space key wcsSPACE (0x0020) will be returned instead.

  
  
• void acWait ( uint16_t seconds ) const;

    Input  :
       seconds : specifies the sleep interval in seconds (1 minute max)
                 0 <= seconds <= 60
  
    Returns: nothing
  

  Pause for a specified amount of time OR until user presses a key.
  This can be thought of as a combination of the acPause and nsleep methods.

  The specified delay is broken into segments and after each delay segment, the input stream is pinged to determine whether user has pressed a key.
  The pause continues until either the full pause interval is complete, or until user presses any key, whichever comes first.

  Any keycode received is discarded, and before return, the input stream is flushed to avoid abandoning any stale data in the input stream.

  
  
• void acFlushIn ( void ) const;

    Input  : none
  
    Returns: nothing
  

  Flush stdin, (the active input stream, wcin or cin).
  Any data still in the input stream will be discarded.

  Note On Performance

  Flushing the input buffer relies on an unbuffered input stream to reliably extract the stale data from the stream. If input buffering is enabled when this method is called, this method disables buffering before the flush and re-enables buffering after the flush.
  While this is effective, it does produce a small performance hit. For this reason, it is recommended that unless there is a clear reason to do otherwise, the application should disable input buffering during startup and then re-enable buffering just before exit.
  Please see acBufferedInput for more information.

  See also acFlushStreams, below.

Output Methods

• WinPos  acWrite ( WinPos wp, const gString& gsTxt, bool flush = true ) const;
• WinPos  acWrite ( short row, short col, const gString& gsTxt, bool flush = true ) const;
• WinPos  acWrite ( WinPos wp, const wchar_t* wTxt, bool flush = true ) const;
• WinPos  acWrite ( short row, short col, const wchar_t* wTxt, bool flush = true ) const;
• WinPos  acWrite ( WinPos wp, const char* cTxt, bool flush = true ) const;
• WinPos  acWrite ( WinPos wp, wchar_t wchar, bool flush = true ) const;
• WinPos  acWrite ( short row, short col, wchar_t wchar, bool flush = true ) const;
• WinPos  acWrite ( WinPos wp, char cbyte, bool flush, bool newln ) const;
• WinPos  acWrite ( short row, short col, char cbyte, bool flush = true ) const;

    Input  : starting cursor position in one of the following formats:
                wp    : a WinPos object (by reference)
                      OR
                row   : target row
                col   : target column
  
             text data to be written in one of the following formats:
                gsTxt : (by reference) a gString object
                      OR
                wTxt  : a wchar_t string (32-bit characters)
                      OR
                cTxt  : a char (byte) string
                      OR
                wchar : a single wchar_t (wide) character
                      OR
                cbyte : a single byte
  
             flush : (optional, default: 'true')
                     if 'true,   flush the output buffer before return
                     if 'false', do not flush the output buffer
  
    Returns: current cursor position (WinPos object)
  

  Write text data to stdout beginning at the specified cursor position. The final cursor position is at the end of the output. This is the return value.

  This method is not reliable for writing ANSI escape sequences and ASCII control codes. For these special cases, use the 'ttyWrite' method below.

  The primary difference between this method and traditional TTY-style output is that newline ('\n') characters are handled as a special case. When a newline character is encountered in the output stream, it causes the cursor to be placed on the next row at the same column as the first column of the previous row. This automatic formatting allows the application to write formatted paragraph data without the painful task of having to count columns. (“You’ll thank me later.” — Adrian Monk)

  This method is actually a group of overloaded methods which provide flexibility in the way parameters are passed.

  Cursor position may be specified either as a WinPos object or as seperate row and column values.

  The source text may be formatted as:

  1. a gString object,
  2. a wchar_t (UTF-32) character array,
  3. a char (UTF-8) character array, or
  4. a single character

  By default, the output buffer is flushed after all data have been written. This is equivalent to the C++ sequence:
     wcout << "text_data" ;
   wcout.flush() ;
  However, flushing the output buffer is a slow operation (relatively speaking), so if multiple writes are performed in sequence, it is more efficient to flush the stream only once, after the last write of the sequence. For example, the following sequence writes three text strings, each in a different color, with the 'flush' flag set (default value) for the last write.
     WinPos wp( 4, 30 ) ;
   acSetFg ( aesFG_RED ) ;
   wp = acWrite ( wp, "Red textdata.\n", false ) ;
   acSetFg ( aesFG_BLUE ) ;
   wp = acWrite ( wp, "Blue text data.\n", false ) ;
   acSetFg ( aesFG_GREEN ) ;
   wp = acWrite ( wp, "Green text data.\n" ) ;
  

  Note that this method is aware of the terminal window dimensions.

  1. Text rows which would overrun the right edge of the terminal window are truncated,
     that is, automatic line wrap does not occur.
  2. Text data that would overrun the bottom edge of the terminal window will be ignored.
     Scrolling of the window contents WILL NOT occur.

  If automatic scrolling or automatic line wrap are desired, then call the ttyWrite method instead.

  Note that the width of the output stream (wide or narrow stream) is established during the application startup sequence; therefore, regardless of the width of the source data, it will be transmitted using the established stream width.
  Please see acSetStreamWidth, or the W option command-line option for more information on stream configuration.

  
  
• void  ttyWrite ( const gString& gsTxt, bool flush = true, bool nl = false ) const;
• void  ttyWrite ( const wchar_t* wTxt, bool flush = true, bool nl = false ) const;
• void  ttyWrite ( const char* cTxt, bool flush = true, bool nl = false ) const;
• void  ttyWrite ( const uint_8* uTxt, bool flush = true, bool nl = false ) const;
• void  ttyWrite ( wchar_t wchar, bool flush = true, bool nl = false ) const;
• void  ttyWrite ( char cbyte, bool flush = true, bool nl = false ) const;

    Input  : text data to be written in one of the following formats:
                gsTxt : (by reference) a gString object
                      OR
                wTxt  : a wchar_t string (32-bit characters)
                      OR
                cTxt  : a char (byte) string
                      OR
                uTxt  : a UTF-8 (byte) string
                      OR
                wchar : a single UTF-32 character
                      OR
                cbyte : a single byte (generally: an ASCII control code)
             flush : (optional, 'true' by default)
                     if 'true,   flush the output buffer before return
                     if 'false', do not flush the output buffer
             nl    : (optional, default: 'false')
                     append a newline character to the output
  
    Returns: nothing
  

  Write text data (or ANSI sequence) to stdout beginning at the current cursor position. This emulates the action of a teletype machine (TTY).
  (If you don’t know what a teletype machine is, your grandparents will explain it to you.)

  Any newline characters encountered will cause the cursor to be positioned on the first (leftmost) column of the line below, and if on the last line in the window, all data will be scrolled upward.
  Text will automatically wrap at the right edge of the window.

  This method is actually a group of overloaded methods which provide flexibility in the way parameters are passed. The source text may be formatted as

  1. a gString object,
  2. a wchar_t (UTF-32) character array,
  3. a char (UTF-8) character array, or
  4. a single character

  By default, the output buffer is flushed after all data have been written. This is equivalent to the C++ sequence:
     wcout << "text_data" ;
   wcout.flush() ;
  However, flushing the output buffer is a slow operation (relatively speaking), so if multiple writes are performed in sequence, it is more efficient to flush the stream only once, after the last write of the sequence. For example, the following sequence writes three text strings, each in a different color, with the 'flush' flag set (default value) for the last write.
     acSetCursor ( 4, 1 ) ;
   acSetFg ( aesFG_RED ) ;
   ttyWrite ( "Red textdata.\n", false ) ;
   acSetFg ( aesFG_BLUE ) ;
   ttyWrite ( "Blue text data.\n", false ) ;
   acSetFg ( aesFG_GREEN ) ;
   ttyWrite ( "Green text data.\n" ) ;
  

  Note that the width of the output stream (wide or narrow stream) is established during the application startup sequence; therefore, regardless of the width of the source data, it will be transmitted using the established stream width.
  Please see acSetStreamWidth, or the W option command-line option for more information on stream configuration.

  
  
• void acFlushOut ( void ) const;

    Input  : none
  
    Returns: nothing
  

  Flush stdout, (the active output stream, wcout or cout).
  Any data still in the output stream will be written to the terminal window.

  Note that the output methods acWrite and ttyWrite by default, flush the output stream at the end of each write. The acFlushOut method may be used to explicitly flush the data from the stream.

  See also acFlushStreams, below.

  
  
• void acFlushStreams ( void ) const;

    Input  : none
  
    Returns: nothing
  

  Flush (write) any data in the stdout stream and discard an stale data in the stdin stream.

  This method combines calls to acFlushIn and acFlushOut as described above.

  Technical Note: Although every effort has been made to clear the I/O buffers as needed, transmission and receipt of ANSI escape sequences can be interrupted or broken, causing display artifacts or other problems. Explicitly flushing the buffers at critical moments can help to reduce such accidents.

Text Erase

• bool acEraseArea ( aeSeq area, short rowOff, short colOff );

    Input  : cur   : one of the members of the text-erasure group within
                     enum aeSeq.
                     example: acEraseArea ( aesERASE_WIN ) ;
             rowOff: (optional, ZERO by default) If a non-zero value is
                     specified, the cursor will be shifted upward (negative
                     values) or downward (positive values) from the current
                     cursor position before the erasure occurs.
             colOff: (optional, ZERO by default) If a non-zero value is
                     specified, the cursor will be shifted leftward (negative
                     values) or rightward (positive values) from the current
                     cursor position before the erasure occurs.
  
    Returns: 'true' if successful
             'false' if invalid parameter(s) specified
  

  Erase the specified area of the terminal window.
  The area to be erased is specified by one of the ANSI erasure commands.
    aesERASE_BOW,   // erase from cursor to bottom of window
    aesERASE_TOW,   // erase from cursor to top of window
    aesERASE_WIN,   // erase entire window (’clear’)
    aesERASE_SAVED, // erase "saved" lines
    aesERASE_EOL,   // erase from cursor to end of line
    aesERASE_BOL,   // erase from cursor to beginning of line
    aesERASE_LINE,  // erase entire line
  The specified erasure is performed relative to the current cursor position UNLESS an offset is specified:
    rowOff : row offset from current row
    colOff : column offset from current column
  Important Note: If the specified offset moves the cursor beyond the edge of the terminal window, unexpected side-effects may occur.

  See also the direct erasure method, acClearArea.

Misc Methods

• void AnsiCmd::acBeep ( short repeat, short delay, int freq ) const;

    Input  : repeat : (optional, 1 by default) repeat count
                      Range: 1 - 32,767
             delay  : (optional, 5 by default i.e. 1/2 second)
                      delay between successive beeps in tenths of a second
                      in the range: 2 - 600 (0.2sec through 1.0min)
                      Note: The system is unable to handle short delays, so
                            a delay of two-tenths second is the safe minimum.
             freq   : (optional, -1 by default)
                      if specified, this is the auditory frequency of the beep
                      [CURRENTLY IGNORED]
  
    Returns: nothing
  

  Invoke the console’s default auditory alert (beep).

  When called without parameters, the acBeep method produces a single beep (or whatever sound your terminal is set up to produce when the ASCII Bell control code is received.

  Three optional parameters are available: 'repeat', 'delay', and freq' as shown above.

  The repeat parameter is straightforward, specifying the number of individual beeps to produce from 1 (default) to 32,767, although we can attest that anything over about 200 will cause everyone in your household to toss the nearest loose object in your direction.

  The delay parameter specifies the (approximate) pause between beeps. The quality and repeatability of the tone is heavily dependent upon the delay between beeps. This is because the the actual physical timer used and the system code which controls it are both shared resources.
  The delay interval may be specified as a multiple of 0.10 (1 tenth) second, with the default being 0.5 (5 tenths) second, and the maximum being one minute (600 tenths). For a stable repeatable sound, the practical minimum is two or three tenths (0.2 - 0.3) of a second.

  The freq parameter specifies the frequency of the tone that will be produced. For the current (pre)release, this parameter is ignored, and the tone is produced by simply issuing the ASCII Bell control code.
  For the production release, however, we hope to implement a more robust and flexible sound control.

  
  
• void AnsiCmd::nsleep ( uint16_t tenths, uint16_t millisec, time_t nanosec ) const;

    Input  : tenths  : specifies the sleep interval in tenths of a second
                       (1/10 sec == 0.10 sec)
             millisec: (optional, zero by default) for finer control over the
                       length of the delay, specify a delay in milliseconds.
             nanosec : (optional, zero by default) for even finer control over
                       the length of the delay, specify a delay in nanoseconds.
                       [CURRENTLY IGNORED]
  
    Returns: nothing
  

  Sleep (pause) execution for the specified time period. This method encapsulates access to the C-language 'nanosleep' function. It is intended to simplify the the interface and replaces direct calls to the obsolete C-language sleep and usleep functions.

  The primary delay value is specified in tenths of a second (0.10sec), with a secondary delay specification in milliseconds (0.001sec). The sum of the two values specifies the total duration of the delay.
  Thus the effective minimum delay is 1 millisecond, while the theoretical maximum delay is: 65535/10 or 6553 minutes + 65535 milliseconds or approximately 6618 minutes.This is an impractically large number, so we arbitrarily limit the maximum delay to 61 minutes, which is approximately 60 minutes more than anyone will likely ever need.
                1 millisecond <= delay <= 61.0 minutes
  Note that the 'nanosec' parameter is currently ignored. (see tech notes below)

  The philosophy here is that delays of less than one tenth of a second are not very useful for a human interface, while smaller delays are oriented toward computer-oriented tasks and which are limited only by the resolution of the clock referenced by the called function.

  Technical Notes

  In C++, the cosmopolitan way to delay the action is to use the 'chrono' class to define the delay, and the 'sleep_for'
  method to execute it.
  Example: chrono::duration<short>aWhile( 10 );
         this_thread::sleep_for( aWhile );
Example: chrono::duration<short, std::milli>aMoment( 250 );
         this_thread::sleep_for( aMoment );
  The chrono/sleep_for C++ implementation is much cleaner and more intuitive than nanosleep(); however, ANSI escape sequences are by definition incompatible with multi-threaded environments, so we do not introduce multi-threading in the AnsiCmd class.
  Instead, we use the 'nanosleep' function which is technically sophisticated, but clunky in implementation. That is why we isolate it here to avoid cluttering up our otherwise lovely code.

  The nanosleep C-library function is defined in time.h and takes as parameters two 'timespec' structures as shown.

  #include <time.h> struct timespec { time_t tv_sec ; /* seconds */ long tv_nsec ; /* nanoseconds */ }; nanosleep ( const struct timespec *req, struct timespec *rem ) ;

  The first parameter 'req' (the ‘request’) specifies the duration of the sleep interval in seconds and nanoseconds. Note that the nanosleep function rounds the nanosecond value ('tv_nsec') upward to the resolution of the clock. Note also that the ('tv_nsec') value is limited to 9,000,000,000 (nine billion nanoseconds). Any larger value will generate an error.

  If the requested interval is completed without interruption, the second parameter ('rem') (the ‘remainder’) remains unused. If however, the sleep interval is interrupted by some system event, then the second parameter receives the remainder of the delay so that nanosleep can be called again to complete the specified sleep interval.

  The resolution of the clock used for this interval is also a significant factor in the accuracy of the operation.
  It is important to keep in mind that although nanosleep claims to be accurate in the nanosecond range, a number of factors may affect the results. For instance, the default Linux scheduler is based on ten-millisecond intervals, so sequential calls may be limited to this resolution. Some newer systems with newer kernel support may be able to provide a resolution of one(1) millisecond.

  See the documentation for the C-library 'clock_getres' function for more information on the clocks available on the host system.
  See also: "man 7 time", which indicates that the effective resolution is between 1 and 10 milliseconds.
  Also see the resolutions specified in the file: "/proc/timer_list". Most of the entries in that file specify a resolution of 1 nanosecond, but we see this as more aspirational, than mathematical.

  While the nanosleep function cannot be relied upon by timing-critical operations which may be affected by these factors, for user-oriented delays, into the tens-of–milliseconds range, however, the nanosleep function is a welcome addition to the C-language library.

  
  
• const char * acVersion ( void ) const;

    Input  : none
  
    Returns: pointer to version string
  

  This method return a const pointer to a string containing the AnsiCmd class version number. The version number takes the form: x.y.zz, where 'x' is the major version, 'y' is the minor version and 'zz' is the step version.
  Example: 0.0.03

  Unlike some other developers whom we will politely not name (Firefox), this author does not advance the major or minor version number without a very good reason. Therefore, even packages we have had in circulation for twenty years seldom advance beyond version 0.2.00. For instance, the gString class distributed with package, which we first released in 2011 is now at version 0.0.32, and yes, it is absolutely solid.

  
  
• bool AnsiCmd::acSetFont ( aeSeq font, uint8_t fontnum );

    Input  : font   : one of aesPRIMARY_FONT or aesALTERNATE_FONT which are
                      members of enum eSeq.
             fontnum: (optional, zero(0) by default)
                      specify the alternate font, range: 1 through 9
  
    Returns: 'true'  if valid greyscale attribute specified and set
             'false' if invalid parameter(s) specified
                     (attributes will not be modified)
  

  Specify the terminal font used to write subsequent text data.

  Specify the 'font' parameter as a member of enum aeSeq:
  

  aesPRIMARY_FONT set the primary font as the active font ('fontnum' parameter is ignored) aesALTERNATE_FONT set one of the alternate fonts as the active font USER# 1 2 3 4 5 6 7 8 9 translates to: ANSI# 11 12 13 14 15 16 17 18 19

  These commands are not recognized on any of our development platforms, but the font test is available for testing them on your particular system: (see Test_AltFonts).

  
  
• bool acSetIdeogram ( aeSeq idea );

    Input  : idea  : member of enum aeSeq within the ideogram-command group.
  
    Returns: 'true'  if valid argument
             'false' if invalid parameter(s) specified
                     (attribute will not be modified)
  

  Interface to the seldom-supported and little-used "ideogram" (logogram) group of ANSI commands.

  It is unclear what this group of commands was originally intended to do. Presumably they were intended to provide some kind of border or highlighting around a block of text.
    aesIDEO_UNDER       // ideogram underlined
    aesIDEO_UDOUBLE     // ideogram double-underlined
    aesIDEO_OVER        // ideogram overlined
    aesIDEO_ODOUBLE     // ideogram double-overlined
    aesIDEO_STRESS      // ideogram stress marking (italic?)
    aesIDEO_OFF         // all ideogram attributes off
  These are probably non-functional, but they can be tested using this method.

  See acDrawBox and acDrawLine methods for line drawing options.

API Methods

The API (Application Programming Interface) methods are designed to encapsulate some of the more common operations performed as a sequence of calls to the low-level primitive methods. Using the API methods reduces code clutter at the application level, which will hopefully reduce development and debugging time for the application.

Color Attribute Methods
The most significant difference between the ANSI primitives and the API layer is the way color attributes are encoded. While the terminal emulator program interprets the ANSI escape sequences to set color attributes and text modifiers, it is rather inconvenient to work with them directly. Internally, the AnsiCmd library encodes color attributes as 32-bit bit fields.
    List of Attribute Names
    Attribute Bitfield Definitions

Display Formatting Methods
Erase the current data displayed in the specified area of the terminal window, or format text paragraph data to fit within a specified area.

Line Drawing Methods
Draw horizontal and vertical lines or draw rectangles in the terminal window.

Identify "Special" Keycodes
Identify whether a given keycode matches one of the defined “special” or “command-key” keycodes.

Temporary File Management
Create and manage temporary files for useby the application.

Communicate With System Clipboard
Establish a communications channel with the system clipboard and exchange text data with the clipboard.
    AnsiCmd Clipboard Access

Color Attribute Methods

• bool AnsiCmd::acSetAttributes ( acAttr newAttr, bool resetAll = false );

    Input  : newAttr : bitfield containing the logical OR of the desired
                       foreground/background attributes and text modifiers.
             resetAll: (optional, 'false' by default)
                       if 'false', only the the attributes specified by
                                   'newAttr' will be modified.
                       if 'true',  all attributes and modifiers will be reset
                                   to their default values before the new
                                   attributes are applied.
  
    Returns: 'true' if successful, else 'false' (currently always 'true')
  

  Modify or replace the current color attributes and/or text modifiers.

  The basic group of AnsiCmd methods set or reset one attribute per call by issuing the corresponding ANSI escape sequence designated as a member of enum aeSeq (ansi escape Sequence). The acSetAttributes method, by contrast, takes as a parameter the logical OR of an arbitrary number of attributes designated as members of enum acAttr (ansi cmd Attribute). Arguably, this provides a cleaner interface between the application layer and the display-formatting functionality.

  The individual enum acAttr members are OR'd together to produce the 'newAttr' parameter sent to acSetAttributes.

  The examples below demonstrate how a logical OR of acAttr values specifies the attribute(s) to be modified.

  Note that when performing any mathematical operation using members of an enumerated type such as enum acAttr, the compiler will complain. For instance, when performing a logical OR using members of enum acAttr, the compiler insists that the result be cast back into the acAttr type. For example, the compiler will complain about this assigment:
     acAttr newAttr = acaFG_BLUE | acaBG_GREEN ;
  so to make the compiler happy we perform a cast back to the type:
     acAttr newAttr = acAttr(acaFG_BLUE | acaBG_GREEN) ;
  Please see enum acAttr, below for more detailed information.

  • To set the foreground color attribute to blue text:
       acSetAttributes ( acaFG_BLUE ) ;
  • To set the background color attribute to green:
       acSetAttributes ( acaBG_GREEN ) ;
  • To simultaneously set both foreground and background color attributes:
       acSetAttributes ( acAttr(acaFG_BLUE | acaBG_GREEN) ) ;
  • To set Bold and Italic text modifiers:
       acSetAttributes ( acAttr(acaBOLD | acaITALIC) ) ;
  • To reset only a specific text modifier (or modifiers) combine the modifier(s) with the “acaCLEAR_MODS” member:
       acSetAttributes ( acAttr(acaCLEAR_MODS | acaBOLD) ) ;
  • To reset all text modifiers (i.e. plain text), call with only the “acaCLEAR_MODS” member:
       acSetAttributes ( acaCLEAR_MODS ) ;
  • To set Bold, blue foreground text, either specify a blue foreground in combination with the Bold attribute, or specify the bold blue attribute directly:
       acSetAttributes ( acAttr(acaBOLD | acaFG_BLUE) ) ;
   or
   acSetAttributes ( acaFGb_BLUE ) ;
  • RGB (Red/Green/Blue) or 8-bit color foreground and background attributes are specified as index values rather than as individual members of enum acAttr. For this reason, setting RGB or 8-bit attributes is a two-step process.
    First, call acComposeAttributes (described below) to construct the bitfield value, then call acSetAttributes with the resulting value.

    RGB attribute values combine 'acaFG_RBG' and/or 'acaBG_RGB' with “web-safe” color indices in the range: wsrgbMIN <= index <= wsrgbMAX. This example sets both foreground and background to web-safe RGB attributes:
    acAttr aca = acComposeAttributes( 14, 221, true, true );
acSetAttributes ( aca );

    Eight-bit attributes combine 'acaFG_INDEX' and/or 'acaBG_INDEX' with 8-bit color indices in the range: min8BIT <= index <= max8BIT. This example sets both foreground and background to 8-bit attributes:
    acAttr aca = acComposeAttributes( 32, 112, false, false );
acSetAttributes ( aca );
    See acComposeAttributes below for additional examples.

  • To reset all attributes and modifiers to their default values, and then set new fgnd/bgnd attributes and text modifiers, call with the 'resetAll' flag set:
       acSetAttributes ( acAttr(acaFG_BLUE | acaBG_GREY | acaUNDERLINE), true ) ;
  • To reset all attributes and modifiers to their default values, use the “acaATTR_DFLT” member in combination with the 'resetAll' flag:
       acSetAttributes ( acaATTR_DFLT, true ) ;
  
  
• acAttr acComposeAttributes ( uint8_t fgVal, uint8_t bgVal, bool rgbfg, bool rgbbg, acAttr mods = acaPLAINTXT )

    Input  : fgVal  : foreground index (8-bit index or web-safe RGB index)
                      -- if 'rgb' reset, then value interpreted as 8-bit index.
                         Range: 16-231 (or greyscale:232-255)
                      -- if 'rgb' set, then value interpreted as web-safe RGB
                         index. Range: 0-252
                      -- if 'rgb' reset AND 'fgVal' 0-15, then assume 4-bit color
             bgVal  : background index (8-bit index or web-safe RGB index)
                      -- if 'rgb' reset, then value interpreted as 8-bit index.
                         Range: 16-231 (or greyscale:232-255)
                      -- if 'rgb' set, then value interpreted as web-safe RGB
                         index. Range: 0-252
                      -- if 'rgb' reset AND 'fgVal' 0-15, then assume 4-bit color
             rgbfg  : if set, fgVal is interpreted as a (web-safe) RGB index
                      if reset, fgVal is interpreted as a 4/8-bit index
             rgbbg  : if set, bgVal is interpreted as a (web-safe) RGB index
                      if reset, bgVal is interpreted as a 4/8-bit index
             mods   : (optional, acaPLAINTXT by default)
                      logical OR of acAttr text-modifier flags)
  
    Returns: the constructed acAttr value
             (if a value is out-of-range, terminal default will be used)
  

  Construct an acAttr attribute bitmap from component values:
  Call this method when composing attributes with 8-bit fgnd/bgnd indices or web-safe RGB fgnd/bgnd indices.

  Use the constructed value as the parameter for a call to acSetAttributes, above.

  
  

  Examples:

  acAttr aca ;      // receives the constructed value
  
  Construct an 8-bit foreground and background value:
    aca = acComposeAttributes ( min8BIT + 2, min8BIT + 27, false, false );
  Construct a value with a 4-bit foreground on an 8-bit background:
    aca = acComposeAttributes ( 3, max8BIT - 32, false, false );
  Construct the same attribute value, but adding italic text.
    aca = acComposeAttributes ( 3, max8BIT - 32, false, false, acaITALIC );
  Construct a web-safe RGB foreground and background value:
    aca = acComposeAttributes ( wsrgbMIN + 16, wsrgbMAX - 32, true, true );
  Construct a value with an 8-bit foreground on an RGB background.
    aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true );
  Construct the same attribute value, but adding underlined text.
    aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true, acaUNDERLINE );
  Construct the same attribute value, but with italic _and_ underlined text.
    aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true, 
                                acAttr(acaITALIC | acaUNDERLINE) );
  
  Use the constructed value to set the specified attributes:
    acSetAttributes ( aca );
      or
    acSetAttributes ( acAttr(aca | acaITALIC | acaUNDERLINE) );
  

  Note on 4-bit values:
  The 4-bit color attributes are individually named, so the attributes may be specified directly.
  Examples: acSetAttributes( acAttr(acaFG_BLUE | acaBGb_BROWN) );
          acSetAttributes( acAttr(acaFG_DFLT | acaBGb_BLUE) );
          acSetAttributes( acAttr(acaFG_DFLT | acaBG_DFLT) );
  Although this method is not designed to configure 4-bit color indices (0-15), they will be handled correctly, EXCEPT THAT it is not possible to specify terminal default foreground or background using this method.
    aca = acComposeAttributes ( 3, 12, false, false );

  
  
• void acGetAttributes ( acaExpand& decodedAttr );

    Input  : decodedAttr: (by reference) instance of an acaExpand object 
                          to receive data.
  
    Returns: nothing
  

  Get a decoded copy of the current color attributes and text modifier flags.

  The bitfield containing the attributes is decoded into it component values.

  Refer to the description of the acaExpand class data members for more information.

Technical Notes on the acAttr Enumerated Type

The acAttr (AnsiCmd Attributes) enumerated type provides application-level color-attribute and text-modifier configuration for terminal applications. The enumerated list, enum acAttr is defined in AnsiCmdDef.hpp.

Members of this type specify color attributes and text modifiers in a consistent format which encapsulates the primitive ANSI escape sequences defined for terminal-window text formatting. (see enum aeSeq).

Within the AnsiCmd class, these values are decoded and mapped to their corresponding ANSI escape sequences (or group of sequences). This allows the application to focus on algorithms and user interaction rather than reading and writing binary data within the terminal window.

Although acAttr is defined as an enumerated type, is constructed as a group of macros defining bitfields. This allows the macros to be grouped in a coherent manner while also allowing bitwise OR operations for the desired foreground, background and text-modifier attributes. For example, combine foreground, background attributes PLUS the “bold” and “italic” text attributes, then pass the value as an argument to one of the application-level methods.
   acAttr txtAttr = acAttr(acaFG_GREEN | acaBG_GREY | acaBOLD | acaITALIC) ;
   acSetAttributes ( txtAttr ) ;

Technical Note: The compiler will complain when performing any mathematical operations on members of an enumerated type; therefore, be sure to cast the OR’d value back to the acAttr type. For instance, the following would cause a compiler warning: acAttr a; a |= acaBOLD;
Instead, use the following syntax: a = acAttr(a | acaBOLD);

See also the acaExpand class below for more information on encoding and decoding the bitfield values.

---

Bit Twiddling — the acaExpand Class

Late Night host, Seth Meyers once defined nerds as people “with coffee-breath and crippling anxiety.” While that characterization was a bit rude, he actually wasn’t wrong. For all OCD sufferers, (otherwise known as technically proficient people), having more information is like having a mug of hot cocoa and a warm blanket.

So, while accessing the API method group (which includes the ACWin class), does not require an understanding of the bit manipulations that occur within the AnsiCmd library, our nerd DNA insists that we have at least a general idea what’s going on in the binary jungle.

All significant bit-oriented operations are encapsulated within the acaExpand class. The data managed by the acaExpand class are derived from the acAttr enumerated type and the WebSafeRGB enumerated type. These are both defined in AnsiCmdDef.hpp.

The acaExpand class is also defined in AnsiCmdDef.hpp, and is implemented in the AnsiCmdAca.cpp source module.

All methods and data members of the acaExpand class are “public”; however, the live data are not available to the application (Duh!). If desired, however, a copy of the live data data may be retrieved and studied.
Please see acGetAttributes, above.

acaExpand Methods

~acaExpand ( void ) ; // destructor

acaExpand ( void ) ; // default constructor

acaExpand ( acAttr bits ) ;
Initialization Constructor:
The 'bits' parameter consists of one or more members of enum acAttr combined using a logical OR. Example:

   acaExpand aca( acAttr(acaFG_RED | acaBG_GREY) );

void decode ( acAttr bits ) ;
Decode the specified bitfield value into it component parts and store them in the data members.

   acaExpand aca;
   aca.decode( acAttr(acaFG_RED | acaBG_GREY) );

acAttr modify ( acAttr acaValue, bool add ) ;
Add (or remove) one or more elements to (from) the bitfield value.
   'acaValue'  specifies the item(s) to be modified.
        'add'  (optional, ’true’ by default)
               referenced ONLY for text modifiers, not color attributes
               if true, add the ’acaValue’ items to the existing bitfield
               if false, remove (reset) the specified items

   acaEx.modify( acaBOLD, true );
   acaEx.modify( acaBOLD, false );
   acaEx.modify( acAttr(acaFGb_RED | acaBG_BLUE) );

void update ( aeSeq aesValue, uint8_t colorIndx = ZERO );
Update attribute tracking data by converting the provided member of
enum aeSeq to the equivalent acAttr bitfield value.
   'aesValue'  aeSeq item specifying attribute to be updated
  'colorIndx'  for aeSeq items requiring a color-attribute index value
(Used internally, but not really useful at the application level.)

acAttr compose ( void );
Construct an acAttr attribute bitmap from the data in the data members:
fgIndex, bgIndex and the boolean (flag) members. This is the reverse of the 'decode' method, above, and is used to encode 8-bit and RGB attribute indices. (Used internally, but not really useful at the application level.)
Please refer to the API-level method acComposeAttributes which calls the ’compose’ method with consistent formatting.

bool swap ( void );
Swap (exchange) the foreground and background attributes.
Text modifiers are not affected.

acAttr buildRgb ( bool fg, WebSafeRGB fgVal, 
                  bool bg = false, WebSafeRGB bgVal = wsrgbMIN ) const
Construct an acAttr bitfield from web-safe RGB color indices.
Specify RGB values for foreground and/or background color attributes. The values are members of enum WebSafeRGB which encode the RGB 'hue' and 'shade' used to initialize the Red/Green/Blue register values.
   'fg'     ’true’  if foreground value specified in ’fgVal’
            ’false’ if ’fgVal’ is to be ignored
   'fgVal'  member of enum WebSafeRGB
            if ’fg’ flag is set, web-safe RGB foreground value
            if ’fg’ flag is reset, this value is ignored
   'bg'     ’true’  if background value specified in ’bgVal’
            ’false’ if ’bgVal’ is to be ignored
   'bgVal'  member of enum WebSafeRGB
            if ’bg’ flag is set, web-safe RGB background value
            if ’bg’ flag is reset, this value is ignored
Returns: the constructed acAttr bitfield (If one or more parameters out-of-range, acaATTR_DFLT is returned.

Examples:

1) Construct a bitfield with medium red foreground and dark blue background.
   acaExpand aca ;
   acAttr newVal =
         aca.buildRgbVal ( true, WebSafeRGB(wsrgbRED + wsrgbSHADE_MED),
                          true, wsrgbBLUE );
   aca.decode( newVal );

2) Construct a bitfield with bright cyan background, and with a standard 
   4-bit (non-RGB) blue foreground.
   acaExpand aca ;
   acAttr newVal =
         aca.buildRgbVal ( false, wsrgbMIN,
                           true, WebSafeRGB(wsrgbCYAN + wsrgbSHADES - 1) );
   newVal = acAttr(newVal | acaFG_BLUE);
   aca.decode( newVal );

3) Construct a bitfield with bright magenta foreground, and a medium blue 
   background shade.
   acaExpand aca ;
   acAttr newVal =
         aca.buildRgb ( true, WebSafeRGB(wsrgbMAGENTA + wsrgbSHADE_MAX), 
                        true, WebSafeRGB(wsrgbBLUE + wsrgbSHADE_MED / 2) );
         aca.decode( newVal );

4) Construct a bitfield with bright yellow foreground and a medium blue
   background.
   acaExpand aca ;
   acAttr newVal =
         acaBld.buildRgb( true, WebSafeRGB(wsrgbBROWN + wsrgbSHADE_MAX),
                          true, WebSafeRGB(wsrgbBLUE + wsrgbSHADE_MAX * 0.65) );
   aca.decode( newVal );

acAttr build8Bit ( bool fg, uint8_t fgVal, bool bg, uint8_t bgVal ) const
   'fg'     ’true’  if foreground value specified in ’fgVal’
            ’false’ if ’fgVal’ is to be ignored
   'fgVal'  index of foreground attribute, range: min8BIT - max8BIT
            if ’fg’ flag is set, calculate foreground bitfield
            if ’fg’ flag is reset, this value is ignored
                    and foreground bits are initialized as reset
   'bg'     (optional, ’false’ by default)
            ’true’  if background value specified in ’bgVal’
            ’false’ if ’bgVal’ is to be ignored
   'bgVal'  (optional, min8BIT by default)
            index of background attribute, range: min8BIT - max8BIT
            if ’bg’ flag is set, calculate background bitfield
            if ’bg’ flag is reset, this value is ignored
                    and background bits are initialized as reset
Returns: the constructed acAttr bitfield

   acaExpand acaBld ;
   acAttr pbAttr = acaBld.build8Bit( true, 160, true, 82 ) ;
   acAttr sbAttr = acaBld.build8Bit( true, 16, true, 219 ) ;
   acAttr rbAttr = acaBld.build8Bit( false, 0, true, 219 ) ;
   acAttr sbAttr = acaBld.build8Bit( true, 16 ) ;

aeSeq bits2aeseq ( acAttr acaBits, uint8_t byteIndx, bool isFgnd, bool isRgb );
Convert between acAttr (bitfield) and aeSeq (ANSI escape sequence).
Note: If the aeSeq value is one of the 4-bit "bold" foreground attributes, the ’boldMod’ flag is set. Otherwise the flag is not modified.
    'acaBits'  acAttr bitfields to be converted
   'byteIndx'  byte index value (either foreground or background index)
               (currently unused)
     'isFgnd'  true if foreground target, false if background target
      'isRgb'  (optional, false by default)
               true if 'acaBits' references one of the
                    web-safeRGB register indices, minRGB-maxRGB.
               ’false if ’acaBits’ is a lookup table index:
                     0-15 : 4-bit color index
                   16-231 : 8-bit color index
                  232-255 : greyscale index
Returns: member of enum aeSeq

   acAttr attrBits = acAttr(acaFG_CYAN | acaBG_BLUE) ;
   WebSafeRGB attrRgb = wsrgbBLUE + wsrgbSHADE_MED ;
   acaExpand acax ;
   // 8-bit background
   aeSeq attrSeq = acaex.bits2aeseq ( attrBits, 0, false );
   // RGB foreground
   attrSeq = acaex.bits2aeseq ( attrRgb, 0, true, true );

acAttr aeseq2bits ( aeSeq aesCmd, bool& setFlag );
Convert between aeSeq (ANSI escape sequence) and acAttr (bitfield).
For named escape sequences only; specifically:
   a) 4-bit foreground
   b) 4-bit background
   c) text modifier flags
All other aeSeq values return acaPLAINTXT (i.e. zero).
Note: If the aeSeq value is one of the 4-bit "bold" foreground or background attributes, the ’boldMod’ flag is set.
Otherwise the flag is not modified.
     'aesCmd'  member of enum aeSeq to be converted
    'setFlag'  (by reference) receives the state of the internal
               set/reset flag associated with the attribute
Returns: member of enum acAttr

   aeSeq fgnd = aesFGb_BLUE ;
   bool flag ;
   acaExpand acax ;
   acAttr convAttr = acax.aeseq2bits( fgnd, flag ) ;

   Returns:
   convAttr == acaFGb_BLUE  and  flag == true

bool web2regs ( uint8_t webrgb, bool fgnd );
Convert web-safe RGB index into red/green/blue RGB register values.
     'webrgb'  value indicating one of the web-safe RGB register groups
               in the range: wsrgbMIN <= webrgb <= wsrgbMAX.
       'fgnd'  true if fgnd attributes, false if bgnd attributes
216 web-safe colors are defined by the standard, which are mapped to the 256 color indices defined for terminal color attributes and are then translated to individual R, G and B register values as shown.

                DARK >>>> LIGHT   CORRESPONDING RGB REGISTER INDICES
 Black        :    0               16;16;16
 Red group    :    1      36       22;16;16  >>>>  231;16;16
 Green group  :   37      72       16;22;16  >>>>  16;231;16
 Blue group   :   73     108       16;16;22  >>>>  16;16;231
 Brown group  :  109     144       22;22;16  >>>>  231;231;16
 Magenta group:  145     180       22;16;22  >>>>  231;16;231
 Cyan group   :  181     216       16;22;22  >>>>  16;231;231
 Grey group   :  217     231       22;22;22  >>>>  231;231;231

void reset ( bool modsOnly = false ) ;
Reset (clear) all data members. Optionally, reset text-mod flags only.
   'modsOnly'  if true, reset only the text-modifier attributes
               if false, reset all color and text-modifier attributes

acaExpand Data Members

Note that while there is some redundancy among the members, the layout of the data members is constructed for speed of access and to minimize the need for higher-level methods to perform bitwise operations. This in turn reduces the chance of processing errors.

acAttr    acaVal;    full, encoded acAttr value
uint32_t  fgBits;    nine bits defining foreground: index byte + fg default flag
uint32_t  bgBits;    nine bits defining background: index byte + bg default flag
uint32_t  allFlags;  all binary flags (excludes fg/bg indices)
uint32_t  modFlags;  text-modification flags (subset of ’allFlags’)
acAttr    acaFgnd;   8-bit field defining the foreground index
acAttr    acaBgnd;   8-bit field defining the background index
aeSeq     aesFgType; Foreground attribute type:
                     aesFG_DFLT:  4-bit color
                     aesFG_INDEX: 8-bit color
                     aesFG_RGB:   r/g/b color
aeSeq     aesBgType; Background attribute type:
                     aesBG_DFLT:  4-bit color
                     aesBG_INDEX: 8-bit color
                     aesBG_RGB:   r/g/b color
aeSeq     aesFgnd;   4-bit foreground (member of enum aeSeq)
aeSeq     aesBgnd;   4-bit background (member of enum aeSeq)
uint8_t   fgIndex;   foreground byte index
uint8_t   bgIndex;   background byte index
uint8_t   rgbFgR;    if RGB foreground, Red register value
uint8_t   rgbFgG;    if RGB foreground, Green register value
uint8_t   rgbFgB;    if RGB foreground, Blue register value
uint8_t   rgbBgR;    if RGB background, Red register value
uint8_t   rgbBgG;    if RGB background, Green register value
uint8_t   rgbBgB;    if RGB background, Blue register value
bool      fgDflt;    if set, terminal default foreground (ignore fg index bits)
bool      bgDflt;    if set, terminal default background (ignore bg index bits)
bool      boldMod;   if set, Bold (intense) text
bool      italicMod; if set, Italic text
bool      ulineMod;  if set, Underlined text
bool      olineMod;  if set, Overlined text
bool      xoutMod;   if set, X-out (strikethrough) text
bool      blinkMod;  if set, Blinking text
bool      invisMod;  if set, Invisible (concealed) text
bool      revMod;    if set, Reversed foreground and background
bool      clrMods;   if set, Clear existing mods before setting new mods
bool      fgRgb;     if set, rgbFgR, rgbFgG and rgbFgB contain the foreground color
bool      bgRgb;     if set, rgbGbR, rgbBgG, and rgbBgB contain the background color

acaExpand Decoding Examples

AnsiCmd (enum acAttr) color-attribute bit fields:
0x000000FF  index for foreground color
            ......00-......0F  16  4-bit color attributes
            ......10-......E7  216 8-bit color attributes
            ......E8-......FF  24  greyscale color attributes
            ......00-......FC  232 RGB color attributes
0x0000FF00  index for background color
            ....00..-....0F..  16  4-bit color attributes
            ....10..-....E7..  216 8-bit color attributes
            ....E8..-....FF..  24  greyscale color attributes
            ....00..-....FC..  232 RGB color attributes
0x00FF0000  text modifier flags
            ..00....   plain text (no modifiers)
            ..01....   bold (intense)
            ..02....   italic
            ..04....   underline
            ..08....   overline
            ..10....   x-out (strike-through)
            ..20....   blink
            ..40....   concealed (invisible)
            ..80....   reversed fg/bg
0xFF000000  additional flags
            01......   clear existing modifiers before setting the new ones
            02......   use terminal default foreground attribute
                       (foreground index ignored)
            04......   if set, it indicates that foreground index is the
                       index of a "web-safe" RGB foreground color attribute
                       with a range of: minRGB <= value <= maxRGB
            08......   use terminal default background attribute
                       (background index ignored)
            10......   if set, it indicates that background index is the
                       index of a "web-safe" RGB background color attribute
                       with a range of: minRGB <= value <= maxRGB
            20......   (reserved)
            40......   (reserved)
            80......   (reserved as internal placeholder value)

The following shows some examples of how the bitfield is constructed.
The contruction is performed by creating a logical OR of enum acAttr members;
or in the case of 8-bit and RGB color attributes by using the 'compose' method
described above.
See also the AnsiCmd 'acComposeAttributes' public method.

To specify the terminal default foreground attribute, set the acaFG_DFLT flag.
The foreground index value will be ignored.
   Fgnd:  xxxx-x01x-xxxx-xxxx-xxxx-xxxx-....-....

To specify the terminal default background attribute, set the acaBG_DFLT flag. 
The background index value will be ignored.
   Bgnd:  xxx0-1xxx-xxxx-xxxx-....-....-xxxx-xxxx

To specify a 4-bit foreground attribute, _reset_ the acaFG_DFLT and
acaFG_RGB flags and insert the desired member of enum acAttr in the range:
acaFG_BLACK through acaFGb_GREY inclusive.

To specify a 4-bit background attribute, _reset_ the acaBG_DFLT and
acaBG_RGB flags and insert the desired member of enum acAttr in the range:
acaBG_BLACK through acaBGb_GREY inclusive.

To specify an 8-bit indexed color foreground attribute, initialize the
foreground index and _reset_ both the acaFG_DFLT and acaFG_RGB flags.
   Fgnd:  xxxx-x00x-xxxx-xxxx-xxxx-xxxx-nnnn-nnnn

To specify an 8-bit indexed color background attribute, initialize the
background index and _reset_ both the acaBG_DFLT and acaBG_RGB flags.
   Bgnd:  xxx0-0xxx-xxxx-xxxx-nnnn-nnnn-xxxx-xxxx

To specify one of the "web-safe" RGB register combinations, initialize
the foreground or background index and set the acaFG_RGB or acaBG_RGB 
flag, respectively. 
   Fgnd:  xxxx-x10x-xxxx-xxxx-xxxx-xxxx-nnnn-nnnn
   Bgnd:  xxx1-0xxx-xxxx-xxxx-nnnn-nnnn-xxxx-xxxx

To set one or more text modifiers, _reset_ the acaCLEAR_MODS flag and
create a logical OR of the desired attributes. (include existing fg/bg bits.)
Ex: acAttr fgbg = acAttr(acaFG_BLUE | acaBGb_RED);
    acAttr((fgbg |acaBOLD | acaITALIC | acaUNDERLINE) & ~acaCLEAR_MODS)
   Mods:  xxxx-xxx0-xxxx-x111-xxxx-xxxx-xxxx-xxxx

To reset one or more text modifier, set the acaCLEAR_MODS flag and _set_
the flag(s) for the modfier(s) to be reset. (include existing fg/bg bits.)
Ex: acAttr(fgbg | acaITALIC | acaCLEAR_MODS)
   Mods:  xxxx-xxx1-0000-0010-xxxx-xxxx-xxxx-xxxx

Display Formatting Methods

• void acClearScreen ( wchar_t fillchar = L' ', acAttr fillattr = acaUSEDFLT );

    Input  : fillchar: (optional, space character ' ' by default)
                       specify a (single-column) character to be written to
                       each character cell of the terminal window
             fillattr: (optional, default: terminal default attribute)
                       color attribute for clearing the terminal window.
                       Note: If a non-default attribute is specified, that will
                             be the current fg/bg attribute on return.
  
    Returns: nothing
  

  Clear the entire terminal window using the specified fill character and color attribute.

  On return, the visible cursor will be at the HOME position (1,1).

  
  
• bool acClearArea ( short row, short col, short height, short width,
                  wchar_t fillchar = L' ',   acAttr fillattr = acaUSEDFLT );
• bool acClearArea ( WinPos wpOrig, short height, short width,
                  wchar_t fillchar = L' ',   acAttr fillattr = acaUSEDFLT );

    Input  : row     : top row of target area
             col     : left column of target area
                    OR
             wpOrig  : top row and left column of target area
  
             height  : number of rows in target area
             width   : number of columns in target area
             fillchar: (optional, ' ' by default)
                       specify a (single-column) character to be written to
                       each character cell in the target area
             fillattr: (optional, default: terminal default attribute)
                       color attribute for clearing the target area.
                       Note: If a non-default attribute is specified, that will
                             be the current fg/bg attribute on return.
  
    Returns: 'true'  if successful
             'false' if parameter(s) out-of-range
  

  Clear the specified rectangular area using spaces (default), or using the specified fill character.
  See acDrawLine below for an example invocation.

  Position, height and width of the area are adjusted as necessary to remain within the terminal window.
  See also the note in cursor offsets regarding 1-based vs. 0-based cursor positioning.

  Note: On return, the cursor position within the window will be indeterminate, so it is caller’s responsibility to adjust cursor position.

  
  
• short acFormatParagraph ( gString& gsTxt, short maxRows, short maxCols,
                          bool trunc = true, bool hypenbrk = false, short *truncIndex = NULL );
• short acFormatParagraph ( wchar_t* wTxt, short maxRows, short maxCols,
                          bool trunc = true, bool hypenbrk = false, short *truncIndex = NULL );

    Input  : on entry, contains raw message text and
             on return, contains formatted message text
             gsTxt    : (by reference) a gString Object
                      OR
             wTxt     : a wchar_t string (32-bit characters)
  
             maxRows  : maximum rows for message
             maxCols  : maximum columns on any message row
             trunc    : (optional, 'true' by default)
                        if 'true',  truncate the data if necessary to ensure
                                    that the data do not extend beyond the
                                    specified target area
                        if 'false', format the entire source text array, even
                                    if doing so requires violating the specified
                                    height of the target area (maxRows).
                                    (see also 'truncIndx' parameter)
             hyphenbrk: (optional, 'false' by default)
                        if 'false', automatic line breaks occur after space 
                                    characters only.
                                     ASCII space   (U+0020)
                                     CJK space     (U+3000)
                                     CJK comma     (U+3001) (see notes)
                                     CJK full stop (U+3002) (see notes)
                        if 'true',  in addition to the space ' ' characters,
                                    enable line break at:
                                     ASCII hyphen    '-' (U+002D)
                                     Unicode — '—' (U+2014)
                                     Unicode – '–' (U+2013)
                                     Unicode − '−' (U+2212)
             truncIndx: (optional, null pointer by default)
                         -- referenced _only_ when the 'trunc' flag is reset
                         if specified, points to a variable to receive the
                         index at which the data _would_have_been_ truncted to
                         fit the specified height of the target area if the
                         'trunc' flag had been set.
                         a) A positive value indicates that the data have not
                            been truncated, AND that the data extend beyond the
                            the specified target area.
                         b) A negative value indicates that it was not necessary
                            to truncate the data i.e. the data fit entirely
                            within the target area.
  
    Returns: number of text rows in formatted paragraph
  

  Reformat the provided text to fit within the specified dimensions.

    1) Remove all newlines.
    2) Perform word wrap to limit width of each row of the paragraph.
    3) If necessary, truncate the text to limit height of the paragraph.
       (but see the ’trunc’ and ’truncIndx’ parameters)

  This method is used internally by the ACWin-class objects when writing text in the window and when creating dialogs within the window, but may be used freely when sizing text for display.

  Both single-width and CJK double-width (two column) characters are handled by the this method.
  Note: “CJK” indicates the Chinese, Japanese, Korean (and historically, Vietnamese) character sets.

  Notes on automatic word wrap:

  1. Line breaks occur after the space character at the end of a token, (word). This means that the line is broken by placing the newline after the identified space character.
     Note: Currently the ASCII space character (20h) and the two-column CJK space (U+3000) are the only whitespace characters recognized.

     Special Case: In every-day use, CJK text seldom contains any spaces at all within a sentence, or even between sentences. Two-column punctuation is designed to provide a visual spacing effect. For this reason, we have made the design decision to process the following CJK ideographs as whitespace:
             '、' comma U+3001 and '。' full stop U+3002

     Caution: Tab characters ('\t') are not recognized as whitespace characters because they are effectively variable width characters. Don’t use them!

     Optionally, the ASCII hyphen and the Unicode hyphen-like characters can be treated as if they were whitespace for purposes of calculating where to break a line. See the 'hyphenbrk' parameter.

  2. When reformatting the data, it is possible that the text will be pushed beyond the specified number of rows. In this case, we have two options:
     1. Truncate the text after the last specified row is filled.
     2. Alert the caller about the number of rows actually required. Optionally, we can indicate the index at which the text would have been truncated so that caller can manually truncate the text if desired. (see the 'truncIndx' parameter)
  3. It is possible that a single token (word) will be longer than the width of the target area. Handling this (unlikely) scenario complicates the line-break algorithm, but could come into play; for instance: filespecs, URLs, or German words. :-)
     Filespecs and URLs should be parsed using specialized formatting methods. Long words, especially hyphenated words can be a problem. This method can optionally break after hyphens (see the 'hyphenbrk' parameter).
  4. Notes on automatic hyphenation at mid-word line breaks:
     Technically, hyphens should be placed between syllables, but that would require a full dictionary of the target language.
     “Can open... worms everywhere.” (Thank you, Chandler Bing.)
     • The hyphen used is the the Unicode &ndash; U+2013. This facilitates stripping them from the text if the text is copied and pasted elsewhere.
       Note the ideally we would use the so-called “soft hyphen,” Unicode &shy; U+00AD, but unfortunately the terminal sees that as a zero-width character making it invisible under most circumstances.
       Example of stripping characters using the gString utility:
        gString gsTxt(  "Dashing–through–the–snow–in–a–one-horse–open–sleigh." );
 short sindx = ZERO ;
 while ( (sindx = gsTxt.find( nDASH, sindx )) >= ZERO )
    gsTxt.erase( sindx, 1 ) ;
       Yields: "Dashing through the snow in a one-horse open sleigh."
       Note that the ASCII hyphen between ’one’ and ’horse’ is not affected.
       Please see gString Text Tool for more information on the gString text internationalization utility.
     • Programmer’s Note: If the current character is the same width as the hyphen, then the hyphen will be at the right edge of the target area. Otherwise there will be a one-column gap at the end of the line.
     • Special case: For multi-column characters, it is assumed that the characters belong to one of the CJK character sets. (This may not be true, but multi-column characters seldom appear in Romance languages.
       Therefore, for multi-column characters only, hyphens are not inserted after mid-token line breaks because there is no way of knowing if we are breaking in mid-word or between words unless we have access to dictionaries for those languages.
       (Again, “...worms everywhere.”)
  
  
• int acShellOut ( const char* cmd = NULL, bool clrWin = false, acAttr txtAttr = acaUSEDFLT );

    Input  :
       cmd    : (optional, default: null pointer) command to be executed
                -- any valid command, or sequence of commands may be
                   specified, using the syntax recognized by the shell
                   program.
                -- if a command is not specified, the default shell
                   program is invoked with a message similar to:
                   "type 'exit' to return."
       clrWin : (optional, default: false)
                if 'false', the called application begins output at the
                            at the current cursor position
                if 'true',  clear the terminal window before invoking the
                            command. The command will appear at the top
                            of the terminal window
       txtAttr: (optional, default: acaUSEDFLT)
                -- if the default value is seen, the the current color
                   attribute settings will be used for both the optional
                   clear of the window and for the text written by the
                   called terminal application.
                -- if a non-default value is specified, it is used for
                   both clearing the terminal window ('clrWin' parameter)
                   and as the color attributes used by the called program
                   for writing text to the window.
                   Note: Many console utilities override the existing
                         terminal attributes, so the specified attribute
                         may be ignored.
  
    Returns: exit code of child process
       Ideally, this is the exit code of the last utility run in the
       child process, but this cannot be guaranteed.
  

  Temporarily return control to terminal shell program.

  1. If specified, set foreground/background color attributes.
  2. If specified, clear the terminal window.
  3. Return I/O buffering and input echo settings to the terminal defaults.
  4. Any signal handlers which have been set within the application will become inactive while the shell program is in control. These signals will become available to the shell program and any utilities executing within the shell.
     Please see acCaptureSignals for a discussion of available signal handlers.
  5. When the application regains control, the previous I/O buffering, echo option and color attributes will be restored.

  This method uses the standard library 'system' function which in turn uses members of the 'exec' function group to format and execute the command and its arguments.
  Refer to standard library docs for details:
      info system
    man 3 system

  See also the ACWin-class ShellOut method.

Line Drawing Methods

• WinPos acDrawLine ( const WinPos& wpOrig, short length, bool vertical, LineType lType = ltSINGLE,
                     wchar_t begChar = L'\0', wchar_t endChar = L'\0' );

    Input  : pos     : offset from upper-left corner of terminal window to
                       upper-left corner of box (1-based)
             length  : length of the line: number of number of rows (vertical),
                       or number of columns (horizontal).
             vertical: 'true'  : vertical line
                       'false' : horizontal line
             lType   : (optional, ltSINGLE by default) line style
                        member of enum LineType: either ltSINGLE or ltDUAL
             begChar : (optional, null character by default)
                        specify the beginning endpoint character
             endChar : (optional, null character by default)
                        specify the final endpoint character
  
    Returns: cursor position at the end of the line:
             For horizontal lines, this is the column following the last character.
             For vertical lines, this is the column below the last character.
  

  Draw a horizontal or vertical line in the terminal window.
  Horizontal lines are drawn left-to-right.
  Vertical lines are drawn top-to-bottom.

  Optionally, the endpoint character(s) may be specified for the beginning and/or end of the line. The valid endpoint characters include any of the line-drawing glyphs defined in AnsiCmdDef.hpp. Note however, that the 'begChar' and 'endChar' parameter are not range checked, so the character specified (if any), will be written. (Use single-column characters only.) If the endpoint(s) are not specified, the line-drawing character is used as the endpoint character.

  Example:
     // define the dimensions of the box
     short hgt = 9, wid = 25 ;
     // define the upper left corner of the box object
     WinPos wp( 9, 9 ) ;
     // clear target area using optional color attributes, and note that
     // on return, the specified colors are still active.
     acClearArea ( wp, hgt, wid, L' ', acAttr(acaFGb_CYAN | acaBG_BLUE) ) ;
     // draw the box
     acDrawBox ( wp, hgt, wid, ltDUAL ) ;
     // move downward to start position of first line
     wp.row += 4 ;
     // draw a line the full width of the box with connections on each end
     acDrawLine ( wp, 25, false, ltSINGLE, wcsLTEEdv, wcsRTEEdv ) ;
     // move to the top center of the box
     wp = { 9, 21 } ;
     // draw a line that connects with the box at the top and terminates
     // with a line-intersection character
     wp = acDrawLine ( wp, 5, true, ltSINGLE, wcsTTEEdh, wcsINSECT ) ;
     // draw a line from below the intersect character to the bottom
     // of the box, and which terminates with a connector character
     acDrawLine ( wp, 4, true, ltSINGLE, NULLCHAR, wcsBTEEdh ) ;
  
          ╔═══════════╤═══════════╗
          ║           │           ║
          ║           │           ║
          ║           │           ║
          ╟───────────┼───────────╢
          ║           │           ║
          ║           │           ║
          ║           │           ║
          ╚═══════════╧═══════════╝
  

  
  
• WinPos acDrawBox ( WinPos pos, short height, short width, LineType lType = ltSINGLE, const char *text = NULL );

    Input  : pos   : offset from upper-left corner of terminal window to
                     upper-left corner of box (1-based)
             height: number of rows for box
             width : number of columns for box
             lType : (optional, ltSINGLE by default) line style
                     member of enum LineType: either ltSINGLE or ltDUAL
             text  : (optional, null pointer by default)
                     If specified, text to be written to interior of box.
  
    Returns: current cursor position within the box
  

  Draw a box in the terminal window and optionally write text in the box.

  This is a greatly simplified form of drawing a window. It simply draws a rectangle in the terminal window at the specified position and of the specified dimensions.
  The box is drawn using the currently active foreground and background colors.

  If parameters are out-of-range, the position and dimensions will be modified as necessary to fit within the terminal window.

  The position of the visible cursor is returned.
  If the 'text' parameter specifies text data to be written into the box, then the cursor will be positioned at the end of the text. Otherwise, the cursor will be positioned at the top-left corner of the interior of the box.
  See acDrawLine above for an example invocation.

  
  
• void acEraseBox ( WinPos wpOrig, short height, short width );

    Input  : pos   : offset from upper-left corner of terminal window to
                     upper-left corner of box (1-based)
             height: number of rows for box
             width : number of columns for box
  
    Returns: nothing
  

  Erase the specified area. This is a companion method to the acDrawBox method above. acEraseBox simply calls the low-level method to clear the text from the specified area.

  
  

  The AC_Box Class

• WinPos acBoxDraw ( AC_Box& box, const char* text = NULL );

    Input  : box : (by reference) configuration parameters for the object
             text: (optional, null pointer by default)
                   If specified, text to be written to interior of box.
  
    Returns: coordinates of upper-left corner of text area within the box
             (These coordinates are the one-based offset from the )
             (upper-left corner of the terminal window.           )
  

  Display the data of an AC_Box object in the terminal window.

  1. Clear the target area.
  2. Draw the box.
  3. Initialize the interior of the box to the specified background color.
  4. If specified, write the initial text to the interior of the box.
     1. Text will be written using the foreground and background attributes specified for the interior.
     2. Caller is responsible for ensuring that the text fits entirely within the interior area, AND that the final cursor position also lies within the interior area. Automatic text formatting is not performed.
  5. On return, the visible cursor will be positioned at the origin (upper-left corner) of the text area unless initial text data were specified, in which case the visible cursor will be positioned at the end-of-text.
  6. On return, color attributes will have been set to terminal defaults.
  
  

  AC_Box Example

  WinPos boxOrigin( 1, 16 ) ;
  short  boxHEIGHT = 11 ;
  short  boxWIDTH  = 48 ;
  LineType lType   = ltSINGLE ;
  aeSeq  borderFg  = aesFGb_GREY ;
  aeSeq  borderBg  = aesBG_BLUE ;
  aeSeq  textFg    = aesFG_BLUE ;
  aeSeq  textBg    = aesBG_CYAN ;
  const char* title = "  Life Is A.. What?!  " ;
  
  AC_Box box( boxOrigin, boxHEIGHT, boxWIDTH, lType, 
              borderFg, borderBg, textFg, textBg, title ) ;
  acBoxDraw ( box, "\n\n     Life is like a box of chocolates.\n"
                       "     You never know what you're gonna get.\n"
                       "      -- Forrest G." ) ;
  

  ┌───────────┤ Life Is A.. What?! ├───────────┐ │ │ │ │ │ Life is like a box of chocolates. │ │ You never know what you're gonna get. │ │ -- Forrest G. │ │ │ │ │ │ │ │ │ └──────────────────────────────────────────────┘
  
  
  
• void acBoxErase ( const AC_Box& box );

    Input  : box : (by reference) configuration parameters for the object
    Returns: nothing
  

  Erase the rectangular area drawn by the acBoxDraw method, above.

  The current color attributes will be used to clear the area.

  
  
• WinPos acBoxClear ( const AC_Box& box );

    Input  : box : (by reference) configuration parameters for the object
    Returns: coordinates of upper-left corner of text area within the box
  

  Erase the text area of of an AC_Box object.

  1. On return, the foreground/background color attributes are set to the colors specified for the interior of the object.
  2. On return, the visible cursor is set to the upper-left corner of the text area.

Identify "Special" Keycodes

• bool isSpecialKey ( wchar_t& wkey, bool alert = false, EchoOpt *eopt = NULL ) const;

    Input  : wkey : (by reference) keycode to be tested
  
             alert: (optional, 'false' by default) audible alert
                    'true'  execute a terminal beep if keycode under test
                            IS one of the supported soft-echo keycodes, but
                            IS NOT not included in the active soft-echo group.
                    'false' do not execute an audible alert
             eopt : (optional, null pointer by default)
                    If specified, this is a pointer to an alternate soft-echo
                    option to be used for the test.
                       (used internally for special-key verification)
  
    Returns: 'true'  if key is one of the ACTIVE special keys
             'false' if key is not one of the active special keys
                     If the caller's keycode is a Special key that IS NOT a
                     member of the active group. the keycode will be set to
                     the null character (NULLCHAR) on return.
  

  Determine whether the specified keycode is one of the "special" keys, AND whether that keycode is a member of the active soft-echo sub-group.

  The test is performed against the soft-echo option specified by the prior terminal setup, (but see the ’eopt’ argument).

  The available character-echo options are members of enum EchoOpt.
  Please refer to TermConfig Class, and specifically the 'echoOption' member variable for terminal setup information.

  Each of the soft-echo options encompasses a subset of the supported "special" keycodes.
  Please see Soft Echo Options for a description of the soft-echo groups.

  NOTE: This method should not be called when the echo option is not one of the soft-echo options, but if it is, it will only result in a harmess waste of CPU cycles.

  
  
• bool isCommandKey ( wchar_t& wkey, bool all = false ) const;

    Input  : wkey : (by reference) keycode to be tested
             all  : (optional, 'false' by default)
                    if 'true', include the "special" keycodes as command keycodes*
                    if 'false, "special" keycodes are excluded
  
    Returns: 'true' if keycode is one of the command keycodes, else 'false'
  

  Determine whether the specified keycode is one of the converted keycodes: 1) ASCII control codes: Ctrl+A - Ctrl+Z, Ctrl+4, Ctrl+5, Ctrl+6, Ctrl+7. 2) "GUI" command keys: Alt+A - Alt+Z, Alt+punctuation characters. 3) Ctrl + navigation keys. 4) Left Alt + navigation keys 5) Function keys: wcsF01-fcsF12, wcsSF01-wcsSF12, wcsCF01-wcsCF12

  By default, this test excludes the “special” keycodes. (see isSpecialKey), however, this method may optionally include the “special” keycodes within the command-key group by setting the 'all' flag.

  Technical Note: These keycodes have been converted from escape sequences or ASCII control codes to graphing characters; however, they should not be echoed to the display. They would just look like garbage from the user’s point of view. If the keycode is not associated with an action within the application, it should be discarded. See the (protected) normalkeyProc method for additional information.

Temporary File Management

Temporary files are an integral part of any application which needs to interact with the host system or with other applications. The AnsiCmd library provides full support for creating and managing temporary files within the system temporary directory.

Although the AnsiCmd library does not make use of temporary files internally; most non-trivial applications do. For this reason, management of temporary files for applications based on the AnsiCmd library is encapsulated here to provide a clean interface to the compiler’s standard library functions for creating and deleting temporary files.

These methods, in turn, rely on the author’s TFMan class which is a stand-alone class included in, but functionally seperate from the AnsiCmd/ACWin/ACDlg group.
Please see TFMan Class for a full description of this class and the associated test utility TFMTest Demo App.

• bool acCreateTemppath ( const char* prefix = NULL );

    Input  : prefix : (optional, default: null pointer)
                      specify a constant token which will prefix the name of the
                      temporary sub-directory in which temp files will be created.
                      If a prefix is not specified, then the default "ANSICMD_"
                      prefix token is used.
                      Important Note: Use only valid filename characters 
                                      (not "special" chars) for the prefix string
  
    Returns: 'true'  if path/dirname created successfully
             'false' if call to standard library function failed
  

  Enable support for temporary files:
  Create a unique sub-directory within the system’s temp-file directory to contain the application’s temporary files.

  Internally, this is implemented by creating an instance of the 'TFMan' class. The Temp File Manager class encapsulates creation and deletion of temporary files. This prevents one of the most common programmer errors, namely exiting the application and leaving orphaned temp files for the system to clean up. This can be especially important if your temp files contain sensitive information.

  The optional 'prefix' parameter is used as the leading substring for the filename to be constructed. A unique six-character sequence will be appended to this sequence to form the name of the subdirectory.

  Example: AnsiCmd *acptr = new AnsiCmd() ; acptr->acCreateTemppath ( "MyApp_" ) ; will result in a directory name of the form: MyApp_rPuyzA

  This name is guaranteed to be unique within the system’s temporary directory.

  If no prefix is specified, then the default prefix ("ANSICMD_") will be used.

  
  
• void acDeleteTemppath ( void );

    Input  : none
    Returns: nothing 
  

  Disable support for temporary files.
  Delete the sub-directory containing the application’s temporary files and any files remaining in that subdirectory.

    1) May be called directly by the application layer, or else
    2) Will be called by the AnsiCmd-class destructor.

  
  
• bool acCreateTempfile ( gString& tempPath );

    Input  :
       tmpPath: (by reference) receives the path/filename of the new file
    Returns:
       'true'  if file created successfully
       'false' if library call failed
  

  Create a unique path/filename for a temporary file, then create the file.
  The file will have been closed and will be empty (will contain no data).

  gString tmpPath ; ACWin* win = new ACWin( ... ); ... win->acCreateTempname ( "SAM_" ) ; if ( (win->acCreateTempfile ( tmpPath )) ) { ofstream ofs ( tmpPath.ustr(), ofstream::out | ofstream::app ) ; if ( (ofs.is_open()) ) { ofs << "Write some data to the temp file." << endl ; ofs.close() ; } } // This is optional. If this method is not explicitly called by // the application, it will be called by the ACWin/AnsiCmd destructor. win->acDeleteTempname () ;
  
  
• bool acDeleteTempfile ( const gString& tempPath );

    Input  :
     tmpPath : full path/filename specification of source
    Returns:
       'true'  if successfully deleted
       'false' if library call failed
  

  Delete the specified temporary file.

  This method will delete the specified file ONLY if the file resides within the temporary subdirectory created by acCreateTemppath.

Communicate With System Clipboard

• bool acClipboardEnable ( gString* version = NULL );

    Input  :
       version : (optional, default: null pointer) if specified, 
                  pointer to gString object which receives version 
                  number of the WaylandCB class _and_ if available, 
                  the version number of the wl-clipboard utility.
  
    Returns: 
       'true'  if system clipboard connection established
       'false' if unable to connect: wl-clipboard utilities 
               not installed or inaccessable, or system error
  

  Establish communications with the system clipboard.
  It is assumed that the system clipboard is managed by the Wayland protocol, which is the case for most modern Linux distributions.

  Create a temporary file in the system temp directory. This file is used for communications with the external “wl-clipboard” utilities, “wl-copy” and “wl-paste”.
  Please see AnsiCmd Clipboard Access for a discussion of these utilities.

  If the wl-clipboard utilities are installed and accessible, establish the connection with the system clipboard.

  This is done through a simple handshake sequence which writes a short text string to the system clipboard, then reads it back. If the received data equal the transmitted data, the connection is verified.

  Technical Note: If the connection was previously established, then the call to acClipboardEnable will reset and re-initialize the connection.

  Note on version number report:

  If the optional version number parameter is included in the call, the two version-number sub-strings are returned in the gString object, separated by a newline character (’\n’) as shown:
    "x.y.zz\na.b.c"
  where "x.y.zz" is the WaylandCB version, and "a.b.c" is the reported wl-copy/wl-paste version. Example:
    0.0.06\n2.2.1
  If communication with the wl-clipboard utilities cannot be established, the version number will be of the form: “0.0.06\nunknown”

  
  
• void acClipboardDisable ( void );

    Input  : none
  
    Returns: nothing
  

  Terminate the connection to system clipboard.

  1) Delete the temp files used for communication.
  2) Delete the WaylandCB-class object.
  3) Return all resources to the system.

  Technical Note: If the application forgets to call acClipboardDisable on exit, the AnsiCmd destructor will release the system resources.

  
  
• bool acClipboardTest ( void );

    Input  : none
  
    Returns: 'true'  if connection verified, else 'false'
  

  Test the connection with the Wayland clipboard.

  Send a short message to the clipboard, then retrieve the data and compare the results.

  
  
• int acClipboardGetText ( gString& gsTxt );

    Input  : gsTxt : (by reference) receives contents of clipboard
  
    Returns: number of characters returned
  

  Get a copy of the text data on the clipboard.

  Technical Note: If communication with the system (Wayland) clipboard has been established (see acClipboardEnable), the data are copied from the system clipboard to the local clipboard buffer, and a copy is then returned to caller.
  If communication with the system clipboard has not been established, the data currently in the local clipboard buffer are returned.

  Within a high-level window (ACWin) or dialog (ACDlg) context, copy/cut/paste operations are handled by the skForm/skField class. See AnsiCmd Clipboard Access, below for more information.
  
  
• int acGetClipboardSetText ( const gString& gsTxt );

    Input  : gsTxt : (by reference) contains data to be written
  
    Returns: number of characters written
  

  Write the specified text data to the clipboard.

  Technical Note: The data are first written to the local clipboard buffer; then, if communication with the system (Wayland) clipboard has been previously established, the data are copied to the system clipboard.

  Within a high-level window (ACWin) or dialog (ACDlg) context, copy/cut/paste operations are handled by the skForm/skField class. See AnsiCmd Clipboard Access, below for more information.
  
  
• int acClipboardCharCnt ( void );

    Input  : none
  
    Returns: number of (wchar_t) characters (including NULLCHAR)
             Note that a value of one(1) indicates an empty string.
  

  Returns the number of UTF-32 characters currently in the local clipboard buffer.

  1. If connected to the system (Wayland) clipboard, return size of system clipboard data.
     Note: This operation will refresh the contents of the local clipboard buffer.
  2. If NOT connected to the system clipboard, value returned is the number of UTF-32 characters stored on the local clipboard.

  Important Note: It can NEVER be assumed that one character equals one byte.

  
  
• int acClipboardByteCnt ( void );

    Input  : none
  
    Returns: number of data bytes (including NULLCHAR)
             Note that a value of one(1) indicates an empty string.
  

  Returns the number of UTF-8 bytes of data on the clipboard.

  1. If connected to the system (Wayland) clipboard, return size of system clipboard data.
     Note: This operation will refresh the contents of the local clipboard buffer.
  2. If NOT connected to the system clipboard, value returned is the number of UTF-8 data bytes stored on the local clipboard.

AnsiCmd Clipboard Access

1. The “clipboard” is an area of system memory which can be used to transfer text, images and other data among the active applications and system processes, or between segments of a single application.
2. Under most modern flavors of Linux, the “Wayland Protocol” manages communications among the system server and its clients, which includes the system clipboard.
3. While terminal applications are technically able to handle any type of data on the clipboard, practically speaking, only text data should be transferred between the terminal window and the clipboard.
4. The AnsiCmd library implements a “local clipboard” which performs copy-and-paste operations within the application. The local clipboard is under the INCLUDE_API conditional compile directive.
5. The AnsiCmd library is built specifically to avoid third-party tools; and therefore direct communication between the library and the system clipboard is not provided; however, an indirect communications channel to the system clipboard is available, as follows:
   1. The AnsiCmd interface with the system clipboard is is included in this package and is under the INCLUDE_WAYLANDCB conditional-compilation directive which enables this author’s (very simple) WaylandCB class.
      Please see Build Options for information on including the WaylandCB module in the build.
      
   2. The WaylandCB class object communicates with the system clipboard through the Linux utility package, wl-clipboard. The wl-clipboard suite was written by Sergey Bugaev and is available on most Linux mirror sites:
         sudo dnf install 'wl-clipboard' or
         sudo apt-get install 'wl-clipboard'
      If the wl-clipboard utility has been installed on the system and its component interface modules (wl-copy and wl-paste) are visible on the path, then the WaylandCB object may be initialized at any time after the AnsiCmd (or ACWin) object has been instantiated.
         AnsiCmd* acptr = new AnsiCmd( ... );
   acptr->acClipboardEnable();
   3. If communication between the system (Wayland) clipboard and the AnsiCmd local clipboard has been established, then data may be exchanged between the current application and all other processes which use the system clipboard.
   4. If wl-clipboard is not installed, or if communication cannot be established, then the application will be limited to the local clipboard.

   Technical Note: The standalone WaylandCB module (see By the Same Author) may be compiled directly into the application instead. If needed, this would provide the application more direct control of the clipboard interface. In that case, to avoid resource conflicts, the AnsiCmd instance of the class should should not be enabled.
   For full details on the WaylandCB class and the associated test app, please visit the author’s website.

6. Clipboard operations Within an skForm object.
   The AnsiCmd methods (acClipboardSetText, etc.) which send data to the clipboard and retrieve data from the clipboard are for use outside any window (ACWin object) or dialog (ACDlg object).

   Within an ACWin or ACDlg object, data are exchanged with the clipboard via protected member methods: ('cbCopy' and 'cbPaste'). Text selection, Copy, Cut are Paste operations are initiated using the “special” key associated with the operation while a Textbox (ftTB) control has the input focus.
   

   Ctrl+C wcsCOPY Copy selected text to clipboard Ctrl+X wcsCUT Copy selected text, then delete source text Ctrl+V wcsPASTE Paste text at the IP position Ctrl+A wcsSELECT Select or deselect all Shift+RightArrow wcsSRIGHT Select text moving rightward Shift+LeftArrow wcsSLEFT Select text moving leftward Shift+UpArrow wcsSUP Select text moving upward Shift+DownArrow wcsSDOWN Select text moving downward

   Please see Decoding the Special Keys for a complete list of defined “special keys”.

   Invoking the “Copy” or “Cut” operation will copy the “selected” text of the Textbox field with input focus to the clipboard. Note that selected text is underlined within the field.
   The data is first copied to the local (AnsiCmd) clipboard, and then if the application has enabled communications with the system clipboard, (see acClipboardEnable), the data are copied from the local clipboard to the system clipboard, where it will be available to all processes of the system.

   (If no text within the field has been “selected”, then the Copy/Cut command will be ignored.)

   Invoking the “Paste” operation will copy the text stored on the clipboard to the IP (insertion point, i.e. the current cursor position) within the Textbox field which has the input focus.
   If the application has enabled communications with the system clipboard, data is first copied from the system clipboard to the local (AnsiCmd) clipboard. Then a copy of the data on the local clipboard is written to the target Textbox field.

   If there is “selected” text within the target field the selected text will be replaced by the clipboard data. Otherwise the clipboard data will be inserted into the existing text (if any) of the field.
   Technical Note: The Paste operation ignores the current state of the Insert/Overstrike flag when inserting text.

   (If the field with input focus is not a Textbox field, then the Paste command will be ignored.)

Development Support

• void ansiTest ( dbgArgs& args );

    Input  : args : (by reference) test to perform and test options
                    major   : specifies the test to perform
                    minor   : specifies test sub-section
                    supp    : specifies sub-test for RGB, etc.
  
    Returns: nothing
  

  This method is a gateway to the debugging code. If debugging disabled (DEBUG_ANSICMD == 0), then a warning message is displayed.

  Perform the specified test of terminal functionality. This functionality is divided into different groups. See ansiTest_Menu method for details.

  
  
• void getDataMembers ( acaExpand* ab, locale* lo, short& tr, short& tc, short& fn, bool& fr, bool& ws ) const

    Input  : lo : receives a pointer to current locale structure
             tr : (by reference) receives terminal rows
             tc : (by reference) receives terminal columns
             fn : (by reference) receives current font number
             fr : (by reference) receives the 'full-reset' flag value
             ws : (by reference) receives the 'wide-stream' flag value
  
    Returns: nothing
  

  Returns a copy of the protected data members of the class.

  Used primarily by the ACWin class to synchronize terminal configuration, but may be used by the curious app designer.

  
  

  void getConfig ( termConfig& tCfg ) ;

    Input  : tCfg : (by reference) receives configuration data
    Returns: nothing
  

  For use during development: The terminal-configuration data used by the AnsiCmd class are private members; however, during development, it is often useful to retrieve a snapshot of the current terminal configuration to verify that the terminal is configured as intended.

  
  

  void tseReport ( const skForm& skf, const WinPos& wpRpt, uint8_t secret_code ) ;

  Although this method is "technically" a public method, it is called ONLY by the test method, Test_SoftEcho() (and its callback function) to report user input and keycode processing. *

Coding Example

The following example demonstrates application startup including creation of an AnsiCmd-class object which provides terminal setup and color attribute control capabilities.

Under C++, the 'main' function does as little as possible.
It simply passes the command-line arguments and terminal environment to the application class, which returns to 'main' only when it is time to exit.

The application class is unique to each application, allocating data storage and providing the functionality and user interface needed to complete the tasks for which it was designed.

The EarthPoints application class is typical of such classes in that it leverages well-established classes and library functions to do most of the work of the application. The application class provides coordination among the various components to produce the desired results. A really good application will also add something the world has never seen before.

The EarthPoints application does not aim so high. It is simply a vehicle for development and testing of the AnsiCmd class library, which is itself interesting, but not particulary innovative. The AnsiCmd library could be characterized as a nerd’s version of binge-watching a Netflix series during a long, long Covid-19 lockdown while on vacation in Guangxi Province.