README file for the NcDialog Application Programmer's Interface (API)
Copyright 2005-2025 by The Software Samurai
on the web:  http://www.SoftwareSam.us/
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

Unpack this archive using the following command (see below for details):
                tar -xjvf ncdialogapi-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains the NcDialog API (Application Programmer's Interface).
The NcDialog API provides a high-level C++ interface to the 'ncurses' 
C-language library.

The NcDialog API is not just an enhancement to the 'ncurses' C++ bindings. 
NcDialog is a comprensive toolkit for development of console applications using 
a text-based dialog-oriented user interface.
NcDialog provides:
   a) dialog-window-based application development
   b) a wide range of user interface control objects
   c) seamless handling of overlapping windows
   d) thread-safe keyboard/mouse input and display output
   e) transparent support for ALL languages, including RTL languages
   f) painless, and error-free text formatting (gString)
   g) access to the system (Wayland) clipboard
   h) much, much more
Using the NcDialog API will allow you to focus your application development on 
real functionality, rather than spending your time on user-interface details.

'ncurses' is present on nearly all GNU/Linux systems and provides formatting 
and color support for text-based applications. However, the 'ncurses' library 
functions are quite difficult to work with, especially in windowed applications.

Come on into the 21st century! Free yourself from the C language and from the 
primitive (AND WE DO MEAN PRIMITIVE) 'ncurses' library function calls.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
The directory tree of files included in this NcDialog API release 
is organized as follows.

NcDialog/               // API Main directory
   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /Dialog1             // Base directory where NcDialog API is built
      Dialog1.cpp          // Test and demonstration application (basic tests)
      NcDialog.hpp         // NcDialog class definition
      NcWindow.hpp         // NcWindow class definition
      NCurses.hpp          // NCurses class definition
      NCursesKeyDef.hpp    // Keycode definitions
      gString.hpp          // gString class definition
      WaylandCB.hpp        // WaylandCB inteface class definition
      GlobalDef.hpp        // Global definitions and includes needed by all NcDialog applications
      NcDialog.cpp         // NcDialog class methods (constructor)
      NcdControl.cpp       // Methods share among all DialogControl classes
      NcdControlBB.cpp     // DialogBillboard class methods
      NcdControlDD.cpp     // DialogDropdown class methods
      NcdControlMW.cpp     // DialogMenuWin class methods
      NcdControlPB.cpp     // DialogPushbutton class methods
      NcdControlRB.cpp     // DialogRadiobutton class methods
      NcdControlSB.cpp     // DialogScrollbox class methods
      NcdControlSE.cpp     // DialogScrollext class methods
      NcdControlSP.cpp     // DialogSpinner class methods
      NcdControlSL.cpp     // DialogSlider class methods
      NcdControlTB.cpp     // DialogTextbox class methods
      NcdKey.cpp           // NcDialog keyboard/mouse interface methods
      NCurses.cpp          // NCurses class methods (constructor)
      NcKey.cpp            // NCurses class keyboard/mouse input methods (primitives)
      NcWindow.cpp         // NcWindow class methods (constructor)
      NcwKey.cpp           // NcWindow class keyboard/mouse input methods (thread safe layer)
      NcwScroll.cpp        // NcWindow class data scrolling methods
      gString.cpp          // gString class methods
      WaylandCB.cpp        // WaylandCB source code
      DialogAppShared.hpp  // Startup data shared by all test applications
      Makefile             // Build the NcDialog API library and Dialog1 test application

   /Dialog2          // Test and demonstration application (keyboard and display tests)
      Dialog2.cpp       // Test application main()
      ColorTest.cpp     // NcDialog color map testing (initialization and modification)
      ColorTest.hpp     // NcDialog color map test support data
      KeyTest.cpp       // NcDialog keyboard and mouse input testing
      KeyTest.hpp       // NcDialog keyboard and mouse test support data
      CapTest.cpp       // NcDialog screen capture testing
      MenuTest.cpp      // DialogMenuWin class testing
      MenuTest.hpp      // DialogMenuWin testing support data
      Makefile          // Build Dialog2 test application
      screenshot-styles.css // CSS definitions for screen capture in HTML format

   /Dialog3          // Test and demonstration application (template for testing)
      Dialog3.cpp       // Test application main()
      Makefile          // Build Dialog3 test application

   /Dialog4          // Test and demonstration application (thread safety)
      Dialog4.cpp          // Test application main()
      BillboardTest.cpp    // Tests for the DialogBillboard class
      BillboardTest.hpp    // DialogBillboard test support data
      CMouseTest.cpp       // Tests for the NCurses mouse interface
      CMouseTest.hpp       // NCurses mouse test support data
      DMouseTest.cpp       // Tests for the NcDialog mouse interface
      DMouseTest.hpp       // NcDialog mouse test support data
      Progbar.cpp          // Progress Bar widget
      Progbar.hpp          // Progress Bar class definition
      ProgbarTest.cpp      // Tests the Probar (Progress Bar) widget
      ProgbarTest.hpp      // Progress Bar test support data
      RTL_ContentTest.cpp  // Tests NcDialog functionality for RTL languages
      RTL_ContentTest.hpp  // RTL language test support data
      ShellTest.cpp        // ShellOut and PseudoShell tests
      ShellTest.hpp        // ShellOut and PseudoShell support data
      ThreadTest.cpp       // NcDialog thread safety tests
      ThreadTest.hpp       // Thread safety test support data
      ExpandTest.cpp       // Expandable test-selection dialog and controls
      ExpandTest.hpp       // Definition of test-selection dialog
      Pinwheel.hpp         // Pinwheel-class Widget
      PinwheelTest.cpp     // Tests for the Pinwheel class
      PinwheelTest.hpp     // Define test dialog for Pinwheel class
      Chart.hpp            // Chart class definition
      Chart.cpp            // Chart class implementation
      ChartTest.hpp        // Define test dialog for Chart class
      ChartTest.cpp        // Tests for Chart class
      SliderTest.hpp       // Define test dialog for dctSLIDER control
      SliderTest.cpp       // Tests for the dctSLIDER control
      Makefile             // Build Dialog4 test application

   /Dialogw          // Test and demonstration application (multi-language support)
      Dialogw.cpp       // Test application main()
      gStringTest.cpp   // Comprehensive tests for the gString class
      gStringTest.hpp   // gString test support data
      infoDocTest.cpp   // Working examples from Texinfo documentation
      infoDocTest.hpp   // Example code support data
      Makefile          // Build Dialogw test application

   /Dialogx          // Test and demonstration application (Wayland clipboard interface)
      Dialogx.hpp       // Test application class definition
      Dialogx.cpp       // Test application source code
      Makefile          // Build Dialogx test application
      Wayclip.hpp       // Pure console demonstration app class definition
      Wayclip.cpp       // Wayclip console app source code
      wMakefile         // Build Wayclip test application (gmake -f wMakefile)

   /Keymap           // Keymap generator application
      Keymap.hpp        // Application class definition
      Keymap.cpp        // Application source code
      KeymapAuto.cpp    // Application keymap file generation and formatting
      Makefile          // Build Keymap application
      NCursesKeyDef_auto.hpp  // Sample of an automatically-generated keymap file
      TransTable2.hpp   // Sample of an auto-generated lookup table sorted by keycode

   /Misc             // Miscellaneous tests and examples

   /Texinfo          // API documentation in Texinfo format
      ncdialogapi.info     // NcDialog API documentation in 'info' format
      ncdialogapi.html     // NcDialog API documentation in HTML format
      infodoc-styles.css   // CSS style definition required by the HTML documentation
      Ch00_NcDialogAPI.texi // Texinfo documentation source files (by chapter)
      Ch01_Introduction.texi
      Ch02_OperationalOverview.texi
      Ch03_YourFirstApplication.texi
      Ch04_NCursesEngine.texi
      Ch05_NcWindowMeta-layer.texi
      Ch06_NcDialogClassDefinition.texi
      Ch06w_WaylandCB.texi
      Ch07_gStringTextTool.texi
      Ch08_ApplicationExamples.texi
      Ch09_Installation.texi
      Ch10_TechnicalSupport.texi
      texi_macros.texi     // macros used within the documentation
      same_author.texi     // list of other projects by the same author
      gpl-3.0.texi         // GNU General Public License
      fdl-1.3.texi         // Free Documentation License
      Makefile             // Build the NcDialog API documentation
      applycss             // Apply CSS style to the HTML-format documentation
      applycss_response.txt
      gstring_response.txt
      gsBase.texi          // Stand-alone documentation for gString class only
      gstring.html
      gstring.info
      wcBase.texi          // Stand-alone documentation for WaylandCB, Wayclip
      waylandcb.html       // (gString docs included)
      waylandcb.info


To read the full Texinfo documentation for this package, type: 
                   info -f ./ncdialogapi.info
or even better, open the 'ncdialogapi.html' file in your favorite browser.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

-- =================================================
-- NOTES on the current release of the NcDialog API:
-- =================================================

-- Version 0.0.38: This release is built using GNU G++ 14.3.1
   -- A new keymap was generated (NCursesKeyDef.hpp).
   -- The gString class now includes the file 'cstdint' (uint8_t, uint32_t, etc.).
   -- The gString class has been updated to use dynamic memory allocation 
      for its buffers. Note however that the NcDialog API does not currently 
      take advantage of the expandable gString buffers.
   -- The WaylandCB class was updated to address changes to the 
      third-party 'wl-clipboard' utilities.
   -- Various bug fixes and minor enhancements (see VERSION_HISTORY).

-- See below for a list of known bugs and other outstanding issues.



-- ===========================================================
-- Building the NcDialog.a link library and test applications:
-- ===========================================================
               This is just a quick reference.
   See the NcDialog API online documentation for full details.
   Open a terminal window and navigate to the documentation 
   directory.
            Example:  cd NcDialog/Texinfo
   Then open the documentation file to the 'Installation' chapter.
            info -f ncdialogapi.info -n Installation
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   1) Open a terminal window.
   2) Navigate to the directory where you want to unpack the archive.
            (See tree structure of the archive above.)
   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/ncdialogapi-0.0.26.tar.bz2
   4) Unpack the archive:
      a) If your target directory already contains an 'NcDialog' directory, 
         then rename it before unpacking the new archive.
            Example:  mv NcDialog NcDialog_OLD
      b) All contents of the compressed archive will be unpacked into a tree 
         whose base directory is 'NcDialog'. 
      c) Unpack the archive.
            tar -xjvf ncdialogapi-x.x.xx.tar.bz2
   5) Navigate to the directory which contains the API source.
            cd NcDialog/Dialog1
   6) Build the NcDialog link library and link it with the 'Dialog1' test 
      application.
      a) Be sure that your compiler version is 4.8.0 or greater.
            g++ --version
      b) Be sure that the installed 'ncursesw' library version is 5.9 or greater.
            Example: ls -l /usr/lib64/libncursesw*
      c) Build the library.
            gmake
      d) The build should be clean with no errors and no warnings.
         If there are errors, then the most likely cause would be that the 
         compiler cannot find some necessary headers or cannot find the 
         'ncursesw' library. Check your LIB_PATH and other environment variables.
   7) Once you have a clean build, run the test application.
            ./Dialog1
      a) If the application opens smoothly, then you are ready to begin using 
         the NcDialog API library in your own applications.
      b) If the application does not run, then verify that all necessary libraries 
         are installed on your system. Type the command:
               ldd Dialog1
          This will tell you all the needed libraries.
   8) Build the remaining test applications.
      a) copy the newly built files to all test directories.
         gmake publish
      b) cd ../Dialog2
         gmake
      c) cd ../Dialog3
         gmake
      d) cd ../Dialog4
         gmake
      e) cd ../Dialogw
         gmake
      f) cd ../Dialogx
         gmake                (build Dialogx)
         gmake -f wMakefile   (build Wayclip)
      g) cd ../Keymap
         gmake

      All test applications should build without errors and without warnings.
      Note that Dialog4 requires the 'pthread' library, and that Dialogw 
      OPTIONALLY includes the 'glib' and 'glibmm' libraries.

   9)  NcDialog API Textbox controls optionally access the GNOME/Wayland 
       system clipboard. Access to the system clipboard is through calls to the 
       external "wl-clipboard" utilities. If these utilities are not installed, 
       the Textbox controls will have access only to the NcDialog API local 
       clipboard.
       a) To install the utilities, use one of the following commands to access 
          the code repository:
             sudo dnf install 'wl-clipboard'
             sudo apt-get install 'wl-clipboard'
       b) The following test applications call the "wl-clipboard" utilities, 
          "wl-copy" and "wl-paste" for access to the GNOME/Wayland clipboard:
               -- Dialog1 (Test #1) 
               -- Dialogw (Test #10) 
               -- Dialogx 
               -- Wayclip  
            i) Dialogx is designed specifically to exercise the NcDialog API 
               clipboard-access code, and is therefore heavily dependent upon 
               these utilities. If access to the system clipboard is not 
               available, the application will run normally, but will be unable 
               to perform tests of the system clipboard interface.
           ii) Wayclip is designed specifically to exercise the stand-alone 
               WaylandCB class for accessing the system clipboard, and is 
               therefore also heavily dependent upon these utilities.
          iii) Dialog1, Dialog4 and Dialogw each include at least one test 
               sequence which accesses the system clipboard as a demonstration of 
               copy/cut/paste operations using the system clipboard.
               If access to the system clipboard is not available, these 
               tests will proceed normally, but using only the NcDialog API 
               local clipboard.


-- ============================
-- Known bugs and other issues:
-- ============================
   -- Depending on your terminal definition and it capabilities (termcap) 
      as well as the installed version of the "ncursesw" library and the 
      transition from X-term to Wayland, certain seldom-used keycode 
      definitions may not match the constant definitions in the 
      NCursesKeyDef.hpp source file. In this case, please refer to the 
      "Keymap" test application which may be used to generate a new map of 
      keycode constants.
   -- Depending on the installed version of the "ncursesw" library and your 
      version of the GNOME/Wayland compositor (window manager), the Escape key 
      may not be available to NcDialog API applications. If the Escape key is 
      pressed several times (approximately 11 times), the first instance will 
      be reported, but the remaining keycodes will remain in the queue. 
      The source of this problem and the solution to it are under investigation.
   -- The PseudoShell method group (execute and interpret a shell command) is 
      not yet implemented, and is currently just a stub.

