//********************************************************************************
//* NcDialog API - Version History                                               *
//*                                                                              *
//* Author     : Mahlon R. Smith                                                 *
//*              Copyright (c) 2005-2024 Mahlon R. Smith, The Software Samurai   *
//*                  CSS definitions, source code, libraries and binaries        *
//*                    released under GNU GPL version 3.                         *
//*                  Documentation released under GNU FDL version 1.3            *
//* Date       : 21-Jun-2024                                                     *
//*                                                                              *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  - *
//* 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/>.              *
//*                                                                              *
//* -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  - *
//* Description:                                                                 *
//* Please see the description of package components in the 'README' file        *
//*                                                                              *
//********************************************************************************

Version History (most recent first):
- - - - - - - - - - - - - - - - - -

v: 0.0.38 22-Feb-2025
-- Update all references to gString-class buffer size.
   The gString class now has variable, auto-sizing storage buffers. For this 
   reason, the limitations of the older gString with static buffer size 
   need to be re-imagined.
   -- Initially, only the size designator definitions have been updated.
      The idea behind this incremental change is that this should cause 
      minimal headaches and no actual change in functionality.
      When this has been verified as stable, it may be possible to expand 
      some NcDialog functionality to take advantage of the larger gString 
      storage space.
   -- The WaylandCB clipboard interface is an exception. While the NcDialog 
      API controls are currently limited to buffers <= gsALLOCDFLT, the 
      clipboard interface can handle up to MAX_CB_UTF32 characters which is 
      currently defined as gsALLOCMED characters. The clipboard UTF-8 (byte) 
      interface can handle up to MAX_CB_UTF8 bytes (gsDFLTBYTES).
      These limits will be revisited for the next release.
-- For some unknown reason, certain Unicode characters have been redefined 
   from single-column to 2-column characters. Formerly, this affected only 
   the HTML documentation; however, the monospace fonts used by the console 
   have now also been infected with this stupidity. This is annoying because 
   the API counts columns for proper alignment within windows and dialogs.
   The most obvious of these characters is the "diamond" character used 
   as the default selectors within Radiobutton controls:
    wcsDIAMOND : 0x0025C6   diamond (black ◆(2-column))
   Replace with single-column char in RB_Strings[] array in NcdControlRB.cpp.
    wcsSDIAMOND : 0x002666  diamond (black ♦ (1-column))
   The DisplayRadiobuttonTypes() debugging method displays the results of 
   of this update. See Dialog1, Test05 for example output.
-- Add an overload to wcbVersion method which reports both the WaylandCB 
   class version and the wl-clipboard utilities version.
-- Bug Fix: When the default (no parameters) NcDialog destructor is invoked, 
   it tests for the presence of the static, shared WaylandCB object, and if 
   present, deletes it. This terminates the application connection to the 
   system clipboard. While this is the correct action when closing the main 
   application dialog, any secondary dialog closed with the default 
   destructor will also delete the WaylandCB object when closing, which means 
   that the application would need to reinitialize the clipboard interface 
   after closing ANY sub-dialog. This is very inconvenient.
   Unfortunately, destructors may not include parameters, and therefore 
   cannot handle special cases, so a design decision must be made:
    a) The NcDialog destructor will release the resources associated with 
       the system clipboard when each dialog closes.
    b) The NcDialog destructor will not release the clipboard resources, 
       so those resource must be released seperately.
   The straightforward answer to this dilemma is that the NcDialog destructor 
   does not handle release of the clipboard connection. Thus, the clipboard 
   connection must be terminated explicitly via wcbDisable(), OR resources 
   (usually) will be automatically returned to the system when the 
   application exits to the command line.
   -- Existing applications should be updated to explicity release clipboard 
      resources just before closing the application's main dialog.
-- NCurses Class Updates:
   -- gString class update (v:0.0.37) uses int32_t rather than int16_t type, 
      so some integer variables were promoted to silence compiler warnings.
   -- ncurses defines (or fails to define) certain directives in curses.h 
      related to accessing the internals of certain structures.
      At some point, these definitions were modified to make the structures 
      "opaque" by default. This was a good move for reentrant code and 
      multi-threaded code which allows multiple threads to simultaneously 
      modify the structures; HOWEVER, the NcDialog API relies upon direct 
      access to window position, color attributes and other structure 
      members, specifically for: "WINDOW" aka "struct _win_st".
      For this reason, these directives are now explicitly defined in 
      NCurses.hpp to allow access to the needed members.
      See #ifndef NCURSES_INTERNALS in curses.h.
         https://invisible-island.net/ncurses/man/curs_opaque.3x.html 
         Opacity config provides SOME get/set-option functions:
         See: int mvwin(WINDOW * win, int y, int x);
         https://invisible-island.net/ncurses/man/curs_window.3x.html 
      - Enabling access to window internals may be a configuration option, 
        but if so, we haven't yet been able to identify it; and therefore 
        we can't expect other developers to independently locate and properly 
        initialize them.
   -- Update the GetLocale() method to capture the locale name string rather 
      simply returning the 'name().cstr()' from the locale object.
      This was done to avoid potetial timing issues with the persistence of 
      of the pointer returned by the locale object. The captured data are parsed 
      to determine whether the string contains multiple, concatenated entries.
-- Update documentation
-- Posted to website ??-Jul-2025

v: 0.0.37 14-Jan-2024
-- Update Keymap utility to use default keycodes for keycodes which are not 
   available to the application and/or were skipped during testing. Also added 
   a prompt when beginning the tests for the numeric keypad group asking whether 
   the keyboard includes a numeric keypad. If not, default values are used for 
   all keypad key combinations.
-- Generated new keymap for NCursesKeyDef.hpp and new TransTable2 for 
   NcKey.hpp using Keymap v:0.0.05.
   The keycodes associated with the keyboard-generated escape sequences 
   change regularly according to the Linux distro flavour, Wayland version, 
   'terminfo' database, terminal emulator used, ncurses verion, keyboard 
   type, and probably global weather patterns as well. See the 'Keymap' 
   utility for details on this recurring (and annoying) phenomenon -- and 
   how to overcome it.
-- Update documentation including repairs damage to some screenshots caused 
   by changes in web browser software and font definitions.
-- Generated new keymap for NCursesKeyDef.hpp and new TransTable2 for
   NcKey.hpp using the ncurses 6.4 library and terminfo database, and 
   Keymap v:0.0.05.
-- Rewrite the dialog-capture methods to HTML format. Formerly the text and 
   attribute values would sometimes get out-of-synch if mixed single-column 
   and multi-column data were overlayed.
-- For the dialog-capture methods to HTML format, added a small enhancement.
   The default monospace font(s) used by web browsers (especially Firefox) 
   now define certain characters which were formerly single-column characters 
   as two-column characters. They must have had their reasons, but it caused 
   some screen grabs in the documentation to become misaligned. Our solution 
   is to automagically replace the '◆' character (U+25C6) with the 
   single-column '♦' (U+2666) character. This is the only standard NcDialog 
   character we have found (so far) that exhibits this problem. If others 
   are identified, they will be addressed in the next release. Again, this 
   is for HTML screen grabs only. Info-format documents still use standard 
   monospace fonts.
-- Update the WaylandCB class and the Wayclip test application to address 
   changed and improvements to the 'wl-clipboard' utilities (wl-copy and wl-paste).
-- Minor change to the gString class to address a change in the way 'gcc' 
   handles include files.
-- Documentation update.
   -- Note that this update affects the gString and WaylandCB chapters.
   -- Note also that updates to the makeinfo/texi2any engine, and adaption to 
      these changes made to the author's Infodoc HTML post-processor have made 
      the post-processing "response file" obsolete. It is included in the current 
      release for reference purposes, but is no longer referenced when building 
      the NcDialog documentation.
-- Posted to website 22-Jun-2024

v: 0.0.36 22-Oct-2021
-- Generated new keymap for NCursesKeyDef.hpp and new TransTable2 for
   NcKey.hpp using Keymap v:0.0.04.
-- Update copyright notices to reflect the new year.
-- Documentation update.
-- Posted to website 10-Jul-2023.

v: 0.0.35 12-Aug-2021
-- Implement the dctSLIDER user interface control. The Slider control 
   allows the user to select a value by adjusting the height of the slider 
   bar. Both vertical and horizontal sliders are supported. The new code is 
   located in NcdControlSL.cpp. Examples of Slider control may be found in:
   Dialog1 Test #8, Dialog2 Test #7 and Dialog4 Test #10: "Slider Controls".
-- Documentation update.
-- Posted to website 01-Sep-2021

v: 0.0.34 29-May-2021
-- Remove obsolete code which was controlled by various conditional-
   compilation constructs. These were related to bug fixes and enhancements 
   which have been verified as functional, so the obsolete code is no 
   longer needed.
-- Increase the maximum number of NcDialog control objects from 24 to 36.
   Several ambitious designers have found the 24-control-object limit to be 
   unnecessarily restrictive. No current functionality is affected by this 
   change. See the constant value, MAX_DIALOG_CONTROLS in NcDialog.hpp.
-- Implement the Chart class. The Chart class supports creation of various 
   types of bar charts (or a Cartesian coordinate grid) which may be 
   customized to present an array of data values in several different ways.
   The Chart class consists of two source modules: Chart.hpp and Chart.cpp.
   These modules may be found in the Dialog4 test application along with 
   an extensive test suite, ChartTest.cpp.
-- Documentation update.
-- Posted to website 03-Aug-2021

v: 0.0.33 08-May-2020
   -- Bug Fix: If the integrated Wayland clipboard interface was active 
      during the deletion of the NcDialog object, the Wayland temporary files 
      were not being deleted from the temp directory. This bug did not 
      affect API functionality, but the abandoned temp files would accumulate 
      until the system was rebooted. (naughty programmer!)
   -- Implement micro-space column alignment for CJK characters in the 
      CaptureDialog() method group (HTML output).(see ccapMicrospace() method.
      -- Update copyright message in CaptureDialog() HTML output.
   -- Bug Fix: In gString class: When calculating column width, the wcwidth() 
      C library function returns '-1' for control characters. This skewed the 
      actual column count for strings containing control characters. Control 
      characters are now reported as having zero (0) width.
   -- Enhance functionality of the padCols() method of the gString class to 
      support centering text within a field.
   -- Enhance the textReverse() method of the gString class to optionally 
      process substrings delimited by newline characters as separate, logical 
      lines of a paragraph. Padding may also be added to right-justify the data.
      This is helpful for columnar data and mixed LTR/RTL data.
   -- Implement SetMenuwinBorderAttr() method. This method can be used to 
      apply custom color attributes to the (expanded-state) border of 
      Menuwin controls. This was requested by the user community. (谢谢楚瑶)
   -- In Hotkey2Index() method, add support for selecting a menu item by 
      number (0-9 only). This is useful for applications which cannot 
      conveniently support user-defined hotkeys: multi-language user 
      interfaces and interface languages which are not written using the 
      Latin alphabet (ASCII 'a'-'z' 'A'-'Z').
   -- Bug Fix: For RTL text data within a collapsed dctDropdown control 
      object, the RedrawControl() method was setting the initial cursor 
      position incorrectly. This bug was evident only when explicitly setting 
      a new highlighted item for the control (SetDropdownSelect method) after 
      returning from the control's edit routine.
   -- Bug Fix: When editing a dctSPINNER control, pressing the SPACE key now 
      terminates the edit (same as ENTER key and TAB key).
   -- Implement the Pinwheel Widget. This is eye candy for the user when the 
      application is busy doing something else. The Pinwheel class is defined 
      and implemented in Pinwheel.hpp, located in the Dialog4 test-application 
      directory. The test code is implemented in Dialog4, Test #10.
   -- Documentation update.
   -- Posted to website 28-May-2021

v: 0.0.32 08-May-2020
   -- The transition from Fedora30 to Fedora32 has broken a large number of 
      keycodes in the range of 0x0102 - 0x0246. The broken key combinations 
      generate the same escape sequences as previously; however, the 
      keycodes assigned to them have been arbitrarily changed.
      The dynamic table in NCursesKeyDef.hpp and the TransTable2 lookup 
      table have been updated to reflect the new keycode assignments.
   -- Add the wcbUserAlert() method which may be used to report the current 
      status of the system clipboard interface.
   -- In the gString class, implement the 'gscanf' method as an internal 
      implementation of the C-library 'swscanf' function.
   -- Bug Fix: In the gString class: Count of formatting specifications was 
      not ignoring a literal '%' character as it should.
   -- Add ClearTerminalWindow() method to the NcDialog Class. May be called 
      when an external process may have compromised the display data.
   -- Bug Fix: Recent enhancements (2019 and 2020) to Gnometerm and Konsole 
      interfere with our algorithm for display of RTL (Right-To-Left) text.
      To compensate, we explicitly disable BiDi (bidirectional text) support 
      during the NCurses Engine start-up sequence, and then re-enable BiDi 
      during the shut-down sequence. 
      -- BiDi support is also re-enabled by a call to Hibernate() in 
         anticipation of temporarily returning to the shell program. BiDi 
         support is then disabled again by a call to Wake().
      -- Note that some terminal emulation software will not respond to direct 
         programatic enabling/disabling of BiDi support. Please see the 
         NCurses-class BiDiEnable() method for more information.
   -- In the gString class: Implement textReverse() method. 
      This method is useful for manipulating RTL (Right-To-Left) text or mixed 
      RTL/LTR text, when the display routine either ignores the RTL language 
      or tries to be "helpful" by automagically (and incorrectly) reformatting 
      the data.
   -- In mid-2019, the replacement of the X mouse driver with the Wayland 
      mouse driver had caused the system to stop reporting the Shift key in 
      conjunction with mouse events. While the Shift key is still not 
      reported in conjunction with mouse clicks, Shift+Scrollwheel events are 
      now being reported correctly (Wayland version 1.18). This means that 
      text selection in Textbox controls and stepped increment/decrement of 
      values in Spinner controls are once again fully functional.
      (However: keep an eye on this.)
   -- In the NcWindow class, add overload methods to the 'WriteParagraph' 
      method. These are inherited by the NcDialog class. Previously, the 
      WriteParagraph() method took only a 'const gString&" text parameter.
      This limited the length of the text data to gsMAXCHARS.
      Overloads have been added to allow for 'const wchar_t*' and 
      'const char*' text parameters, allowing for arbitrary-length text output.
   -- Bug Fix: A call to 'SetDropdownSelect' was not forcing a redraw of the 
      control, so when control was subsequently expanded, the highlight was 
      sometimes on the incorrect item.
   -- Update copyright message to reflect the new year.
   -- Minor updates to all Makefiles.
   -- Documentation update.
   -- Posted to website 25-Jan-2021

v: 0.0.31 23-Apr-2020
   -- Integrate the Wayland clipboard interface for textbox copy/cut/paste.
      -- Create NcDialog stubs for all WaylandCB public methods.
      -- Add static non-member pointer 'wcbClip' to access WaylandCB object.
         Located at the top of NcdControlTB.cpp.
      -- Enable Textbox default copy/cut/paste/select keys as part of the 
         NcDialog instantiation.
      -- Add exercise of Wayland clipboard in Dialog1 (Test #1) and 
         Dialogw (Test #10).
   -- Bug Fix: For Textbox controls configured for RTL text, the 
      cut-selection-to-clipboard operation was indexed incorrectly under some 
      conditions, causing an endless loop.
   -- Expand definition of Delete key within a Textbox control to delete 
      'selected' text.
   -- Minor changes to the WaylandCB class:
      -- Redefine the return value for the wcbTest() method.
         Formerly, it returned 'true' indicating a successful connection, 
         or 'false' if unable to communicate with the system clipboard.
         The return value is now a member of enum wcbStatus which provides a 
         more detailed status.
      -- Redefine the return value for the wcbClear() method.
         Formerly, it returned (0) on success or (-1) if error.
         The return value is now 'true' for success or 'false' if error.
      -- Cosmetic changes: Update some source code comments.
   -- Documentation update.
   -- Posted to website 28-Apr-2020

v: 0.0.30 13-Sep-2019
   -- Update from gcc 4.8.3  to  gcc 9.0.1.
      New warning: -Wmisleading-indentation
      This is a bogus warning because C/C++ are free-form languages.
      The compiler's complaint is that under some circumstances, there are 
      no braces after a conditional statement to enclose ("guard") a 
      single instruction to be executed. In any case, all has been 
      beautified to silence the compiler warning.
   -- Design a new test application, 'Keymap' which performs key-map 
      testing on three keycode groups: Navigation keys, Function Keys and 
      Numeric Keypad keys, along with a few special keys such as Insert, 
      Delete and Shift+Tab. From the test results, this utility generates 
      a C++ header file which may be "include'd" into NCursesKeyDef.hpp.
      It can also generate a copy of the NCurses-class translation table, 
      TransTable2. See the documentation for the Keymap utility for more 
      information.
   -- Bug Fix: In NCurses::WriteString() method, if ASCII control codes were 
      in the source data, the method would not step over the control code as 
      it should, causing the application to hang. (Yes, we are roundly 
      ashamed of ourselves.)
   -- Mouse scroll-wheel event definitions have changed, either in the 
      ncurses code, OR in the Wayland mouse driver interface to ncurses.
      Either way, access to our Shift+Scroll shortcut for selecting text 
      in a Textbox is no longer directly available. The work-around would 
      be to _assume_ that mouse scrol events in a Texbox control are an 
      attempt to select data; however, we resist making that assumption, 
      so text selection via mouse is not implemented at this time.
   -- A bug in the ncursesw library (or inadequate support under Wayland) 
      causes artifacts between the left edge of the terminal window and 
      our defined window WHEN DRAWING THE WINDOW BACKGROUND (ClearWin()).
      This only happens when the specified color register pair of the 
      color attribute >= 0x08.
      Our work-around is that IF the register pair >= 0x08, THEN we 
      refresh the window after each character written. This clears 
      whatever ncursesw internal tracking error that is causing the 
      artifacts outside the boundaries of the defined window. There is a 
      slight performance hit, but it is barely noticeable to the eye, even 
      on our 800Mz doorstop.
      -- Note also that artifacts occur ONLY the first time the window 
         is drawn. Subsequent calls seem to work without error.
   -- Enhance operation of the DialogBillboard class. The 'sclAttr' member 
      was formerly ignored, but it now indicates whether the color 
      attributes will be scrolled when the text data are scrolled. By 
      default color attributes are associated with the display line; but 
      when this flag is SET, color attributes are associated with the 
      display text rather than with the line number.
      See the "ScrollBillboardColors(bool) method for details.
   -- Full rewrite of Dialogx application to access the Wayland clipboard 
      rather than the X clipboard. This functionality is external to the 
      NcDialogAPI itself and is a fully-independent implementation.
      See WaylandCB.hpp and WaylandCB.cpp.
   -- Due to a bug in the ncurses 'keypad', the Escape character is no 
      longer passed through. The loss of access to the Escape key is a 
      serious problem for NcDialog functionality. The edit methods are 
      designed to interpret the Escape key as a command to discard current 
      edits, restore the previous state of the control and move focus away 
      from that control.
      As a temporary patch, when the ALT+X character is received by any of 
      the edit-control methods, we substitute the Escape key (nckESC).
      We hope that Mr. Dickey will issue a patch for this issue soon.
   -- Recent changes in the way text is rendered in browsers has affected 
      the way dialog screenshots are displayed. Specifically, the 
      horizontal dimension of the background ("max-width") calculation.
      We have experimentally determined the multiplication constant 
      needed for this calculation. See notes in ccapFile() method.
   -- Documentation update.
   -- Posted to website 17-Jan-2020

v: 0.0.29 19-Jan-2016
   -- Bug fix in NcDialog constructor, defend against unitialized InitCtrl 
      object or invalid control type being passed by application. Now the 
      dialog will stay open to visually demonstrate the error. Previously, 
      the dialog opened and closed faster than the eye could see.
   -- Bug fix in 'ShellOut' method:
      -- the 'soX' option was being overridden by the default option.
      -- the 'soP' option was incorrectly displaying an initial message in 
         addition to the specified post-operation message.
   -- 'ShellOut' method now returns the exit code from the child process.
      Caller must determine the value and reliability of this code and 
      how to interpret it.
   -- Bug Fix in 'ClearWin' method: If window is too small to have a border 
      (rows==1 || cols==1), start and end position for clear were being set 
      incorrectly.
   -- Finish implementation of support for fixed-width Textbox controls.
      Previously editing of a fixed-width field was not fully supported.
      -- Rename the 'ExtendedTextboxData' method as 'FixedWidthTextbox'.
         This is an obtrusive change: existing code must be updated to use 
         the new method name.
      -- When horizontal shift was disabled, existing text data was not being 
         properly truncated to width of field.
      -- When scrolling, do not allow cursor movement to cause a data shift.
      -- When inserting or replacing text, prevent overflow of the field.
      -- Update documentation to explicity state that only single-line Textbox 
         controls may be set as fixed-width controls.
   -- Add an undocumented option to emwEditSingle() to allow screenshot 
      capture of a Menuwin object under edit (invoke with ESC key).
   -- The 'EditScrollext' method now sets the returned 'dataMod' flag if 
      user input is nckENTER, nckpENTER or nckSPACE, _or_ if the position 
      of the highlight has changed. Formerly, nckSPACE did not cause the 
      'dataMod' flag to be set.
   -- Create a callback method for the 'GenericDialog' method specifically 
      for capturing screenshots of 'DecisionDialog' and 'InfoDialog' windows.
      Activation key == nckAINSRT (ALT+INSERT).
      Conditionally compiled under both 'ENABLE_DEVELOPMENT_METHODS' 
      and 'GD_CAPTURE'. This makes creating documentation for NcDialog-based 
      applications much easier.
   -- Expand the definition of the tbFileName and tbPathName Textbox filters 
      to include all printing characters except a few 'special' characters.
      While technically, all characters except '/' and '\0' are valid 
      filename characters under Linux, many of the specified special 
      characters are not portable, or are othewise foolish filename choices.
   -- Update interval timing for the 'UserAlert' method and make user 
      mid-sequence termination more robust.
   -- Bug Fix: In MoveScrollextHighlight(), calling this method always made 
      the highlight visible, even if it should have remained invisible.
   -- Bug Fix: In SetPushbuttonText(), default hotkey was being lost, causing 
      the control to stop responding to mouse input.
   -- Overload the SetActiveMenuItems() method to allow replacement of the 
      menu-item text strings.
   -- Repair documentation error in header of dtbmData constructor, 'center' 
      parameter. Documentation change only--no change in functionality.
   -- Increase maximum control label size from 128 to 256 wide characters.
   -- Finish implementation of remaining genDialog-class members (yesTxt and 
      noTxt) which implement the optional, alternate Pushbutton text in 
      DecisionDialog() and InfoDialog(). This includes support for RTL 
      Pushbutton label text.
   -- Modify the conditions for DrawContentsAsRTL() method to allow toggling 
      the RTL flag for Textbox controls. This allow setting RTL format even 
      if the Textbox has focus _IF_ the containing window has not yet been 
      opened.
   -- Bug fix in low-level WriteHotString() method related to cursor 
      positioning for multi-column RTL output. See note in NcWindow.cpp.
   -- Add full initialization constructor to the reservedKeys class. We 
      should have done this from the beginning. (see example in Dialogx.cpp) 
   -- Implement enhancements and additional features for the gString class.
      See gString.cpp module header for details.
   -- Add two additional options to spinner controls to allow the value to 
      be displayed in hexadecimal format. See enum dspinFormat.
   -- Update for g++ v:5.4.0 AND ncurses library v:6.0.yyyymmdd:
      -- Note that GNOME-term "ambiguous-width" characters must be rendered 
         as "narrow." This is an option in the gnome-terminal settings.
         Formerly, this always defaulted to "narrow" without an 
         easily-accessible setting to modify it. The characters in question 
         are the line-drawing characters which are a major element in drawing 
         dialog windows in gnome-terminal. Konsole may have a similar issue, 
         but this has not yet been verified.
      -- NCurses::GetKeyInput() method workaround for libncurses bug.
      -- Due to some subtle change in which the compiler puts string pointers 
         on the stack the NCurses VerifyLocale() method had stopped working.
         Now fully functional.
      -- Update certain NCurses-class keycode definitions to correspond with 
         the ncursesw v:6.0.20160213. See NcKey.cpp for details.
   -- Add new method: GetBillboardIndex( short cIndex, short& lIndex );
      For Billboard controls, returns index of the next free display line.
   -- Define additional const character codes: wcsWCIRCLE, wcsBCIRCLE, 
        wcsFISHEYE, wcsBULLSEYE, wcsWDIAMOND, wcsDIAMONDS. (see NCurses.hpp) 
        -- This was done primarily to implement a special case of the 
           single-character radiobutton type, rbtC1. See RedrawControl() 
           method of the DialogRadiobutton class.
   -- Add an undocumented debugging feature for screen capture of Dropdown 
      controls. See EditDropdown().
   -- Allow Linux "special" characters to optionally be recognized as valid 
      filename characters. See tbIsFileName().
      -- Add method to escape the Linux special characters so they will be 
         seen as ordinary filename characters when passed to console shell 
         program. See EscapeLinuxSpecialChars(). For a more comprehensive 
         special-character-escape method, see the FileMangler application, 
         FMgr::EscapeSpecialChars() method.
   -- gString class:
      -- Implement the 'findlast' method group.
      -- Implement the 'strip' method.
      -- Implement the 'padCols' method.
      -- Implement the 'loadChars' method.
      -- Implement the 'findx' method.
      -- Implement the 'scan' method.
      -- Overload the 'after' method to take a 'src' argument of a single, 
          wchar_t character. This is consistent with the 'find' and 'findlast' 
          methods.
      -- Declare some unchanging parameters as 'const'. No functionality 
         change, but more safety.
      -- Bug Fix: in 'composeFieldwidthBugFix' method. (how embarrassing!)
         For composing strings with field-width specifier, if string to be 
         padded contained multi-column characters, the NULL terminator was 
         _sometimes_ being positioned incorrectly.
      -- Bug Fix: in 'compare' method. Narrowing of int to short in return 
         value from wcsncmp/wcsncasecmp functions was causing a bad compare 
         between ASCII and CJK characters which could produce very large 
         numerical differences between characters.
      -- Bug Fix: In the find() method, if caller specified an over-range 
         offset, offset was set to ZERO. This could have caused a caller's 
         sequential find to loop forever. Now if offset parameter is overrange, 
         it is set to index the null terminator.
      -- Bug Fix: In the after() method, if caller's substring was not found, 
         then returned index was not -1 as it should have been.
   -- Documentation update.
   -- Posted to website 11-Sep-2019

v: 0.0.28 20-Aug-2015
   -- gString class:
      -- Implement the 'erase' method group and the 'replace' method group. 
         Update Dialogw, Test06 for testing 'erase' and 'replace'.
      -- Update 'compare' method group to support both case-sensitive and
         case-insensitive comparisons.
         IMPORTANT NOTE: CHANGES TO EXISTING APPLICATION CODE ARE REQUIRED.
           Any code which currently uses the _optional_ parameters of the 
           'compare' methods will need to be updated to reflect the changes 
           to the 'compare' prototypes.
      -- Redesign the 'formatInteger' methods.
         -- Create a group of constructors for formatting fixed-width integer 
            fields.
         -- Create a group of 'formatInt' methods for formatting fixed-width
            integer fields. New features include increased maximum field width,
            support for signed integers, choice of metric (base-10) compression 
            or binary (base-2) compression, choice of units designators.
         IMPORTANT NOTE: CHANGES TO EXISTING APPLICATION CODE ARE REQUIRED.
           Any code which currently calls 'formatInteger' will need to be 
           updated. Only the method name needs to be changed from 'formatInteger' 
           to 'formatInt' the _required_ parameters are unchanged.
      Update Dialogw, Test06 for testing 'formatInt' group and new constructors.
   -- Bug fix in IsHotkey(): if test value is a NULL character, then do not 
      scan the hotkey list. We had assumed that the keyboard would never 
      return a NULLCHAR as a valid keycode; however CTRL+2 actually does so. 
      Note that this is actually an ncurses bug because it is responsible 
      for returning only valid keycodes, but we squash it here.
   -- Bug fix in ConnectControl2Border(): return value was not being updated 
      on success.
   -- Bug fix in DialogScrollbox() constructor: protect ourselves from a 
      NULL pointer in InitCtrl::scrColor member by setting a default color.
   -- Bug fix in IsHotkey(): Converted mouse event was not being recognized 
      as a potential hotkey.
   -- Bug fix in NcWindow.hpp: Was wrong default 'dclick' value for call to 
      EnableStableMouse().
   -- Bug fix in meIsObscured(): Testing whether the target of a mouse click 
      is obscured by an open menu. Test formerly did not distinguish between 
      regular menus and context menus which caused an occasional false positive.
   -- Refine the algorithm for converting mouse input to keycodes.
      Affects only scrolling controls dctSCROLLBOX, dctSCROLLEXT, dctDROPDOWN, 
      dctMENUWIN. Both single- and double-click now move the highlight to the 
      item under the mouse pointer _and_ 'selects' that item. 
      See meTransformEvent() method for details.
   -- Make the main keyboard Enter key (nckENTER) and the numeric keypad Enter 
      key (nckpENTER) equivalent in all user-interface code (EditXXX methods).
   -- In NcDialog constructor, if the NCurses Engine shows that the mouse 
      interface is enabled, then inherit the parent dialog's mouse settings. 
      This allows sub-dialogs access to the mouse without having to 
      explicitly enable the mouse after instanting them.
   -- Update definition of the dspinData class for formatting Spinner data. 
      This was done primarily to support implementation of date/time Spinners 
      which have been requested by the community.
      -- Added an initialization constructor and two optional new fields.
         IMPORTANT NOTE: CHANGES TO EXISTING APPLICATION CODE ARE REQUIRED.
         Existing code which uses structure-style initialization for this 
         class, must be checked for correct order of arguments.
         (This is an obtrusive change.)
   -- Documentation update

v: 0.0.27 25-Apr-2015
   -- Standardize the naming convention for the support methods of the 
      DialogScrollbox, DialogScrollext, and DialogDropdown classes to 
      address confusion reported by beta-testers.
      -- Split GetSbSelect and SetSbSelect methods into:
         GetScrollboxSelect(), GetScrollextSelect(), GetDropdownSelect()
         SetScrollboxSelect(), SetScrollextSelect(), SetDropdownSelect()
            [This may break some existing code, but only in]
            [the method name, not the functionality.       ]
            [Grep your application source for '.etSbSelect']
            [and make the appropriate name substitutions.  ]
   -- Application layer mouse interface is now fully functional. 
      Specificially, the meEnableStableMouse method overrides the pathetic 
      timing of the xterm driver and the ncurses(w) library to achieve a 
      relatively stable mouse interface.
   -- Redesign Textbox text-selection, copy, cut and paste operations.
      -- Copy to and from the Local Clipboard simplified and made more robust.
      -- Text selection within a Textbox redesigned and simplified.
   -- The genDialog class now fully supports both LTR and RTL languages 
      for automatically-generated dialogs. See InfoDialog and DecisionDialog 
      methods.
   -- Enforce horizontal and vertical positioning of controls to bring them 
      completely inside the boundaries of the parent dialog. (DialogMenuwin 
      controls may still descend below the dialog boundary.)
   -- The CaptureDialog group of methods is now fully functional, although 
      alignment of multi-column characters in the HTML output is not yet 
      satisfactory.
      -- A new, 8-bit-color HTML capture is implemented for capturing 
         small-footprint screenshots for Texinfo documentation.
   -- Finished implementation of the ShellOut method which temporarily puts 
      the NCurses Engine to sleep and dumps the user back to the command line.
   -- Implemented the Progress Bar widget (Progbar class). This widget is 
      defined outside the NcDialog API library. See the test application
      Dialog4, Test09 and the source modules Progbar.cpp and Progbar.hpp
   -- Completed the basic draft of the Texinfo documentation (info and HTML 
      formats) except for the chapter on the X clipboard.

v: 0.0.26 21-Mar-2015
   -- Since the last public release of the NcDialog API in 2011, we have made 
      significant changes to all areas of the software and documentation.
   -- The API input/output streams are now thread safe. Output to the display 
      is significantly more robust. Key input processing took a performance hit 
      for thread safety, but possible performance enhancements are currently 
      under investigation. Refer to the Dialog4 test application, Test #7.
   -- Previous releases supported only the first eight(8) RGB registers.
      We now fully support all sixteen(16) RGB registers for 16-color terminals.
      Refer to the Dialog2 test application, Test #7.
   -- Most significantly, all previous releases relied on the the 
      self-documenting nature of the source code itself to assist the 
      application programmer. The current release is the first to include 
      detailed Texinfo documentation, in both 'info' and HTML formats.
   -- The gString class, which is a subset of the NcDialog API has had several 
      public releases as an independent package since the last full API release.


