//********************************************************************************
//* AnsiCmd link library and test applications: Version History                  *
//*                                                                              *
//* Author     : Mahlon R. Smith                                                 *
//*              Copyright (c) 2020-2026 Mahlon R. Smith, The Software Samurai   *
//*              On the web :            http://www.SoftwareSam.us/              *
//*                                                                              *
//*              Source code, binary, and CSS style definitions released under   *
//*                 GNU GPL version 3.                                           *
//*              Documentation released under:                                   *
//*                 GNU FDL version 1.3                                          *
//*                                                                              *
//* Date       : 05-Apr-2026                                                     *
//*                                                                              *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  - *
//* Copyright Notice:                                                            *
//* This program is free software: you can redistribute it and/or modify it      *
//* under the terms of the GNU General Public License as published by the Free   *
//* Software Foundation, either version 3 of the License, or (at your option)    *
//* any later version.                                                           *
//*                                                                              *
//* This program is distributed in the hope that it will be useful, but          *
//* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY   *
//* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License     *
//* for more details.                                                            *
//*                                                                              *
//* You should have received a copy of the GNU General Public License along      *
//* with this program.  If not, see <http://www.gnu.org/licenses/>.              *
//*                                                                              *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -    *
//* The full copyright notice for the package is located in 'ansicmd.info' and   *
//* 'ansicmd.html'.                                                              *
//*    Texinfo-format docs: info -f ansicmd.info -n 'Copyright Notice'           *
//*    HTML-format docs   : open 'ansicmd.html' in your favorite browser         *
//*                                                                              *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  - *
//* Description:                                                                 *
//* Please see the description of package components in the 'README' file        *
//*                                                                              *
//********************************************************************************

Version History (most recent first):
- - - - - - - - - - - - - - - - - -
v: 0.00.07 20-Dec-2025
   -- Early versions of the EarthPoints application used "ansi" as the switch 
      to invoke tests. The switch has been changed to "--test"; however, 
      the original switch is still recognized.
   -- ACWin class update:
      -- Several methods related to user interface control have been modified 
         to accept an skForm pointer or skField pointer instead of a single
         index value. This means that they are available from both ACWin and 
         ACDlg windows. The existing index-oriented methods are still available 
         (for ACWin windows only).
      -- The Scrollbox (control type ftSB) has been updated from a simple 
         read-only Textbox. It can now optionally function as a scrolling 
         menu from which the user can select an item. For an example, see 
         how the AcEdit app interacts with the user in traversing the directory 
         tree and selecting a file from the list.
      -- For Scrollbox and Menu controls, a new skField public method: getIem() 
         can be used to report the 'selected' (or current-highlighted) item.
         See documentation for details.
      -- Both Scrollbox and Menu controls may now be configured for multi-color 
         text, one color per item (row). See documentation for details.
   -- Significant update to the ACDlg class.
      -- All control types are now supported within dialog window with the 
         following exceptions: 
         -- Textbox controls (ftTB) are limited to a single row, which in 
            turn limits the formatting option to floShift. 
            -- Technical Note: During development the use of multi-row 
               text fields was validated; however, at this time, dialogs text 
               fields are limited to single-row controls. This simplifies the 
               range check on field dimensions.
         -- Menus: Context menus are supported, but must be locked in the 
            visible state. Menu groups are not supported because it would 
            make dialog refresh unnecessarily complex.
      -- Control outlines and external labels for control types that support 
         them are not directly available for controls within a dialog window.
         The data members that define outlines and labels are 'protected' 
         members; that is, they may not be directly modified at the application 
         level. Instead, two specialized public methods of the skField class 
         are available to configure these options: labelConfig() and 
         outlineConfig(). See documentation for details.
      -- Implement support for callback functions within the EditDialog() method.
         There are some differences between ACWin callbacks and ACDlg callbacks.
         Additionally, there are differences between QuickDialog and Full Dialog.
         a) QuickDialog objects:
            -- Callbacks to the application layer _are not_ available.
            -- Dialog has no defined "exit key". To close the dialog, press 
               either of the defined Pushbutton controls.
         b) Full Dialog objects:
            -- Callbacks to the application layer are available, but not 
               mandatory.
            -- If no callback is specified, then the dialog is automatically 
               closed when any Pushbutton control is selected.
               (At least one Pushbutton must be defined.)
            -- When a callback is active, the automatic closure via Pushbutton 
               is disabled. The callback must signal when to exit the dialog 
               by returning the exit code: wcsCTL_4.
            -- If a callback is specified, then a limited interaction between 
               the application and the dialog controls is available.
               A specialized group of methods provide the callback with a 
               limited access to the data in the dialog's controls.
               This group of methods are named using the format: "Dialog_nnn", 
               where the "nnn" is replaced with a name which indicates the 
               available functionality. See documentation for details on use 
               of these methods. This group of methods may be expanded as needed.
   -- Hotkey validation: The ALT+n group of keycodes are the primary keycodes 
      used as hotkeys; however, many of the ASCII control codes 
      (CTRL+n keycode group) are not assigned to any particular function and 
      may be designated as hotkeys.
      The logic needed to test for both groups is complex and error prone, so 
      if a keycode in the range: wcsCTL_A - wcsCTL_Z is received, _AND_ if 
      it is not assigned to a specific functionality, (ex:wcsCTL_C==Copy), 
      then the isHotkey() method can optionally convert to the equivalent 
      keycode in the range: wcsALT_A - wcsALT_Z.
        Example: wcsCTL_U becomes wcsALT_U.
      NOTE: This option is fully implemented; however, the code is currently 
            disabled under a conditional compile directive in isHotkey().
            If future, we hope to implement a configuration option to 
            dynamically enable or disable the conversion.
      See the 'isHotkey() method for a list of ASCII control codes which are 
      not available as hotkeys.
   -- Redesign of skField class to include 'mrptr' which is a const pointer 
      to the protected 'mrp' member.
      This was done because real-world code needs access to the MRParse-class 
      data considerably more often than we had anticipated.
      As a result of this modification, the GetFieldData method was simplified.
   -- Add optional parameters to SetFieldIP().
      -- Add an optional 'centered' parameter.
         Vertically centers the target (IP) row within the field.
      -- Add an optional 'refresh' parameter.
         Avoids potential double refresh during complex configurations.
   -- Add an optional 'refresh' parameter to SetFieldData().
      Avoids potential double refresh.
   -- Add an experimental input stream pushback queue. This is useful within 
      application callback methods, allowing greater control over program 
      flow without compromising library integrity.
   -- Bug Fix: In formatFieldText(), if specified text flow option was 
      'floChar', then the text was under some circumstances, incorrectly 
      formatted as 'floToken'.
      This fix required implementation for the previously unused 'force' 
      parameter of the private fftReformat() method.
   -- Add an overload to the pre-instantiation method 'labelConfig'. This 
      overload is designed for Radiobutton controls (ftRB) only.
      By default Radiobutton labels inherit the color attributes of the parent 
      window/dialog _and_ the label is positioned to the right of the field.
      The new method allows direct specification of the label attributes and 
      allows the label to optionally be positioned to the left of the control.
   -- Add a 'brief' parameter to the dumpMrp2Log() debugging method.
      If the flag is set, then only the indexed records are reported.
      If the flag is reset, then all records are reported.
   -- Implement ShiftFieldText() method. This complements the ScrollFieldText() 
      method, but instead of moving the cursor row, it performs a vertical 
      block shift of the visible text (Textbox (ftTB) fields only).
   -- Replace the hard-coded underline used to indicate "selected" text.
      The hidden 'modifierTable' class is now used to retrieve pointers to 
      ANSI escape sequences for the text-modifier group of attributes: 
      underline, bold, italic, reversed, blink, etc. 
      See HilightFieldText() for notes on this feature.
   -- In SetFieldFlow(), redefine the 'force' parameter for call to 
      formatFieldText(). Now, if the text is already formatted to fit within 
      the field, then it will not be reformatted.
   -- Bug Fix: In EditForm(), if an exit field was specifield 
      ('exitField' parameter), the validation test was incorrect. This caused 
      the parameter to be unrecognized under some circumstances.
   -- Bug Fix: If using the Delete key to delete "selected" text the command 
      was being ignored if IP referenced the null terminator.
   -- Bug Fix: In parseFieldText(), the 'ovr' flag was not being set reliably 
      if IP was outside the left margin of the visible area.
      Applies only to Textbox fields configured for 'floShift'.
   -- The tempfile manager "TFMan.hpp": This class has proven to be surprisingly 
      useful, and may be incorporated into other projects; therefore a 
      stand-alone package is under development. This includes a simple demo app. 
      TFMan and the TFMTest demo app are still included as an integral part of 
      the AnsiCmd package, but do not require the AnsiCmd library.
      They require only the gString class, and are otherwise fully independent.
   -- Add a conditional compile directive, 'DEBUG_ANSICMD_TEST' to isolate 
      compilation of the AnsiCmd Test suite located in AnsiCmdTest.cpp.
      This update allows the CsvView, AcEdit and other secondary demo apps
      to be compiled without the test suite which is unnecessary for these
      secondary apps.
   -- Reconfigure the softWrite() method from 'private' to 'protected'.
      This makes it available to the ACWin class.
   -- Implement a new method: acWait() which waits a specified amount of 
      time or until user presses a key, whichever comes first.
   -- update documentation.
      -- Note: Recent updates to the 'idpp' HTML post-processing utility have 
         made the "idpp_response.txt" unnecessary, so that file is no longer 
         included in the package.
   -- Posted to website: 05-Apr-2026

v: 0.00.06 24-Mar-2025
   -- Update all references to the beta release of the gString library to 
      reflect that the new mainline gString is now integrated into the 
      package.
      -- This includes updating key 'short' integers to 'int32_t' to match 
         the new gString class definition.
   -- The beta-test release of the gString class is now stable, so all beta 
      gString references have been updated to reflect the mainline code.
   -- Add the acPause method to capture a single keystroke from the input 
      stream. (keycode is discarded)
   -- Integrate the TFMan class which handles creation and deletion of 
      temporary files.
   -- Integrate the WaylandCB class which provides a communications channel 
      with the system clipboard.
   -- Encapsulate all methods of AnsiCmdTest.cpp under both the 
      DEBUG_ANSICMD && INCLUDE_API directives. This allows the library to 
      build when the INCLUDE_API directive is reset.
   -- Improve capture and handling of stand-alone Escape key.
   -- Implement an overload for acSetFgBg() which takes an acAttr bitfield 
      as an argument. While the acAttr attribute group is designed for use 
      within the API/ACWin/ACDlg method group, the bitfield encoding makes 
      for considerably cleaner application code (if you like that sort of 
      thing). This overload required that the protected setAttributes() 
      method be moved outside the API conditional compilation directive.
   -- Implement acShellOut() method which temporarily returns control to 
      the terminal shell program.
   -- Begin implementation of the "dialog" object.
      This is a child window of the parent ACWin object, which temporarily 
      obscures the parent window for specific tasks.
      The dialog is in two formats:
      -- The "quick" dialog that gives information and optionally returns a 
         yes or no response.
      -- The custom dialog which can be configured as a less complex version 
         of the ACWin object.
      The experimental dialog code was moved to its own module to provide room 
      for expansion.
   -- Add support for "hidden" controls. Any control may be hidden, that is, 
      invisible and inactive. This is useful for controls which overlap.
      This required additional support methods for display and erasure of the 
      controls.
   -- Implement new control objects:
      -- Scrollbox, a view-only text field.
      -- Menubox, a menu-oriented field which can also be configured as a 
         Menubar group.
   -- Redefine the dumpField2Log method. It now reports _all_ data members, 
      including 'protected' members.
   -- Rename 'FieldOutline' method to 'SetFieldOutline' for uniformity among 
      field configuration methods. Expand functionality to optionally specify 
      both outline and label in a single call.
   -- Redefine and/or enhance definition of the skForm and skField classes 
      to support new functionality.
   -- Add an _optional_ parameter to GetFieldData method for public access to 
      the MRParse class members.
   -- Bug Fix: In QuickDialog(), if 'timeout' > ZERO, always return 'false'.
   -- Major update to documentation.
   -- limited release.

v: 0.00.05 21-Aug-2023
   -- Integrate the CsvView application into the AnsiCmd distribution package.
      This application formats a CSV (Comma-Seperated-Values) file for display 
      in the terminal window. See documentation for details.
      CsvView uses only the low-level ANSI commands of the AnsiCmd library; 
      and therefore the library should be built:
      debugging disabled (directive: DEBUG_ANSICMD (0), and
      API-level functionality disabled (directive: INCLUDE_API 0).
      Build the library only:  gmake buildlib
      This reduces the overall size of the application by approximately 110 Kbytes.
      See documentation for additional information.
   -- Add an optional parameter to ACWin initialization constructor: 
      'termDef' specifies optional terminal configuration data.
   -- Expand the definition of the skForm and skField classes to define 
      additional types of user-interface controls. (see enum FldType) 
   -- Add the ACWin-class WinInfo method which reports the essential 
      configuration data for the window.
   -- For the 'noEcho' input option, all "special" keycodes are now reported 
      as valid keycodes. See 'specialkeyDecode' and 'isSpecialKey' methods 
      for more information.
   -- Add method acGetEchoOption which returns the current input stream 
      echo option.
   -- Add overload to ACWin Write method to write a single wide character.
   -- Add AnsiCmd-class acFormatParagraph method and the ACWin-class 
      FormatParagraph method which perform automatic line breaks in a text 
      string so the text will fit into a specified width and height.
      -- Note: Both of these methods are actually just pass-throughs to 
         the underlying gString-class method which does the actual work.
   -- Improved automatic text formatting for the ACWin Write method group.
   -- Add an optional parameter 'clear' to the ACWin-class method DrawBox, 
      which will clear the interior of the box using the attributes of the 
      parent window.
   -- Update the FieldOutline method to refresh the contents of the field 
      after the outline has been drawn.
   -- Add additional tests to exercise the new and/or modified functionality 
      of the library.
   -- Update and expand "Special" keys captured and converted.
      See specialkeyDecode().
   -- Capture and decode as many of the ASCII control codes as possible.
      These codes may then be used as application-specific commands.
      -- Special codes not included in this list: Escape (1Bh), Null (00h), 
         Ctrl+H (Backspace), Ctrl+I (Tab), Newline (0Ah, incl. Ctrl+J and CtrlM).
      -- Note that six control codes are used as signals by the terminal: 
         Ctrl+C (03h) Break signal,       Ctrl+Z (1Ah) Stop signal 
         Ctrl+S (13h) Pause the output    Ctrl+Q (11h) Resume the output 
         Ctrl+4 (13h) Quit (also Ctrl+\)
         Capture and rerouting of these signals is done where practical.
      -- Redefine the ASCII control code test to exercise the new method 
         of capture and decoding of these codes.
   -- Capture the escape sequences associated with Left Alt key in 
      combination with alpha and punctuation keys.
      -- To fascilitate this development, a new test method: Test_RawInput() 
         was created.
   -- Add isCommandKey() method to identify the converted escape sequences 
      and control codes which are not included among the special keycodes.
   -- Implement 'cchtCopy' of enum CCH_Type. This captures the break signal 
      (Ctrl+C) and converts the control signal to an ordinary keycode 
      which can be interpreted as the copy-to-clipboard command.
   -- Implement capture of the "quit" signal (Ctrl+4). Instead of simply 
      killing the application and leaving a pile of smoking rubble 
      i.e. a core dump, by default, this signal now performs an orderly 
      shutdown: deletes temp files, releases dynamic memory allocation and 
      displays a message at the bottom of the terminal window.
   -- Renamed acEchoOption() to acSetEchoOption() to conform to established 
      naming style.
   -- Revise and expand specialkeyProc() method for handling the "special" 
      keycodes.
   -- Add the conditional compilation directive INCLUDE_API to isolate the 
      API methods and data including the ACWin class.
   -- Redesign the ttyWrite(const char*, bool) overload.
      If multi-byte UTF-8 characters are written to the wide stream, they 
      will not be rendered correctly (if at all). For this reason, for 
      wide-stream output of UTF-8 data only: we convert the data to wchar_t 
      (UTF-32) before sending it to stdout. This includes both "char*" and 
      "uint8_t" source data. Note that UTF-8 data are not actually 'char' 
      data; but are in fact, unsigned char data.
      -- Add an overload to the ttyWrite method for uint8_t data because 
         without an explicit cast, the compiler choosing the wrong overload.
      -- Update the test suite to exercise the new functionality.
         Output test: epts --ansi=To
      -- Expand the definition of the winInfo class to include AnsiCmd-class 
         information. Existing members are unchanged. See WinInfo method.
      -- Redefine the SetFieldData() method to include a parameter for setting 
         the word-wrap option.
      -- Add a field to the "Text Selection and Clipboard Access" test, 
         (--ansi=Tea) to exercise the functionality of the 'floShift' text 
         formatting option.
      -- Add include file: "cstdint". This was made necessary by changes to 
         the GNU compiler for C++13, which no longer automatically includes 
         cstdint within cstdlib.
   -- Integrate the AcEdit application into the AnsiCmd distribution package.
      This application uses the windowed methods of the AnsiCmd class to implement 
      a simple text editor that runs inside the terminal window.
      Although the editor functionality is incomplete for the current release, 
      it demonstrates the use of the higher-level functionality available in 
      the library. For the AcEdit application, the library should be built with 
      debugging disabled AND with API-level functionality enabled: 
      (directive: INCLUDE_API == 1). See documentation for additional information.
   -- Major documentation update including the CsvView demo application.
   -- no public release

v: 0.00.04 21-Jul-2023
   -- Completed testing of conversion between setting attributes using ANSI 
      escape sequences and using bit-mapped settings.
   -- Completed implementation of RGB foreground/background attributes.
   -- Remove the 'normText' flag from the acaExpand class. It was unused.
   -- Implemented mix-and-match foreground/background color attributes.
      Previously, if foreground was indexed, the background also had to be 
      indexed. If foreground was RGB, then background also had to be RGB.
      Foreground and background settings are now independent.
   -- Implement ACWin method DrawLine(). This was formerly a stub.
   -- Add a "soft return" key to the group of special keys.
      Alt+Enter is recognized within multi-row fields of an skForm object, 
      and inserts a newline into the text. Note that under Wayland, currently
      Alt+Enter, Alt+Shift+Enter, Alt+Ctrl+Enter and Alt+Ctrl+Shift+Enter 
      all return the same hex sequence (1B 0A).
   -- Bug Fix: Corrected off-by-one error in acDrawLine().
   -- Bug Fix: Corrected error when drawing invisible window border.
   -- Cleaned up and/or removed some temporary debugging code.
   -- Major sections of the documentation are now complete, but are subject 
      to change as the project moves forward.
   -- Posted to website: 21-Aug-2023

v: 0.00.03 28-Mar-2023
   -- Implement the first effort at the ACWin class which defines a simple 
      "window" or dialog. This is not intended as a full-featured dialog 
      as implemented in the author's NcDialog API which is based on the 
      ncurses library. Instead, it is a lean, no-nonsense window for 
      display of information and basic interaction with the user.
   -- Clean up and formalize definitions for command-line arguments used 
      to configure the terminal. This includes a stand-alone function, 
      "ansicmdSetup()" which converts the command-line text to 
      configuration parameters in a TermConfig structure which is then 
      used to configure the terminal environment for the application.
   -- Greatly expand the test code to cover all aspects of the AnsiCmd 
      and ACWin functionality.
   -- Implement a non-blocking read in order to perform look-ahead into 
      the input stream. Useful for capture of ANSI escape sequences.
   -- Speed enhancement for acWrite() group.
   -- Implement the AC_Box class. Previously it was just a stub.
      This is a greatly-simplified version of the ACWin class which 
      provides the LOOK of a window, but with only a very basic 
      functionality. See the Test_Box() method for details.
   -- ACWin class is now stable enough to integrate it as an output option 
      for the EarthPoint test app.
   -- Limited distribution.

v: 0.00.02 25-Nov-2022
   -- Expand terminal setup options (TermConfig class).
   -- Add support for setting foreground/background by specifying the 
      RGB component colors.
   -- Outline some higher-level methods for simplified access from the 
      application. (not fully implemented)
   -- Support capture of break key, Ctrl+C.
   -- Support setting cursor style.
   -- Implement a local sleep (pause) method using nanosleep().
      See the nsleep() method for details.
   -- Remove some experimental code.
   -- Isolate help text for command-line options: '--term' and '--ansi'.
   -- Squash bugs, (how did they get into the code? My code!?! 这不可能！).
   -- Clean up comments.
   -- General layout of formal documentation.
   -- Limited distribution.

v: 0.00.01 12-Oct-2022
   -- First Effort.
      - Define the basic class functionality for implementation of the 
        ANSI commands, most of which are defined as "escape sequences".
   -- Limited distribution.



