NcDialog Library API

Description of a Dialog

• The Concept of a Dialog
• An NcDialog API Dialog

Application Layer Methods

1. Startup Code: All NcDialog-based applications have a standard sequence of startup-up activities. This sequence is demonstrated in the ’main’ method of each of the test applications (see Test Applications).
   For more information on the startup sequence, please see NCurses Engine, or see Your First Application, for a step-by-step explanation of the startup sequence.
2. Define the NcDialog object: An instance of an NcDialog window object has the following characteristics:
   
   Parameter Description ......... .................................................... Size The number of rows and columns for the window Position The offset of the dialog from terminal window origin Color Color attributes for window border and interior Style Border style Title Optional window title to be displayed in border

   Please refer to the discussion of the InitNcDialog class,
   see Your First Application, for more information.

3. Define and configure the controls the NcDialog window will contain.
   For each control contained in an NcDialog window, there is a control definition which specifies size, position, color, contents and other parameters.

   In addition, many optional configuration methods are provided which can be called after instantiation to further refine each control object for your particular needs. Please see Dialog Control Objects for details on the definition and optional configuration parameters for each control type.

4. Instantiate and open the dialog window. Once the NcDialog window object and its controls have been defined, open the dialog using the following steps.
   1. Instantiate the dialog and its controls.
   2. Call any optional configuration methods which must be completed before the window is opened for the first time.
   3. Open the dialog window.
   4. Call any additional configuration methods for the controls.
   5. Write any desired static text to the window.
   6. Make the window visible to the user.
   7. Enter the user-interface loop.

   For an example sequence, please refer to the discussion in see Your First Application.
   Please refer to see Dialog Control Objects for details on optional configuration parameters for each control type.

5. User Interface loop: The basic application layer consists of a simple user-interface loop. This loop organizes user input and decides what to do with that input. It tracks which control object currently has the input focus and calls the appropriate ’Edit’ method for that control type.

   There is exactly one (1) publically-accessible Edit method for each control type:

   Edit Method Control Class Control Type ........... ............. .............. EditPushbutton DialogPushbutton dctPUSHBUTTON EditTextbox DialogTextbox dctTEXTBOX EditBillboard DialogBillboard dctBILLBOARD EditRadiobutton DialogRadiobutton dctRADIOBUTTON EditScrollbox DialogScrollbox dctSCROLLBOX EditDropdown DialogDropdown dctDROPDOWN EditMenuwin DialogMenuwin dctMENUWIN EditScrollext DialogScrollext dctSCROLLEXT EditSpinner DialogSpinner dctSPINNER EditSlider DialogSlider dctSLIDER
6. Keyboard and Mouse Input: All, or nearly all user input is handled within the Edit methods listed above. However, there are certain instances where it is useful to obtain information directly from the user. The most common of these would be the nckPause() macro which simply waits for the user to press a key.

   All keyboard and mouse input is channeled through the method
   GetKeyInput( wkeyCode& wk )
   Please note that for reasons of thread safety, this method is designed in layers. The NcDialog::GetKeyInput() method should be used in nearly all cases because it incorporates not only thread safety, but also translates mouse input into keycodes and dialog coordinates associated with the mouse pointer wherever possible.
   Please see Mouse Configuration for a detailed description of the mouse interface.
   Please see Thread Safety for a more detailed discussion of thread safety.

   The 'NcWindow::GetKeyInput()' method is a thread-safe pass-through to the underlying 'NCurses::GetKeyInput()' method, which IS NOT thread safe, and neither of these layers should be called directly from within an NcDialog application.

7. Output to the Display: There are three (3) primary methods for writing data to the NcDialog window:
   
   Output Method Description ............. ..................................... NcDialog::WriteChar() Writes a single character NcDialog::WriteString() Writes a text string to current line NcDialog::WriteParagraph() Writes a paragraph (with line breaks)

   These methods are actually member methods of the parent class, the NcWindow class, and are fully thread-safe, that is: they will not interfere with each other if multiple threads are simultaneously writing to the dialog.

   For a detailed description of how these methods are used, please refer to the section, see NcDialog Display Output.
   For a more detailed discussion of thread safety, please refer to the section, see Thread Safety.

   Note that the NCurses class also has 'WriteChar()' and 'WriteString()' methods for writing directly to the terminal window; however, these methods ARE NOT thread safe, and should not be used when an NcDialog window is open (except possibly for writing debugging messages to the terminal during application development).

8. Shutdown Code: An orderly shutdown of the NcDialog API is necessary in order to prevent memory leaks, pointers to unallocated data space and other application bête noire. Fortunately, the shutdown sequence is very simple:
   
   1. delete the NcDialog-class object,
      
   2. then stop the NCurses Engine.

   Please refer to the section, see NCurses Engine,
   or the section,see Your First Application, for more information.

Library Internals

This document is intended as a reference for the application designer. As such, the private, support methods which implement the low-level NcDialog API functionality are not discussed in detail here.

However, your author has spent most of his career documenting code, his own code and everyone else’s code; therefore, the NcDialog API library source code is as close to being self-documenting as we can make it. In addition, copious programming notes are included in every source module and in the header of every non-trivial method, so the next poor bastard who updates the code will have an easier time of it.

If, however, you are having trouble with any section of the source code, just remember that your author has a massive ego (as all software designers do), and is happy to discuss his work with anyone who has a serious question.
See Technical Support.

Inheritance Layers

A Short History Lesson

The C language is powerful, concise, infinitely adaptable, and in the right hands, imbued with the seeds of artistry.

However, C is a terrible language for generational software such as the Linux kernel and the ncurses function library because one designer’s artistry is the next generation’s frustration and misery.

In a past life, this author partnered with a true software genius to start a little company in the Silicon Valley. His code was pristine—it did exactly what he intended it to do, smooth and fast—a true work of art. The problem was his total recall: he never wrote a word of comment because he remembered in great detail every line of code he ever wrote. So when he went off the rails, as genius always does, it became our job as his number two to come along behind, documenting what he had done and porting the code for next-generation projects. Frustration and misery, indeed!

Layering to the Rescue

Just as parents work all their lives to create a stable environment from which their children can launch themselves into the future; exactly so, the strength of C++ is the ability to inherit robust, reliable, self-documenting code from parent classes, building layer-by-layer upon the successes of the past.

The NCurses / NcWindow / NcDialog class progression starts simple and becomes progressively more sophisticated. We make no wild claim, however, that all bugs have been banished. Indeed, sophistication breeds fragility, and each layer requires an order of magnitude greater planning, care and field testing.

1. The NCurses Layer
   The function of the NCurses class is to define and configure input and output streams, and to interact directly with the underlying ncursesw C-language library.

   The application’s only direct access points to the NCurses class are:
   

   1. the start-up sequence
   2. the defined constants for keycodes and color attributes
   3. the shut-down sequence

   The application needs NO direct contact with the underlying C library, and in fact, doing so would very likely trash the application’s working environment. DON’T DO IT!

   Please study the ’Dialogw’ test application, tests 1 and 2 for a demonstration of the NCurses class methods.
   See Dialogw App.

   For a detailed explanation of all public methods and data of the NCurses class, please see NCurses Engine.

2. The NcWindow Layer
   The true value of the ncurses(w) C library is its definition of a text-mode "window." This ’window’ is a block of memory which contains the text and color attribute data, along with positioning and configuration information representing a section of the terminal’s display area. It’s primitive C-style naming conventions, and ad-hoc design are rather difficult to work with, but it is also quite a powerful construct.

   However, in order to harness this power for non-trivial projects, it is necessary to encapsulate the ncurses(w) window primitives, simplifying its application interface and compensating for its weaknesses.

   The NcWindow class leverages the low-level power of the NCurses class for input and output while creating a cushion between the application programmer and the difficult process of creating and maintaining window objects. In short, the NcWindow class converts the ncurses(w) ’window’ construct from a sequence of C function calls into a true window ’object’.

   Simultaneously, the NcWindow class creates a thread-safe application environment upon which its derived classes can rely.

   Like the NCurses class, the NcWindow class makes no attempt to encapsulate the entire ncurses(w) windowing interface. Instead, it uses the absolute minimum number of ncurses(w) primitive functions necessary to get the job done. This is not a matter of laziness (or of arrogance), but is an exercise in defensive programming: we want our API to be robust and reliable, and much of the ncurses(w) C library is neither.

   Please study the ’Dialog1’ test application, tests 3 and 4, and the ’Dialogw’ test application, test 3 for a demonstration of the NcWindow class methods:
   See Dialog1 App.
   See Dialogw App.

   For a detailed explanation of all public methods of the NcWindow class, please see NcWindow Meta-layer.

3. The NcDialog Layer
   

   While it is possible to write a decently-robust application using the NcWindow class directly, the NcWindow class lacks any kind of sophisticated user interface or visual polish.

   The NcDialog class is a ’derived class’ whose parent is the NcWindow class. Essentially everything inside the NcDialog class is a window object or a group of window objects. The NcDialog layer makes no direct calls to the ncurses(w) C library, and is thus free from the problems that arise when changes are made to underlying third-party libraries. See Description of a Dialog, for more information on dialog objects.

   The NcDialog class is the application programmer’s working environment.

   • The application knows nothing at all about the ncurses(w) C library.
   • The application knows nothing about the NcWindow class.
   • Apart from the start-up and shut-down sequences, and the constant definitions (keycodes and color attributes), the application knows nothing about the NCurses class.

   Of course a good programmer can find ways to violate this layering of functionality, but a great programmer will not do it.

4. The Dialog Control-Object Layer
   Within a dialog object, interaction with the user is the primary focus. To interface smoothly with the user, several dialog control objects are defined. Each control object has a specific interface function so the application programmer does not have to create all new interface functionality.

   Each control object is itself a dialog object which is in turn, created from one or more NcWindow objects. For instance, the DialogMenuwin class is actually a linked set of three(3) NcWindow objects: a title, a border and a scrolling display area which constitute a collapsible menu object. See Application Layer Methods, for an overview of the user interface controls.

   For a detailed explanation of all public methods, data and control objects of the NcDialog class, please see NcDialog Class Definition.

Thread Safety

• Introduction
• Implementation
• Thread-safe Operation

Newbie Corner

Introduction

Software Sam may be a caffine-swilling, hard-core, old-school assembly-language programmer, but he is also a classroom teacher, so he understands that for a programmer who is just starting out on his or her career, even a very small misunderstanding over terminology or some minor technical issue which needs to be researched can stall a project for hours—or even weeks. For this reason, we offer some simple, introductory information for a few of the problems which beginning programmers and those new to GNU/Linux are likely to encounter.

• Vocabulary
• What Is a Class?
• Reading Texinfo documentation
• Configuring Linux
• Selected command-line utilities
• Friendly Advice for New Programmers

Development Tools

Developing terminal (text-based) applications is not like working in a GUI environment. It is not necessary to learn how to use a "development environment" in order to get useful work done. In fact, working in an "environment" feels to us like having to drag around a bag of rocks wherever we go. For a lovely visual of what it feels like to work within a development environment, we recommend the opening scenes of the film, "Johnny English—Reborn."

To create a complete and sophisticated NcDialog application, all you will need is a simple text editor, a terminal program and the compiler.

Text Editor

If you are an experienced programmer, you probably already have a favorite text editor, one with which you feel comfortable. If you are new to bit-herding, we do recommend that you select a text editor that has direct support for C++ formatting, i.e. a "programmer’s text editor," but the most important qualities for any tool are that it doesn’t get in the way of your productivity and that it feels right for you.

Terminal Program

We assume that you are at least generally familiar with how to use a terminal program, and that you understand the basic command-line utilities; but even if you are not familiar with 'ls', 'grep', 'chmod' and a few of the other basic commands, don’t worry. You WILL succeed.

The default terminal program for most GNU/Linux installations is either the GNOME Terminal or the KDE Konsole. Both of these are excellent choices for command-line work. Konsole is a bit more configurable (as are all things KDE), but for our purposes there is little difference between them. If you already have a favorite terminal program, you are definitely nerd enough to succeed at any task.

GCC (g++) Compiler

The use of an up-to-date compiler and its associated header files and libraries are critical to any software project. In our not-too-humble opinion the GNU GCC compiler collection is the finest piece of software ever written for public use.

The NcDialog API relies on full compiler support for the GNU++11 (C++11) standard. According to the GCC compiler’s own documentation, full support for C++11 was achieved in GCC version 4.8.1. However, several earlier versions actually had full (if poorly documented) support for C++11 functionality.

(If you are a member of that annoyingly enthusiastic group who uses LLVM/Clang as your C++ compiler, be sure that you are using version 3.3 or higher.)

Additional Tools

'make':
-------
The ’make’ utility is an integral part of software development, and you should know the basics of writing a ’Makefile’; however, the NcDialog package provides several Makefiles which you can copy and use with very little modification to build your own projects. Note that we refer to the ’make’ utility as ’gmake’ throughout this document. The reason is that we grew up using UNIX make and that worthless steaming pile of cow dung known as Microsoft make(tm), and we want to distinguish between those and GNU ’make’ which actually performs as documented.

The good news is that all you need to know for now is that you type the word ’gmake’ (or ’make’) and press ENTER.

'grep':
-------
If you are like us, you probably use ’grep’ at least three times before you’ve even had your morning coffee. This is especially true if you are working on a large project. For instance, the NcDialog project, including the test applications, is now over 45,000 lines of code.

Here’s a quick example. If you want to find the debugging method, Dump_uiInfo() in the NcDialog source code, type:
grep -n ’NcDialog::Dump_uiInfo’ *.cpp
This will yield your answer:
NcdControl.cpp:904:void NcDialog::Dump_uiInfo(winPos wPos, uiInfo info)

Application Framework

IMPORTANT NOTE: If you have not installed the ’ncursesw’ development package, then do it now (see Libraries for ncurses).

IMPORTANT NOTE: If you have not yet compiled the ’NcDialog.a’ link library, then do it now (see Building the API Library).

Create a Directory for Your New Application

Your new project deserves a new, empty subdirectory in which to live.
If you are new to programming, new to C++ or new to Linux, please go to Newbie Corner for general information about finding your way through the wonderful world of GNU/Linux programming.
If you’re not a programming virgin, then feel free to move ahead.

• Open a terminal window
  This is the GNOME, Konsole or other terminal emulator.
  Expand the window to at least 132 columns wide by 32 lines high.
• Create a subdirectory
  For this exercise we recommend that you create your work directory at the same level as the NcDialog test applications:
  
  cd NcDialog mkdir FirstProg cd FirstProg
• Copy the NcDialog Support files
  
  cp --preserve=all ../Dialog1/*.hpp cp --preserve=all ../Dialog1/NcDialog.a
• Create your Main Source file
  Open your favorite text editor and create an empty C++ source file. In this example we will use the name ’FirstProg.cpp’.

  Do what every programmer has done since Dennis Ritchie wrote his first ’Hello World!’ (although we will do it better than Dennis ever did).

  Copy the following into your empty source file and save it.

  // FirstProg.cpp // Written by: your_name_here // All definitions needed for your application #include "GlobalDef.hpp" // Prototype for local method void MyDialog ( void ) ; int main ( int argc, char* argv[], char* argenv[] ) { MyDialog () ; exit ( 0 ) ; } void MyDialog ( void ) { }
• Create a Makefile
  Open another empty document which will be your Makefile.

  Copy the following into the Makefile and save it as ’Makefile’. Note that uppercase and lowercase DO matter here.

  # This variable is defined for technical reasons # (see 'make' documentation for more information) .RECIPEPREFIX = > # Definition for compiler invocation COMPILE = g++ -x c++ -std=gnu++11 -Wall -c # Link the main source file to create an executable binary FirstProg: FirstProg.o NcDialog.a > g++ -o FirstProg FirstProg.o NcDialog.a -lncursesw # Comile the main source file FirstProg.o: FirstProg.cpp > $(COMPILE) FirstProg.cpp
• Test Your Setup
  You now have created enough of your application to try a compile, although at this time, the application still does nothing. At the command line, invoke gmake:

  gmake (ENTER)

  Your application should compile without errors and without warnings. If it does not, then please check your compiler installation and your ’ncursesw’ C-language library installation.

Add the Start-up and Shut-down Sequences

Although the start-up sequence can include several additional configuration options, this is just our first try, so we will keep it simple.

Modify main() and and the ’MyDialog’ method to look like this:

Try another compile. Your application should build without errors and without warnings. However, this time your application can show a bit of life, so after a successful build, invoke your application, admire it, invite your friends to admire it — and then press any key to exit.

Congratulations!

With 22 lines of code, you have mastered almost everything you need to know about using ’ncurses’. (It really is that easy.)

The next chapter will show you how to create your first NcDialog-based application. See Create a Dialog Window.

Create a Dialog Window

Now that you have created your application template (see Application Framework) you can create a useful application based on a dialog window. Then in the next chapter, see Create Control Objects, we will add control objects.

Define What Your Dialog Will Look Like

Discard the current ’MyDialog’ method.

Insert the following ’MyDialog’ method.
Yes, this is a big step, but each item will be carefully explained.

A Closer Look At Our Dialog

• The first two lines define the SIZE of the dialog.
• The next three lines define the COLOR of the dialog.
• The next two lines define the POSITION of the dialog.
• The next line is our display message
  And what kind of programmers would we be if we didn’t follow the only tradition in the high-tech world?.
• InitNcDialog dInit(){}
  Next, we populate a class (structure) for passing our dialog definition to the constructor.
  We initialize this object with the following:
  — the dialog dimensions — the dialog position — the dialog title (optional) — the dialog border style — the dialog’s border color and interior color — Note: We have not yet defined any control objects, so we pass a NULL pointer for the list of control objects.
• NcDialog* dp = new NcDialog ( dInit ) ;
  Instantiate (create) the dialog window object. This operation creates an ’instance’ of an NcDialog class object. Although nothing is yet visible, all necessary memory allocation and data configuration are now complete.
• dp->OpenWindow()
  ’Opening’ the window means drawing the window (text and color attributes) into the dialog’s reserved memory space. The data are not yet visible because we want to write additional data into the window before making it visible.

  Note that if the dialog does not open, we display a message in the parent window calling the user a dumb-guy. There are three (3) major reasons why a dialog might fail to open:

  1. memory allocation error (unlikely)
  2. invalid dialog definition parameters
  3. the terminal window is too small to hold our dialog
     This is the most likely cause, so if the dialog doesn’t open, expand you terminal window.
• dp->WriteParagraph ()
  Write a message into the dialog.
• dp->RefreshWin () ;
nckPause();
  Make the dialog visible to the user and wait for a key press.
• delete ( dp ) ;
  If the dialog was successfully opened, then close it now.
  To ’close’ a dialog means to make it invisible and then return all its resources to the system. If you forget this step, you will have an orphaned dialog floating around your application until you return to the command line.
• Return to main() for the shut-down sequence.

Re-compile and run your application again.

Congratulations!

You have successfully created your first dialog window. Yes, we admit that our dialog still doesn’t do anything useful, but we are getting close — and with only 54 lines of code.

The next chapter will show you how to design and position some control objects which we will use to interact with the user.
See Create Control Objects.

Create Control Objects

We now have a simple dialog object (see Create a Dialog Window), and we are ready to create some control objects.

We will define a list of four (4) control objects, 1 Pushbutton, 2 Radio buttons and 1 Textbox. Then in the next chapter will provide the user with access to these controls. See Simple Interface Loop.

Give names to our controls

Although we could use magic numbers to refer to our various controls, good programming practice dictates that we should name them in a consistent and meaningful way.

Copy this name list into the ’MyDialog’ method just above the InitNcDialog initialization.

Define the list of control objects

Control objects are defined by creating an initialized array of ’InitCtrl’ class objects.

The ’InitCtrl’ class is fairly complex, but for now, we will just use it, and later we will come to understand it. A detailed description of the ’InitCtrl’ class can be found at See InitCtrl class.

Copy the following array into the ’MyDialog’ method just below our name list.

Group the Radio Buttons

We have defined two Radio Buttons, and each button selects a color attribute for our displayed message. Clearly, the message cannot be BOTH colors at the same time, so we must allow the user to select only one of the Radio Buttons at a time.

To do this, we create an Exclusive-OR grouping for the buttons. An XOR group means that exactly one member of the group may be selected at any given time. (The ’yellow’ button is initially selected.)

Copy the following into the ’MyDialog’ method just below ’dp->OpenWindow()’, and just above ’dp->WriteParagraph()’.

Update our message

Make one more small adjustment to our existing code:
Replace the existing message text with the following message.

Rebuild and Run the Application

Congratulations!

You now have a fully-populated dialog application, although the user doesn’t yet have access to the controls. Let’s do that next.
See Simple Interface Loop.

Simple Interface Loop

An application based on an NcDialog dialog window uses an extremely simple user interface loop. The loop simply transfers the input focus among the defined controls.

All actual keyboard (and mouse) input is handled by the ’Edit_Xxx’ method for the control object which currently has the input focus.

For our example application, we defined three (3) types of controls, so our user-interface loop must handle those three types.

Edit Method	Control Class	Control Type
EditPushbutton	DialogPushbutton	dctPUSHBUTTON
EditTextbox	DialogTextbox	dctTEXTBOX
EditRadiobutton	DialogRadiobutton	dctRADIOBUTTON

Copy the following code into the ’MyDialog’ method just above ’nckPause();’, and then delete the ’nckPause();’ line because we don’t need it anymore.

Again, this is a big step, but each item will be carefully explained.

REMEMBER to delete the ’nckPause()’ call !!

A Closer Look At the Loop Elements

Note that no direct input is collected from the user!
All direct contact with the user is through the Edit_Xxx methods.

• gString lfMsg
  This is a message buffer used inside the user-interface loop.
  For more information on the gString class, please see gString Text Tool.
• uiInfo Info ;
  Define a class (structure) which is used to pass user input information between the ’Edit_Xxx’ methods and our control loop.
• short icIndex ;
  Define an index variable to track which control object currently has the input focus. This is an index into the array of control objects we defined above: 'InitCtrl ic[mdCONTROLS]'. The initial index (and the initial input focus) are on the ’DONE’ Pushbutton.
• bool done = false ;
  This is our loop-control flag. We keep processing user input until this flag becomes ’true’.
• while ( ! done )
  This is the top of our user-input loop.
• There are four(4) sections to this loop.
  
  • The first section tests for a ’dctPUSHBUTTON’ control type. If it is, then call the EditPushbutton() method.

    On return, Pushbuttons have one of two states: ’true’ or ’false’. If ’true’, then user is ready to exit the dialog, else move to the next/previous control.

    Also note that this control may be selected using the ’hotkey’ defined for the control. The ’hotkey’ can be identified by the underlined character which in this case is ’D’ indicating that the hotkey is CTRL+D.

    Thus, if focus arrived at the control via ’hotkey’, then we don’t call the EditPushbutton() method because the user’s instructions are already in the ’uiInfo’ data, so we just unpack it using the 'uiInfo::HotData2Primary()' method.

  • The second section tests for a ’dctTEXTBOX’ control type. If it is, then call the EditTextbox() method.

    On return, we have some fun with the contents of the Textbox control. If the contents were changed, we display them in the main dialog window using the current message color. If no change, we do nothing.

  • The third section tests for a ’dctRADIOBUTTON’ control type. Because the Radio Buttons are an XOR group. the edit method does not return until user leaves the group.

    On return, if the active member of the group has changed, then we re-draw the messages in the new color. If no change, we do nothing.

  • The fourth section of the input loop simply moves the input focus to whatever control the user has specified.

    Note that if the focus has already changed via ’hotkey’, then we do nothing here.

• Of course, we could add more controls and more types of controls to our dialog, so in that case, the user-interface loop would need an entry for each type of control defined.

  In a real-world application, data provided by the user would be used for more than just drawing pretty pictures, but we hope that the examples clearly describe the mechanism for expanding the power of the user-interface loop.

Rebuild and Run the Application

It's Playtime!

• You can now use the TAB and Shift+TAB keys to navigate among the dialog controls.
• Enter text into the Textbox control.
  Press ENTER or TAB to exit the Textbox.
• Change the message color with the Radio Button controls.
  Press ENTER or SPACE to activate a Radio Button.
• Exit the dialog
  Navigate to the ’DONE’ Pushbutton control and press ENTER, or use the defined ’hotkey’ for the ’DONE’ button: (CTRL+D) to exit the dialog from within any of the controls.
• Note that the Panic Button (CTRL+C) is captured, so the application will always be shut down in an orderly manner.

For a screenshot of this dialog, please see eye candy.

Congratulations!

You have successfully created your first NcDialog application!

It may be simple, but it can already do real things. How long did it take? If you are an experienced programmer, it probably took less than 30 minutes. If you are just beginning your career as an author of world-changing software, then perhaps an hour. Well done!!

Many more and different examples can be found in the test applications included in the NcDialog API package.
See Application Examples. Enjoy!

Introduction to ncurses

The ’curses’ interface was originally created for BSD UNIX to allow for formatted text output. A.T.&T. created a much-enhanced version of curses for use in its versions of UNIX.

The GNU ’ncurses’ (New Curses) C-language library is ’free software’ created under Linux to avoid copyright issues with SystemV(tm) UNIX. This is the version of curses included in all major Linux distributions. The ’ncurses’ C-language library comes in two flavors:
    ’ncurses’     This is the narrow (8-bit) character interface.
    ’ncursesw’    This is the wide (32-bit) character interface.
The functionality of these two versions is nearly identical; however, the ’wide’ version is recommended for all modern applications, because it fully supports all languages and character sets for internationalization of user interfaces.

Several people have been involved in the developmet of ’ncurses’ including Pavel Curtis, Zeyd Ben-Halim, Eric Raymond and Juergen Pfeifer. However, most of the heavy lifting in recent times has been done by the inestimable Thomas E. Dickey <http://invisible-island.net/> who, as he once posted on his website, took it up as a hobby. (Some hobby!)

Many terminal-based Linux applications use the ’ncurses’ C library, either directly or through one of the toolkits developed to make ’ncurses’ programming easier. ’ncurses’ is extremely portable and terminal-independent, and is reasonably-well documented. It suffers, however, from many years of questionable extensions (code bloat) and a general seediness that is revealed in a large number of small, but annoying bugs which most developers simply work around.

The only major drawback to the ’ncurses’ library is that it is oriented toward C-language programming and all that entails: lax prototyping, lack of type-checking, ’structs’, random casts, maintenance nightmares, and the constant threat of buffer overruns. This is not the fault of ’ncurses’, but of Kernighan and Ritchie, darn their lazy and unimaginative hides. :-)

Overall, ’ncurses’ is a tremendous accomplishment that brings a GUI-like interface and a quick application-development process to the obscure world of Linux command-line utilities.

NCurses Class Overview

The NCurses Engine is based on the ’ncurses’ C-language library functions. It is written entirely in C++ and encapsulates the most vulnerable constructs of C-language programming within the ’ncurses’ library for a nearly-indestructable (albeit, single-threaded) user interface.

The NCurses Engine uses the ‘ncursesw’ (wide-character) version of the ‘ncurses’ C library exclusively. The 8-bit character library, ‘ncurses’ is not used.

NCurses is implemented as a C++ class definition with approximately sixty (60) public methods for initialization and use of the underlying ‘ncurses’ library for keyboard and mouse input and formatted text output to the terminal window.

A comprehensive array of color-attribute constants and keycode constants are also available as public data members.
See Keycode Constants.
See Color Attributes.

The NCurses-class methods follow the ’ncurses’ C library convention regarding defined return values:
   (short int) ’OK’  indicates a successful execution
   (short int) ’ERR’ indicates a general error condition
(See note below on the choice of ’short int’ over the ’int’ integral type.)

The NCurses class makes absolutely no effort to be an inclusive wrapper for the ’ncurses’ library. In the author’s view, most of the capabilities provided by ’ncurses’ are seldom, if ever used — certainly not in a simple terminal application, so there is no need to provide a high-level interface to them. Note however, that if you find a need for ’ncurses’ functionality that is not supported within the NCurses class, please send the author a note, and we’ll see what can be done.
See Technical Support.

There is a single instance of the NCurses class in each application program. Because the NCurses-class object is instantiated globally (see GlobalDef.hpp), access to the NCurses methods and public data members is through the global handle, ’nc’. Example:
              nc.WriteString ( 5, 2, "What’s up doc?", nc.bl ) ;
This call will write the message using the NCurses::WriteString() method, AND the message will be written using the color attribute defined in the public data member, NCurses::bl (blue on default background).

Notes

1. The NCurses-class methods ARE NOT thread safe!
   The NCurses-class provides direct, or nearly direct access to the underlying ’ncurses’ C library functions. Be sure, therefore, to complete all initialization and configuration which uses NCurses methods BEFORE launching any secondary threads and BEFORE performing any Input/Output operations.
2. Beyond the start-up and shut-down sequences described, direct use of the NCurses-class methods in applications is strongly discouraged.

   Instead, use the NcDialog API for all non-trivial applications, so that you are working in a controlled dialog window rather that writing haphazardly to the base terminal window.

   The exception would be if you are writing what appears to the user to be an application that is writing to ’stdout’ (’wcout’, ’wprintf’) BUT is actually capable of formatted, multi-color output. In that case, by all means, amaze your friends with your command-line skills! In particular, please refer to the OutputStreamScrolling method.

3. The NCurses class, and in fact, the entire NcDialog API uses the ’short int’ integral type wherever practical. The author learned programming on an IBM360(tm), DEC PDP8(tm), PDP11(tm), S/100-bus hacks, the PET(tm), the Apple2(tm), Amiga(tm), and on and on: all in assembly language. The declaration of variables with 2, 4, 6, 12 or more extra bytes that do nothing at all is an offense to the author’s sensibilities.
   (We will admit, however, that memory-access time on certain platforms is more efficient in larger chunks.)

NCurses Public Methods

What follows is a list of all public methods of the NCurses class.
Methods are arranged in functional groups.

NCurses Startup-Shutdown

• NCurses ( void );

    Input  : none
  
    Returns: nothing
  

  NCurses-class constructor.

  The NCurses-class object is instantiated only once for the application. Global instantiation allows all application modules access to the methods and public data members of the class.
  

  NOTE: The instantiation occurs in GlobalDef.hpp and the instance 
        actually lives at the top of NCurses.cpp, and it is declared 
        as 'extern' everywhere else.
  

  
  
  
• ~Ncurses(void);

    Input  : none
  
    Returns: nothing
  

  NCurses-class destructor.

  The destructor returns any local resources to the system, and then calls the underlying ’ncurses’ C-library to shut down ncurses and release control of the input/output streams.
  

  NOTE: The destructor is called @emph{implicitly} as the NCurses 
        object goes out of scope (as the application exits to the 
        command line). The destructor actually has nothing to do if 
        the application exits in an orderly manner. See below for a 
        description of the 'StopNCursesEngine' method.
  

  
  
  
• short StartNCursesEngine ( bool autostartColorEngine = true,
                             NcColorMap* colorMap = NULL );

    Input  :
       autostartColorEngine : (optional, true by default)
          - if 'true' (AND if terminal supports color output), call the
            StartColorEngine() method before return to caller
          - if 'false', do not start the Color Engine, and only 2-color
            output will be available unless StartColorEngine() is called
            before any color output is performed.
       colorMap  : (optional, NULL* pointer by default)
          - if autostartColorEngine != false AND colorMap != NULL* , then this
            is a pointer to a fully-initialized NcColorMap object containing
            the color-pair and RGB values for the available color attributes.
  
    Returns:
       OK if successful
       ERR if unable to gain access to terminal firmware (or emulator)
           OR if provided color data do not match terminal definition
           OR if NCurses engine previously initialized
  

  Initialize the NCurses engine for formatted-text input and output.
  Must be called after instantiation of the NCurses class (which happens automagically when the application is executed) but before any other method of this class is called. See examples in test applications (see Test Applications).

  Default Settings On Startup

  • Locale: set according to terminal window’s environment
  • Cursor shape: nccvINVISIBLE
  • Keycode width: nckbEIGHT (UTF-8 encoding requires 8-bit width)
  • Key processing: nckpRAW
  • Key echo: disabled
  • Key delay: nckdFOREVER (blocking read)
  • Additional delay after ESC key detected: none
  • Escape sequence translation: enabled
  • I/O stream scrolling: disabled
  • Mouse input: disabled
  • Display colors:
    If a color-map is not specified by ’colorMap’ parameter, then the NCurses default color mapping is used, and RGB registers are not modified.

  Notes on color map initialization

  • If colorMap.rgbCount == actual number of RGB register sets supported by the terminal AND if the terminal allows modification of the RGB registers, then colorMap.rgbMap[] data is applied to the registers.
  • If colorMap.pairCount == actual number of color pairs supported by the terminal AND the terminal allows modification of the color pairs, then colorMap.pairMap[] data is applied to the terminal’s foreground/background color pairs.
  • if autostartColorEngine != false AND colorMap == NULL* , then the NCurses default color mapping will be used to initialize the Color Engine.
  • See NcColorMap class, for more information.
  • See also the descriptions of ’GetColorMap’ and ’SetColorMap’ elsewhere in this chapter.
  
  
  
• short StartColorEngine ( NcColorMap* colorMap = NULL );

    Input  :
       colorMap  : (optional, NULL* pointer by default)
          - if specified, then this is a pointer to a fully-initialized
            NcColorMap object containing the RGB register set values and/or
            the color-pair values.
          - to set RGB registers: set colorMap.rgbCount == number of register
            sets supported by the terminal (see 'TerminalColorSupport' method)
          - to set Color Pairs: set colorMap.pairCount == number of color
            pairs supported by the terminal
          - if not specified, then the NCurses default color mapping will be
            used to initialize the Color Engine.
  
    Returns:
       OK if successful
       ERR if unable to gain access to terminal firmware (or emulator)
           OR if provided color data do not match terminal definition
  

  Please see NcColorMap class for additional information on color map initialization.

  Initialize the NCurses color engine for color text output.
  This method is called automatically as part of StartNCursesEngine() UNLESS the application specifically overrides the default start-up sequence: (autostartColorEngine parameter == false) to start the NCurses Engine in monochrome mode.
  If multi-color output is desired, but automatic Color Engine startup was disabled in the call to StartNCursesEngine(), then call this method immediately after a successful call to StartNCursesEngine() OR at the latest, before any color-text output is performed.

  
  
  
• void StopNCursesEngine ( void );

    Input  : none
  
    Returns: nothing
  

  Shut down the NCurses Engine and release all associated resources.
  (To be called just before driving application exits.)

  Once the NCurses Engine has been shut down, the underlying ’ncurses’ C-library has returned all of its resources to the system and the terminal’s ’stdin’ and ’stdout’ character streams are once again available.

  
  
  
• bool ColorText_Available ( void );

    Input  : none
  
    Returns:
       'true' if the terminal supports multi-color text output
       'false' if the terminal does not support multi-color text output
               OR if the NCurses Engine has not yet been started 
                  i.e. system information is not yet available
  

  Determine whether the terminal or terminal emulator is capable of displaying color text. This will almost always be true on a computer, but may return false if running on a monochrome dumb terminal.

  
  
  
• bool ColorText_Initialized ( void );

    Input  : none
  
    Returns:
       'true' if Color Engine has been successfully initialized
       'false' otherwise
  

  Determine whether the Color Engine has been successfully initialized.
  

  If the terminal supports color output, then the NCurses Color Engine is started automatically by the call to ’StartNCursesEngine()’ unless the call explicity excludes color initialization. See also the description of ’StartColorEngine()’ above.

  
  
  
• bool TerminalColorSupport ( termColorInfo& cinfo );

    Input  :
       cinfo : (by reference) receives terminal color information
  
    Returns:
       'true' if the terminal supports multi-color text output
              parameters will be initialized
       'false' if the terminal does not support multi-color text output
               OR if Color Engine has not yet been started i.e. info is
                  not yet available
               (term_colors, rgb_regs and fgbg_pairs set to ZERO)
               (mod_pairs and mod_rgb set to 'false')
  

  Report terminal (or terminal emulator) color output capabilities.
  Data are returned in the specified termColorInfo-class object.

  class termColorInfo { public: // number of colors supported by the terminal short term_colors ; // number of RGB register sets supported (16 max) short rgb_regs ; // number of foreground/background color pairs supported short fgbg_pairs ; // 'true' if terminal supports color-pair modification bool mod_pairs ; // 'true' if terminal supports RGB register modification bool mod_rgb ; } ;
  
  
  

NCurses Configuration

• void ScreenDimensions ( short& scrLines, short& scrColumns );

    Input  :
       scrLines (by reference) receives screen line-count
       scrColumns (by reference) receives screen column-count
  
    Returns: nothing
  

  Returns the terminal window dimensions in lines and columns.

  All applications need some minimum amount of display area in which to operate, and many applications will expand to fill the available space. Therefore, it is important to check the dimensions of the terminal window as the application starts to be sure there is enough room to play.

  In addition, the user will sometimes re-size the terminal window while the application is running. If the size of the terminal window could affect the performance of your application, then you may want to check the dimensions regularly.

  
  
  
• short GetColorMap ( NcColorMap& cMap );

    Input  : 
       cmapPtr: (by reference, initial values ignored)
                NcColorMap-class object to receive the color-pair
                and RGB register data
  
    Returns: 
       OK if successful,
       ERR if Color Engine not started
  

  Get a copy of the terminal’s color-pair and RGB-register settings.
  Each element of a color-pair is indicated as a member of enum NcBaseColors. RGB register value range: minRGBvalue to maxRGBvalue (virtual values).

  For a full explanation of color mapping please see Color Attributes.

  
  
  
• short SetColorMap ( NcColorMap* cmapPtr,
                      bool setPairs, bool setRGB );

    Input  :
       cmapPtr : pointer to an initialized NcColorMap-class object
                 containing the new color-pair AND/OR RGB register data
       setPairs: if 'true', use data provided in cmapPtr.pairMap[] array
                 to modify ALL color pairs supported by the terminal
                 - Each value is a member of enum NcBaseColors or
                   enum NcExtendedColors.
                 - Each terminal implementation has a 'default'
                   foreground and background color, usually
                   white-on-black OR black-on-white. Use of defaults
                   may be specified for either or both fgnd/bkgnd by
                   entering ncbcDEFAULT in the appropriate field(s).
       setRGB  : if 'true', use data provided in cmapPtr.rgbMap[] array
                 to modify ALL RGB registers supported by the terminal
                 - RGB register value range: minRGBvalue to maxRGBvalue.
  
    Returns: OK if successful, else ERR
  

  Modify the terminal’s foreground/background color pairs AND/OR modify the RGB (Red-Green-Blue) register values (color hue).

  The safe way to modify the color data is to first get a copy of the existing color data and then modify it as needed.

  NcColorMap colorMap; nc.GetColorMap ( colorMap ); [ perform desired modifications to the data ] nc.SetColorMap ( colorMap, true, true );

  Please see Dialog2 App, Test 4, ’Adjusting the Text-color Map’ for a demonstration of color mapping, including saving the formatted data to a file and initializing the color data from the file. .

  
  
  
• short SetColorMap ( short pairIndex,
                      const NcColorPair& pairData );

    Input  :
       pairIndex: index of color pair to be modified
       pairData : new foreground and background color numbers
  
    Returns: OK if successful, else ERR
  

  Modify a single foreground/background color-pair.
  (See above for more information.)

  
  
  
• short SetColorMap ( short rgbIndex,
                      const NcRgbSet& rgbData );

    Input  :
       rgbIndex : index of RGB register set to be modified
       rgbData  : new red/green/blue register-set values
  
    Returns: OK if successful, else ERR
  

  Modify a single RGB register set.
  (See above for more information.)

  
  
  
• const char* GetLocale ( void );

    Input  : none
  
    Returns: pointer to locale string
  

  Returns a pointer to a const string containing the name of the currently-active locale setting.

  Please see Multi-language Support for a description of how the application’s locale affects text processing and the user interface.

  
  
  
• short SetLocale ( const char* newLocaleName );

    Input  :
       newLocaleName : string containing name of new locale
  
    Returns: OK if successful, else ERR
  

  Specify a new locale setting for multi-byte character interpretation.

  Note that when the NCurses class is instantiated, the locale used is the one specified by the terminal window’s environment variables. If the terminal window’s locale is not a UTF-8 locale, then this method must be called to specify a UTF-8-compliant locale before any I/O takes place.

  USE CARE! If the locale is not UTF-8 compliant, then NCurses methods will not be able to handle characters beyond simple ASCII (7-bit) characters.

  NOTE: For a complete list of locales supported by your terminal,
  use the ’locale -a’ command.

  
  
  
• short VerifyLocale ( const char* lcName=NULL );

    Input  :
       lcName : (optional, NULL by default)
                NULL indicates that current local setting should be tested
                If non-NULL, test the locale name provided
  
    Returns:
       OK if specified locale is known to support UTF-8 encoding
       ERR otherwise.
  

  Attempts to verify whether the local name provided specifies a locale that supports UTF-8 encoding.

  We perform a very simple test: If the locale name contains one of the following substrings ’UTF-8’ or ’utf8’ (case insensitive) then UTF-8 support is assumed. This assumption is somewhat dangerous because it relies on the folks at GNU.org to use consistent naming conventions, but we have (provisional) faith.

  
  
  
• void SetDefaultBackground ( NcBaseColors bkGround,
                              NcBaseColors pzfgnd=ncbcDEFAULT );

    Input  :
       bkGround : background color for the basic color pairs directly
                  supported by the ncurses library (usually pairs 0-7)
       pzfgnd   : (optional, ncbcDEFAULT by default)
                  foreground text color for color pair zero (ncbcBK)
  
    Returns: nothing
  

  Establish a default background color to be used with all the basic text (foreground) colors.

  Note that the results of this operation will likely be disappointing, especially if a black background (ncbcBK) is specified.
  See also: ’SetColorMap()’. Please see Dialog2 App, Test 4, ’Adjusting the Text-color Map’ for a demonstration of color mapping.

  
  
  
• short KeyEcho ( bool enable );

    Input  :
       enable : if 'true', enable key input echo
                if 'false', disable key input echo
  
    Returns: OK if successful, else ERR
  

  Enable or disable automatic echo of key input.

  IMPORTANT NOTE: Use of this method is not recommended.
  To ’echo’ key input means that for every keystroke you enter, the system immediately prints it to the display. While this is useful in ordinary command-line (’stdio’) user interaction, it is inappropriate for applications that used formatted output.
  Input echo is disabled by default inside the NCurses Engine, and should stay that way.

  
  
  
• ncKeyProc GetKeyProcState ( void );

    Input  : none
  
    Returns: member of ncKeyProc
  

  Returns the current level of key-input processing done by the kernel, the ncurses library, and the NCurses class before data are passed to the application.

  
  
  
• short SetKeyProcState ( ncKeyProc procState );

    Input  :
       procState : member of ncKeyProc
  
    Returns: OK if successful, else ERR
  

  Set the level of key-input processing done by the kernel, the ncurses library, and the NCurses class before data are passed to the application code.

  The default value set during startup is nckpRAW because key input will be fully encapsulated in the NCurses class making the maximum number of keys available to the driving application. Have a good reason before modifying this parameter.

  Applications should always request key data through the ’GetKeyInput’ method, and NEVER directly from the system or through C/C++ functions.

  
  
  
• short GetKeyDelay ( void );

    Input  : none
  
    Returns:
       delay in milliseconds
         or
       nckdFOREVER
         or
       nckdNODELAY
  

  Returns the current key-input delay in milliseconds.

  
  
  
• short SetKeyDelay ( short delay );

    Input  :
       delay : delay in milliseconds (1 to 1000)
                 or
               nckdFOREVER == wait indefinitely for input (blocking read)
                 or
               nckdNODELAY == returns immediately if no key data available
  
    Returns: OK
  

  Set the number of milliseconds to delay while waiting for key input.

  If no key data arrives before the timeout, the ’GetKeyInput’ method will return ERR and the target variable will be undefined.

  The default value on startup is nckdFOREVER (blocking read).
  Please see NCurses Startup-Shutdown for more information on the startup defaults.

  
  
  
• short SetKeycodeWidth ( ncKeyBits codeWidth );

    Input  :
       codeWidth : member of ncKeyBits
  
    Returns: OK if successful, else ERR
  

  Set the number of significant bits of key input from keyboard controller.

  IMPORTANT NOTE: Use of this method is not recommended.
  The default value set during startup is nckbEIGHT (8-bit) because UTF-8 encoding requires 8-bit width, so don’t modify default without a good reason.

NCurses Keyboard Input

• wkeyType GetKeyInput ( wkeyCode& wKey, bool rawData=false );

    Input  :
       wKey   : wkeyCode-class object (by reference) to hold the key
                information (initial values ignored)
       rawData: (optional, false by default)
                if false, capture and translate escape sequences
                if true, no local processing by the NCurses class,
                BUT the ncurses library will still do its translations
                UNLESS there has been a prior call to
                SetKeyProcState(nckpNO_TRANSLATION);
  
    Returns:
       member of enum wkeyType
       wktPRINT  if key is a valid, printing wchar_t character code
       wktFUNKEY if key is a translated function key (cursor key, Fnn, etc)
                 OR if key is an ASCII (non-printing) control code < 0x0020.
       wktMOUSE  if a mouse event in the input stream has been detected,
                 then the mouse event will be returned in wKey.mevent.
                 (wKey.key will be set to ZERO and should be ignored.)
       wktEXTEND This is an extension to the key input captured by the
                 ncurses library primitives. It provides additional
                 keycodes to the application: Alt+'a' through Alt+'z',
                 Alt+Shift+'a' through Alt+Shift+'z' and Alt+Ctrl+'a'
                 through Alt+Ctrl+'z'. (See notes in NCursesKeyDef.hpp.)
       wktESCSEQ if an untranslated escape sequence was captured.
                 The keycode (wKey.key) will be set to ZERO.
                 This should only happen if application has turned
                 off key-input translation (or in the rare case that
                 neither the ncurses library nor the NCurses class can
                 translate the sequence).
                 The captured escape sequence is held in a static
                 buffer and can be retrieved via GetEscapeSequence()
                 before it is overwritten by the next untranslated
                 sequence.
       wktERR    early return if no key data available.
                  This method performs a non-blocking read if 
                  'SetKeyDelay' method not set to nckdFOREVER,
                  and will retur wktERR if key data not available.
                 OR 
                  If system call returned an error (unlikely).
                 The keycode (wKey.key) will be set to ZERO.
  
       IT IS STRONGLY RECOMMENDED THAT THE RETURN VALUE ALWAYS BE CHECKED!
  

  Get a keycode and keytype from the ncursesw input stream. This includes all supported international character codes as well as captured-and-translated escape sequences representing function keys, cursor keys and other special-purpose key combinations.

  If mouse input has been enabled, mouse events will also be returned in caller’s wkeyCode-class object. For additional information, please see MouseEvent class.

  To use this method properly, the key processing state must be set to nckpUNBUFFERED or nckpRAW (see the ’SetKeyProcState’ method).
  In nckpCOOKED mode, system does not return data until the ENTER (RET) key is pressed, We short-circuit cooked-mode input gathering by a direct call to the ncurses-library primitive. Note also that mouse events cannot be detected while in cooked-mode. No developer in his/her/its right mind would use cooked-mode input anyway.

  
  
  
• wkeyType GetKeyInput ( short& sChar, bool rawData=false );

    Input  :
       sChar  : returned key value (by reference, initial value ignored)
       rawData: (optional, false by default)
                if false, capture and translate escape sequences
                if true, no local processing by the NCurses class
  
    Returns:
       member of enum wkeyType
       See GetKeyInput(wkeyCode&), above for details.
  

  Get a 16-bit key from the input stream.

  IMPORTANT NOTE: Use of this method is not recommended.
  Internally, the NCurses family of classes uses 32-bit input and output exclusively. However this 16-bit method is available if it is known that ’wide’ characters and keycodes will never be input by the user.

  Note that mouse input requires the 32-bit input stream. If a mouse event is captured through the 16-bit method, it will be discarded and reported as wktERR.

  
  
  
• short GetKeyInput ( void );

    Input  : none
  
    Returns: OK
  

  Wait for a keystroke i.e. PAUSE. The key input data are discarded.

  It is recommended that you use the ’nckPause();’ macro to initiate a wait-for-keypress, rather than calling this method directly.

  
  
  
• short UngetKeyInput ( wkeyCode& wKey );

    Input  :
       wKey : (by reference)
              contains keycode and key type of input to be 
              returned to the input queue
  
    Returns:
       OK if successful
       ERR if invalid key data (e.g. part of an escape sequence)
           or if un-get queue is full
  

  Return the wchar_t keycode and keytype, or a mouse event to the input queue.

  • The ncurses C-library function, ’unget_wch’ is very limited, and frankly, too buggy to be useful.
    For this reason, we have made the design decision to implement a more rubust push-back queue within the NCurses class.
  • Note that no more than KEYPUSH_MAX keycodes may be pushed back into the queue without an intervening call to the ’GetKeyInput’ method.
  • Note that only valid keycodes and mouse events can be pushed back into the queue. Escape sequences MAY NOT be pushed back into the queue.

  The primary use for this method is to implement keystroke macros to be executed within your application. For instance, if a user often enters a particular sequence of keystrokes, then this could be encapsulated and assigned a shortcut key, with your record_macro method and then executed with your play_macro method.

  
  
  
• wkeyType KeyPeek ( wkeyCode& wKey );

    Input  :
       wKey : wkeyCode-class object (by reference) to
              hold the key information (initial values ignored)
  
    Returns:
       member of enum wkeyType
          if key data waiting:
             wKey.type == wktPRINT, wktFUNKEY or wktMOUSE
             wKey.key  == key code
          if no key data waiting (or untranslated escape sequence):
             wKey.type == wktERR
             wKey.key  == ZERO and should be ignored
  

  If there is key data waiting in the key input buffer, return a copy of it. Does not remove key data from input stream.

  
  
  
• const wchar_t* GetEscapeSequence ( short& charCount );

    Input  :
       charCount : (by reference, initial value ignored)
                   receives the number of items in the escape 
                   sequence array
  
    Returns:
       const pointer to static buffer containing untranslated 
       escape sequence
         OR
       returns a pointer to an empty string if no untranslated
       sequence has been captured and 'charCount' set to ZERO.
  

  If an escape sequence has not been translated into a keycode within a call to the ’GetKeyInput’ method — either because the application has disabled translation, or because the sequence is unknown, then — ’GetKeyInput’ returns wktESCSEQ and the sequence is stored in a static buffer for potential retrieval. This method returns a pointer to the most recently captured sequence.

  If an untranslated sequence is generated by a key combination which you often use, then please contact the author with details so the NcDialog API can be updated. Please see Technical Support.

  
  
  
• short FlushKeyInputStream ( void );

    Input  : none
  
    Returns: OK
  

  Flush (discard) any key input data currently in the key input stream. If mouse input has been enabled, then flush the mouse-event queue also.

Please see NCurses Configuration for information on configuring the key input stream.

NCurses Display Output

The following methods write text and color-attribute data directly to the main terminal window. As with all NCurses-class methods, access is through the global handle: 'nc'.
Example: nc.WriteString ( 4, 1, "Hello World!", nc.bl );

Note that if NcWindow-class or NcDialog-class objects also exist in the terminal window, then those objects will need to be refreshed AFTER you have finished writing data to the terminal window.

IMPORTANT NOTE:
NCurses-class output methods are not thread safe; thread safety is implemented at a higher level (see thread-safe operation).
When using NCurses-class methods, be very sure that only one execution thread in your application is writing to the display.

• winPos WriteString ( const winPos& startYX, const char* uStr,
                       attr_t cAttr, bool rtl=false );
  
• winPos WriteString ( const winPos& startYX, const wchar_t* wStr,
                       attr_t cAttr, bool rtl=false );
  
• winPos WriteString ( short startY, short startX,
                       const wchar_t* wStr,
                       attr_t cAttr, bool rtl=false );
  
• winPos WriteString ( short startY, short startX,
                       const char* uStr,
                       attr_t cAttr, bool rtl=false );

    Input  :
       startYX: start position in Y/X (row/column)
             OR
       startY : start position in Y (row)
       startX : start position in X (column)
  
       -- FOR UTF-8-ENCODED CHARACTERS (INCLUDING ASCII)
         uStr : pointer to null-terminated UTF-8-encoded string
                note: gsMAXBYTES is the maximum number of bytes in
                      the string (including the NULLCHAR byte)
       -- FOR wchar_t 'WIDE' CHARACTERS
         wStr : pointer to null-terminated wchar_t ('wide') string
                note: gsMAXCHARS is the maximum number of characters
                      in the string (including the NULLCHAR)
  
       cAttr  : color attribute - one of the NCurses defined colors 
                with any additional attributes bits
       rtl    : (optional, 'false' by default) for RTL written languages
                if 'true', cursor moves from right-to-left
  
    Returns:
       returns final position of cursor
         specifies the row/column following the last character written,
         or if the target line has been filled, the last column 
         of the target line
  

  Write a text string with color attribute at the specified position in the stdscr window i.e. the main terminal window.

  The display IS REFRESHED to make the output visible.

  
  

  NOTES:

  • If specified starting position is invalid (beyond the window boundaries), then cursor will be set to the LTR or RTL window origin before data are written.
  • Output will be truncated at the edge of the window.
  • ASCII control characters, 0x01 through 0x1F are ignored.
  
  
  
• winPos WriteChar ( const winPos& startYX,
                     const char* uChar, attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( const winPos& startYX,
                     wchar_t wChar, attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( short startY, short startX,
                     const char* uChar, attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( short startY, short startX,
                     wchar_t wChar, attr_t cAttr,
                     bool refresh=false, bool rtl=false );

    Input  :
       startYX: start position in Y/X (row/column)
             OR
       startY : start position in Y (row)
       startX : start position in X (column)
  
       -- FOR UTF-8-ENCODED CHARACTERS (INCLUDING ASCII)
         uChar: pointer to character to display
                (single-byte or multi-byte character)
  
       -- FOR wchar_t 'WIDE' CHARACTERS
  
    Returns:
       returns final position of cursor
         specifies the row/column following the last character written,
         or if the target line has been filled, the last column 
         of the target line
  

  
  

  NOTES:

  • If specified starting position is invalid (beyond the window boundaries), then cursor will be set to the LTR or RTL window origin before data are written.
  • Output will be truncated at the edge of the window.
  • ASCII control characters, 0x01 through 0x1F are not written.
  • Be aware! A UTF-8 character can never be assumed to be a single byte.
    This is why the ’uChar’ parameter is a ’const char*’.
  • Be aware! For some languages, a wchar_t character may require additional zero-width meta-characters in order to be displayed properly. If so, use the WriteString method instead.
  
  
  
• void ClearScreen ( void );

    Input  : none
  
    Returns: nothing
  

  Erase the entire contents of the terminal window using the default background color, and then refresh the display to make the change visible.

  
  
  
• void RefreshScreen ( void );

    Input  : none
  
    Returns: nothing
  

  Refresh the contents of the terminal window, making any previous changes visible.

  
  
  
• short ClearLine ( short ypos, attr_t cAttr = ZERO );

    Input  :
       ypos : line number (zero-based)
       cAttr: (optional, default==terminal background color: nc.bw)
              if specified, set the BACKGROUND color attribute
  
    Returns:
       OK  if successful
       ERR if invalid line index
  

  Clear the specified line of the terminal window. Sets all characters of specified line to SPACE character.

  Terminal window is refreshed.

  Examples: If 'cAttr' is specified, it should indicate
            the BACKGROUND color. Because the character written is 
            the SPACE character, there is no visible foreground.
  
     nc.ClearLine ( 4 );                  // clear using default background
     nc.ClearLine ( 4, nc.bl | ncrATTR ); // clear using blue background
     nc.ClearLine ( 4, nc.blR );          // clear using blue background
     nc.ClearLine ( 4, nc.blcy );         // clear using cyan background
  
     // Clear entire terminal window to red background
     const short ROWS = 25 ;
     for ( short i = ZERO ; i < ROWS ; i++ )
        nc.ClearLine ( i, nc.reR ) ;
  

  
  
  
• winPos GetCursor ( void );

    Input  : none
  
    Returns:
       current cursor position is returned in a winPos-class object
  

  Get the current position of the terminal window’s cursor (insertion point).

  Example: winPos wp = nc.GetCursor ();

  USE OF THIS METHOD IS NOT RECOMMENDED:
  The cursor is not guaranteed to remain at its current position. Screen refresh operations, or other functionality may move the cursor at any time.

  
  
  
• short SetCursor ( short ypos, short xpos );
• short SetCursor ( winPos yxpos );

    Input  :
       ypos : Y offset from upper-left corner (zero-based)
       xpos : X offset from upper-left corner (zero-based)
           OR
       yxpos: Y/X offset from upper-left corner (zero-based)
  
    Returns:
       OK  if successful
       ERR if parameter(s) out of range
  

  Set the terminal window’s cursor position (insertion point).

  USE OF THIS METHOD IS NOT RECOMMENDED:
  The cursor is not guaranteed to remain where it is placed. Screen refresh operations, or other functionality may move the cursor at any time.

  
  
  
• ncCurVis GetCursorState ( void );

    Input  : none
  
    Returns:
       current cursor state (member of enum ncCurVis)
  

  Returns the current visibility state of the cursor.

  The cursor is set as invisible during startup, and should usually remain invisible at all times to avoid ugliness during re-drawing of the window contents.

  Internally, the NcDialog API makes the cursor visible ONLY within the ’EditTextbox’ method, so the user can see the text-insertion point.

  
  
  
• short SetCursorState ( ncCurVis state );

    Input  :
       state : member of enum ncCurVis
  
    Returns: OK
  

  Set the visibility state of the cursor.
  Saves previous state for later call to RestoreCursorState().

  
  
  
• short RestoreCursorState ( void );

    Input  : none
  
    Returns: OK
  

  Restore the previous visibility state of the cursor.
  See ’SetCursorState’ method, above.

NCurses Mouse Access

The NCurses-class mouse implementation is simply a primitive interface to the underlying ncursesw C-language library mouse interface. For the application layer mouse interface, please see the NcDialog API mouse interface. See Mouse Configuration.

Introduction to the Text-based Mouse Interface

• Please note that the xterm (or Wayland) mouse driver and the ncurses(w) C-language library mouse interface are, as distributed, completely useless to console applications.
• Because the NCurses-class mouse interface provides direct access to the xterm/ncurses(w) mouse interface, we must admit that the NCurses-class mouse interface is nearly useless on its own.
• The methods described in this chapter form the basis of the much more sophisticated NcDialog mouse interface:
  (see Mouse Configuration).
• The mouse is a shared resource:
  • Events located beyond the writable area of the terminal window belong to someone else and are therefore not available to us.
  • Some mouse events within the writable area of the terminal window are captured by the GUI desktop, and are therefore not available to us. Examples: Button 3 click is the terminal’s context menu, and by default, Button 2 click is masked by the ’paste selection’ shorcut.
• Timing artifacts:
  • While mouse events in a GUI application are handled in a sophisticated way (see the GTK+ mouse interface), mouse events in an ncurses(w) text-based environment are not handled very well at the xterm level. This puts most error-recovery beyond the reach of console applications unless they circumvent the majority of the ncurses(w) library mouse interface altogether.
  • Mouse events are presented in a LIFO (last-in-first-out) queue. This means that events which are older than the one you just extracted from the queue are probably stale and meaningless.
  • The scan interval for mouse events in a terminal window is a fixed period, which unfortunately means that the actual event may occur partly during one interval, and partly during the following interval.
  • These timing issues lead to all sorts of partial event captures, misinterpreted events, un-requested events and loss of valid events. (We hates meeces to pieces!)
  • Filtering of spurious events is done locally to prevent reporting of unexpected events related to timing artifacts, but the occasional loss of valid mouse activity is unavoidable at this level. See the ’FilterSpuriousMouseEvents’ method for more information.
• Mouse-cursor position:
  Mouse movements cannot be directly determined through the ncurses(w) C-language library interface. The Y/X coordinates which indicate mouse position are available ONLY in conjunction with a button event. While we hope for an enhancement to the ncurses(w) library which will support independent position reporting, it’s not likely to happen any time soon.
• Mouse hardware:
  Different platforms and different mouse manufactures present a wide variety of mouse input; however, the most important features are the number of mouse buttons implemented and whether the mouse includes a scroll wheel. Certain joysticks and other game input devices also use the mouse interface in innovative ways. Touchpads, which are a kind of mouse hardware, support Y/X/Z coordinates, but the ncurses(w) library does not currently support the ’Z’ axis (vertical) coordinate or multi-point touch. Clearly, the underlying ncurses(w) library can only hope to support a common subset of all these possible options, so developers of text-based games are basically out of luck.
• Scroll-Wheel events:
  • xterm supports ScrollWheels (and button2-TrackPoint(tm) scroll emulation, although it may be disabled by default).
  • The ncurses(w) library, however, has no way to reliably report these events across all systems, so expect the unexpected.
    (See the event-mask definition, REPORT_SCROLL_WHEEL, below.)
  • IMPORTANT NOTE: When mouse events are disabled in the ncurses(w) C-language library, then the xterm mouse driver may convert ScrollWheel events to a series of UpArrow or DownArrow keys (usually groups of 3). This is a standard feature of terminals. However, when the ncurses(w) C-language library’s mouse interface is enabled, then the terminal’s automagic conversions are blocked, and we receive the actual mouse events.

Please see the test application, Dialog4, Test03 for an example of the NCurses-class mouse interface.

Please see the test application, Dialog4, Test04 for an example of the NcDialog-class mouse interface.

In general, using the mouse for a text-based application is unnecessary, and actually makes the user interface more difficult to use. This is especially true at the level of the NCurses (terminal window) abstraction layer. For this reason, please consider the following method descriptions as reference information only, and not as an invitation to use them directly. However, if you must have mouse input for your application, use the NcDialog mouse interface instead: see Mouse Configuration, which transparently converts most mouse events into the equivalent keystroke data.

NCurses Mouse Methods

• short EnableMouseEvents ( mmask_t eventTypes );

    Input  :
       eventTypes : bit mask of event types to be enabled
                    (at least one event-type bit must be set)
                    Bit definitions are the BUTTONxxxx group of
                    defines in ncurses.h
    Returns:
       OK  if mouse enabled AND all bits of the event-type mask
           have been set successfully
       ERR if a) mouse not enabled OR
              b) actual event-type mask differs from that specified
              c) eventTypes == ZERO
  

  Allow mouse events to be reported, either indirectly through the ’GetKeyInput’ method, or directly through the ’GetMouseEvent’ method.

  See the list of mouse event bitmask values in the SetMouseEventTypes method, below.

  
  
• short DisableMouseEvents ( mmask_t* oldeventTypes=NULL );

    Input  :
       oldeventTypes : (optional, NULL pointer by default)
                       if not a NULL pointer, then target
                       receives previous event-type bit mask
  
    Returns:
       OK  if mouse-event reporting disabled
           (mouse driver MAY BE disabled also - system dependent)
       ERR if mouse-event reporting could not be disabled
           (this could be due to a timing issue, so try again)
  

  Disable reporting of mouse events.

  The connection with the mouse interface will be disabled and no further mouse events will be placed in the input queue.

  Note that any mouse events that have already arrived in the queue will still be available, so it is good practice to flush the input queue after disabling the mouse interface. See the ’FlushKeyInputStream’ method.

  
  
• bool MouseEventsEnabled ( void );

    Input  : none
  
    Returns:
       'true' if mouse events can be detected and reported
       else 'false'
  

  Reports whether mouse input is currently enabled.
  (See ’EnableMouseEvents’ method, above.)

  
  
• short GetMouseEventTypes ( mmask_t& eventTypes );

    Input  :
       eventTypes: (by reference, initial value ignored)
                   receives the mouse-event-type mask
  
    Returns:
       OK  if successtul
       ERR if mouse-event input disabled
  

  Reports the type(s) of mouse events which will be reported.
  This is the current mouse-event-type bitmask.

  
  
• short SetMouseEventTypes ( mmask_t eventTypes );

    Input  :
       eventTypes: new mouse-event-type mask
  
    Returns:
       OK  if mouse enabled AND all bits of the event-type mask
           have been set successfully
       ERR if mouse not enabled, OR 
           if actual event-type mask set differs from that specified, OR
           if eventTypes == ZERO (i.e. invalid mask)
  

  Specify the type(s) of mouse events which will be reported.
  Bit definitions for the event mask are the BUTTONxxxx group of defines in ncurses.h. As of ’ncursesw’ library version 5.9 (mouse version 1), these are as follows. Note however, that not all events will be reported in the same way by all system/hardware combinations.

  BUTTON1_RELEASED BUTTON2_RELEASED BUTTON1_PRESSED BUTTON2_PRESSED BUTTON1_CLICKED BUTTON2_CLICKED BUTTON1_DOUBLE_CLICKED BUTTON2_DOUBLE_CLICKED BUTTON1_TRIPLE_CLICKED BUTTON2_TRIPLE_CLICKED BUTTON1_RESERVED_EVENT BUTTON2_RESERVED_EVENT BUTTON3_RELEASED BUTTON4_RELEASED BUTTON3_PRESSED BUTTON4_PRESSED (also ScrollWheel-Down) BUTTON3_CLICKED BUTTON4_CLICKED BUTTON3_DOUBLE_CLICKED BUTTON4_DOUBLE_CLICKED BUTTON3_TRIPLE_CLICKED BUTTON4_TRIPLE_CLICKED BUTTON3_RESERVED_EVENT BUTTON4_RESERVED_EVENT BUTTON_CTRL (CTRL key down) BUTTON_SHIFT (SHIFT key down) BUTTON_ALT (ALT key down) REPORT_MOUSE_POSITION (also ScrollWheel-Up)

  Note that we define an additional event-type mask item, REPORT_SCROLL_WHEEL, in NCurses.hpp. However, this definition has been tested only for the common mouse type with two-buttons plus clickable Scroll-Wheel. Note that even with this limited test, the results are disappointing. This is because the ’ncursesw’ C library defines two seldom-used bits to indicate ScrollWheel activity: BUTTON4_PRESSED==ScrollDown and REPORT_MOUSE_POSITION==ScrollUp.
  While these definitions are helpful in supporting ScrollWheels, the default scan interval is too long for capturing a sequence of ScrollWheel events. (See the SetMouseClickInterval method, below.)

  Note that the BUTTON_CTRL, BUTTON_SHIFT and BUTTON_ALT flags are for reporting only, and will be reported regardless of whether you specify them in the bitmask.

  
  
• short GetMouseClickInterval ( short& max4Click );

    Input  :
       max4Click : (by reference, initial value ignored)
                   receives current interval
  
    Returns:
       OK  if successful
       ERR if mouse-event input disabled
  

  Get the current maximum mouse-click interval in thousandths of a second.

  
  
• short SetMouseClickInterval ( short max4Click,
                                short* oldMax=NULL );

    Input  :
       max4Click : interval in thousandths (0.001) of a second
                   specify an interval OR a member of enum ncmInterval
       oldMax    : (optional, NULL pointer by default)
                   pointer to variable to receive previous interval value
  
    Returns:
       OK  if successful
       ERR if value out-of-range OR
           if mouse-event input disabled
  

  Specify the maximum interval for collecting a series of mouse-button-press and mouse-button-release events which will be interpreted as a ’click’ event.

  This interval is set to ncmiDFLT (166ms) by default, but can be adjusted for the dexterity and caffination level of the individual user.

  Examples:

  • Scanning for a ’single-click’ event:
    One ’press’ event followed by one ’release’ event must be received within the specified interval.
  • Scanning for a ’double-click’ event:
    The event series ’press’, ’release’, press’, ’release’ must be received within the specified interval.
  • Scanning for a ’triple-click’ event:
    The event series ’press’, ’release’, press’, ’release’, ’press’, ’release’ must be received within the specified interval.
  
  
• short GetMouseEvent ( MouseEvent& mevent );

    Input  :
       mevent : (by reference, initial value ignored)
                receives the mouse-event data
  
    Returns:
       OK  if mouse event extracted successfully
       ERR if no mouse event in the queue OR
           if mouse-event input disabled
  

  Extract the newest mouse event from the event queue.

  PLEASE NOTE: The low-level ’ncursesw’ C-library functions that handle mouse events are not reliable; therefore IT IS STRONGLY RECOMMENDED that all mouse-event storage and retrieval be done through the ’GetKeyInput’ and ’UngetKeyInput’ methods, and that the ’GetMouseEvent’ and ’UngetMouseEvent’ methods should not be called directly.

  
  
• short UngetMouseEvent ( MouseEvent& mevent );

    Input  :
       mevent : (by reference) contains the mouse-event data to be 
                pushed back into the event queue.
  
    Returns:
       OK  if mouse event successfully re-queued
       ERR if event queue is full OR 
           if mouse-event input disabled
  

  Push a previously-extracted mouse event back into the input queue.

  PLEASE NOTE: The low-level ’ncursesw’ C-library functions that handle mouse events are not reliable; therefore IT IS STRONGLY RECOMMENDED that all mouse-event storage and retrieval be done through the ’GetKeyInput’ and ’UngetKeyInput’ methods, and that the ’GetMouseEvent’ and ’UngetMouseEvent’ methods should not be called directly.

  
  
• short FlushMouseEventQueue ( void );

    Input  : none
  
    Returns:
       OK if successful, or
       ERR if mouse-event input disabled
  

  Remove any mouse events waiting in the mouse-event queue.

  The ’GetMouseEvent’ method returns events in LIFO (last-in-first-out) order. If you have received the event you’re looking for and don’t want any more events, OR if your mouse has become tempramental and is sending undesired or unexpected events, then this method can be used to flush the mouse-event queue.

  
  
• short GetMousePosition ( MouseEvent& mpos );

    Input  :
       mevent : (by reference, initial value ignored)
                receives the mouse-event data
  
    Returns:
       OK if current mouse position determined
       ERR if unable to determine mouse position, or
           if mouse-event input disabled
           
  

  Report the current mouse position in the ’sypos’ and ’sxpos’ data members of the provided MouseEvent object.

  NOTE: At present, there is no method provided by the ncurses C-language library for obtaining the mouse-pointer position unless it is returned as part of a button event. Therefore, this method will always return ERR.

  
  
• short FilterSpuriousMouseEvents ( bool filter );

    Input  :
       filter : 'true' enables filtering
                'false disables filtering
  
    Returns:
       OK if successful, or
       ERR if mouse-event input disabled
  

  Enable or disable filtering of mouse events that arrive in the queue even though events of that type have not been requested via the event mask.

  Filtering is enabled by default, and it is recommended that it remain enabled unless there is a specific need to see the spurious events.

  While filtering is enabled: - If an unrequested event is received by the ’GetMouseEvent’ method, then it is discarded, and reported as no event. - If an unrequested event is received in the keyboard-input queue via the ’GetKeyInput’ method, then the event is discarded AND: a) if ’GetKeyInput’ is set to block, then wait for the next keycode b) if ’GetKeyInput’ is set for timeout, then wktERR is returned. - In either case, if an unrequested event is received, then the mouse-input queue is flushed. While filtering is disabled: - All detected mouse events, whether or not they match those enabled through the event mask, will be reported as normal mouse events. - Note that the ’ncursesw’ library is not really at fault for reporting unrequested mouse events. Rather it is the xterm mouse driver which allows the spurious events into the event queue.

NCurses Utility Methods

• void Hibernate ( void );

    Input  : none
    Returns: nothing
  

  Temporarily disable the NCurses Engine so external terminal applications can gain full access to the terminal’s functionality.

  IMPORTANT NOTE: Unlike the ’StopNCursesEngine()’ method, all resources held by the NCurses Engine are retained while in hibernation mode.

  Call ’Wake()’ or ’RefreshScreen()’ method to re-activate the NCurses engine.

  
  
• void Wake ( void );

    Input  : none
    Returns: nothing
  

  Re-enable the NCurses Engine after a previous call to Hibernate().
  Also flushes any remaining data from the keyboard input stream.

  
  
• void BiDiEnable ( bool enable );

    Input  : 
       enable : if 'false', disable terminal control of RTL output
                if 'true',  return control of RTL output to terminal
    Returns: nothing
  

  Disable or re-enable the terminal emulator’s automatic control of BiDi (Bi-Directional) output.

  This method must be called when the NCurses Engine IS NOT active.

  The NCurses Engine calls this method during start-up to disable the terminal’s BiDi detection, and calls the method again during the shut-down sequence to re-enable terminal control of BiDi data.
  See NCurses Startup-Shutdown, “StartNCursesEngine” and “StopNCursesEngine” methods, as well as the discussion of RTL (Right-To-Left) text rendering at: BiDi Support for more information.

  
  
• short UserAlert ( void );

    Input  : none
    Returns: OK if audible alert supported, else ERR
  

  Sound an audible alert. The actual sound produced is system dependent.
  Note that if the system does not support audible alerts, then then the screen will visibly flash instead.

  
  
• const char* Get_NCurses_Version ( void );

    Input  : none
    Returns:
       (const char*) pointer to version string
  

  Returns a pointer to NCursesVersion, the NCurses class version number.

  
  
• const char* Get_nclibrary_Version ( void );

    Input  : none
    Returns:
       (const char*) pointer to version string
  

  Returns a pointer to the ncurses (curses) C-language library version number.

NCurses Debugging Methods

• winPos WriteStream ( const wchar_t* wStr, attr_t cAttr );

    Input  :
       wStr : pointer to null-terminated wchar_t 'wide'
              character string
       cAttr: color attribute for output
  
    Returns:
       returns final position of cursor
  

  Write data to the main terminal window (’stdscr’). This method is to be called ONLY to output data to the terminal window when output-stream scrolling has been enabled. (see the OutputStreamScrolling method) If output-stream scrolling has not been enabled, then this method redirects to the standard NCurses-class ’WriteString’ method to produce formatted, non-scrolling data.

  Note that the NcDialog API does not support ’narrow’ (char) output.
  Because the input to this unformatted-output method may be of any length, we avoid possible conversion-buffer overrun by allowing only ’wide’ input.

  This method does not filter the output in any way. While the standard output methods ignore ASCII control characters to ensure consistent formatting, WriteStream() outputs all characters, regardless of type. Note however, that the C language output primitives embedded in the ’ncursesw’ C library will either ignore most ASCII control characters, or will choke and output garbage. Only newline '\n' and tab '\t' will be reliably recognized on all systems.

  IMPORTANT NOTE:
  This method gives the underlying ’ncurses’ C-language library direct control of the output, which is generally not a good idea. That is why this method is classified as a debugging method. Use with caution.

  IMPORTANT NOTE:
  This method is not to be used when the higher-level NcWindow and NcDialog classes have been instantiated in the terminal window. Doing so will cause all kinds of ugliness. You have been warned.

  
  

  Example of stream-oriented output:
  
  if( (nc.StartNCursesEngine ()) == OK )
  {
     nc.ClearScreen () ;                    // clear terminal window
     nc.OutputStreamScrolling ( true ) ;    // enable stream output
  
     nc.SetCursor ( 0, 0 ) ;                // set cursor to window origin
     for ( short i = 100 ; i > ZERO ; i-- ) // output some data
        nc.WriteStream ( L"Raw stream output.**", nc.bl ) ;
     nckPause();                            // wait for user
  
     nc.OutputStreamScrolling ( false ) ;   // disable stream output
     nc.ClearScreen () ;                    // clear terminal window
     nc.StopNCursesEngine () ;              // Deactivate the NCurses engine
  }
  

  See test application Dialog2, Test11 (see Stream Output) for a working example of this method. Invoke with:  ./Dialog2 -11 

  
  
• short OutputStreamScrolling ( bool enable );

    Input  :
       enable : if 'true', enable automatic line wrap and scrolling
                if 'false', disable automatic line wrap and scrolling
  
    Returns: OK
  

  Enable or Disable "standard output" style scrolling in the stdscr window.

  By default, the underlying ’ncurses’ library disables scrolling. The NCurses library also leaves scrolling disabled by default because it produces ugly and undisciplined output.

  If, however, you have a need to emulate a common console application which is unaware of screen edges and data formatting then use this method to enable/disable scrolling.

  For an example of an application built around this functionality, please see Keymap App.

  a) If the cursor reaches the right edge of the terminal window, the cursor is automatically repositioned to the leftmost column of the following display line. (This is dumb-terminal character wrapping, NOT word wrap.) b) If the cursor reaches the right edge of the last display line in the terminal window, then all data in the window will be scrolled up by one line, and the cursor will be repositioned to the leftmost column of the last display line. IMPORTANT INFORMATION ABOUT AUTOMATIC SCROLLING: - The NCurses-class output methods ’WriteString’ and ’WriteChar’ are fully aware of the terminal-window edges and therefore truncate output at the edge of the window REGARDLESS of the state of output-stream scrolling. - Only the ’WriteStream’ method ignores the terminal window dimensions and allows for automatic scrolling. - Scrolling output applies ONLY to the main terminal window and NOT to any sub-window objects within the terminal window. Therefore, do not define any sub-windows when output-stream scrolling is enabled. In practical terms, this means that you must not instantiate any of the higher-level NcWindow and NcDialog classes while scrolling is enabled. - The cursor remains where is was placed after the last character in the string is written, so subsequent output will begin where the previous output left off unless the ’SetCursor’ method is explicitly called. Note that any attempt to set the cursor at a position outside the terminal window will be ignored. - This functionality IS NOT THREAD SAFE. It is the application’s responsibility to ensure that only one thread writes data to the output stream. - Because output-stream scrolling emulates output to a dumb terminal, this method does not support RTL languages.
  
  
• void DisplayColorOptions ( short ypos=3, short xpos=1,
                             bool pause=true );

    Input  :
       ypos      : (optional, default==3) Y screen offset
       xpos      : (optional, default==1) X screen offset
       pause     : (optional, default==true)
                   if 'true' wait for key input before returning
    Returns:
       nothing
  

  Display samples of the standard color scheme defined in the ’ncurses’ C-language library, using the current background color.

  The ’ncurses’ library directly supports the basic eight (8) color attributes and the associated color-modification bits.
  Please see Color Attributes for a detailed discussion of color attributes.

  
  
• void DisplayDefinedColors ( short ypos=3, short xpos=1,
                              bool pause=true );

    Input  :
       ypos      : (optional, default==3) Y screen offset
       xpos      : (optional, default==1) X screen offset
       pause     : (optional, default==true)
                   if 'true' wait for key input before returning
    Returns:
       nothing
  

  Display a character string to demonstrate each of the public data member color attributes defined in NCurses.hpp.

  Although the ’ncurses’ C-language library directly supports only the basic eight (8) foreground/background color pairs available on all color terminals, most modern system hardware supports 16 or more color pairs. As an extension to ’ncurses’, the NCurses Engine dynamically defines as many color pairs as the target hardware will support up to 64 color pairs. See Color Attributes.

  This method may also be used to visually verify that during startup, the ’SetDefaultBackground’ method has properly initialized these members.

  
  
• void DisplayAlternateFont ( short ypos=3, short xpos=1,
                              bool pause=true );

    Input  :
       ypos      : (optional, default==3) Y screen offset
       xpos      : (optional, default==1) X screen offset
       pause     : (optional, default==true)
                   if 'true' wait for key input before returning
    Returns:
       nothing
  

  Display the characters of the Alternate Character Set (ACS). These are the ’narrow’ (ncurses) or ’wide’ (ncursesw) characters, which are built into the terminal’s character set for most terminal emulation software. Display of these characters is controlled by a bit in the color attribute value. This alternate character set consists mainly of line-drawing characters, along with some miscellaneous symbols.

  As an example, in the normal ASCII character set, the value 0x6B is displayed as the letter ’k’. To display this character in the terminal window using the default color, you would call:
      nc.WriteChar ( 1, 1, 'k', nc.bw ) ;            - ->'k'
  However, by changing a bit in the color attribute, the line drawing character, ’upper right corner’ will be displayed instead.
      nc.WriteChar ( 1, 1, 'k', nc.bw | ncaATTR ) ;  - ->'┐'

  While this sequence works, it is not intuitive to work with, nor particulary maintainable. It is recommended that the equivalent (’wide’) character constants be used for all new development. These constants for line-drawing and other characters are declared in NCurses.hpp.
  See Line Drawing Characters.

  Please note that the UTF-8 character set which is the system default, knows nothing about the ACS, so that the low-level ncurses C-language library is probably emulating the ACS anyway, so why bother with the ACS at all?

  
  
• void DebugBorder ( short wLines, short wCols,
                     short wulY, short wulX, attr_t attr );

    Input  :
       wLines    : verical size of area in lines
       wCols     : horizontal size of area in columns
       wulY      : Y offset from upper left of terminal window
       wulX      : X offset from upper left of terminal window
       attr      : color attribute for drawing
    Returns: nothing
  

  Draw a fake border around an imaginary window.

  NOTE: This method is for use only with the development methods:
        DisplayDefinedColors(), DisplayColorOptions(), and
        DisplayAlternateFont().

  
  
• void GetTransTable1 ( const char**& tt1,
                        short& tt1Min, short& tt1Max );
  
• void GetTransTable2 ( const char**& tt2,
                        short& tt2Min, short& ttsMax );
  
• void GetTransTable3 ( const char**& tt3, short& tt3Entries );

    Input  :
       tt1 | tt2 | tt3    : receives address of specified lookup table
       tt1Min | tt2Min | tt3Min : receives lowest code in table
       tt1Max | tt2Max | tt3Max : receives highest code in table
    Returns: nothing
  

  Provides access to tables of string literals matching the keycodes defined in the NCurses class. These can be used to unambiguously display any captured keycode which has been defined within the environment.

  TransTable1
     Contains the ASCII control codes, pluse ENTER, TAB, ESCAPE
     and NULLCHAR.
  TransTable2
     Contains the range of keycodes available to the 'ncurses' 
     C-language library; however, remember that 'ncurses' can define 
     a maximum of 64 keycodes, so not all values in the table have 
     associated key definitions.
  TransTable3
     Contains the wktEXTENDED keycode group which consists of keys 
     defined in the NCurses Engine. These are ALT+key and ALT+SHIFT+key 
     key combinations.
  

  
  

  Examples

  //* Access to debugging data for key translation *
  const char **TransTable1, **TransTable2, **TransTable3 ;
  short tt1Min, tt1Max, tt2Min, tt2Max, tt3Entries ;
  nc.GetTransTable1 ( TransTable1, tt1Min, tt1Max ) ;
  nc.GetTransTable2 ( TransTable2, tt2Min, tt2Max ) ;
  nc.GetTransTable3 ( TransTable3, tt3Entries ) ;
  
  const char* cptr ;
  const char* ovrflow = "OVERFLOW" ;
  wchar_t wOut[100] ;
  wkeyCode wk ;
  nc.GetKeyInput ( wk ) ;
  switch ( wk.type )
  {
     case wktPRINT:
        swprintf ( wOut, 99, L"Printing character: '%C'", wk.key ) ;
        break ;
     case wktFUNKEY:
        if ( wk.key >= tt1Min && wk.key <= tt1Max )
           cptr = TransTable1[wk.key] ;
        else if ( wk.key >= tt2Min && wk.key <= tt2Max )
           cptr = TransTable2[wk.key - tt1Max] ;
        else   
           cptr = ovrflow ;
        swprintf ( wOut, 99, L"Function key: %s", cptr ) ;
        break ;
     case wktEXTEND:
        if ( wk.key >= ZERO && wk.key < tt3Entries )
           cptr = TransTable3[wk.key] ;
        else
           cptr = ovrflow ;
        swprintf ( wOut, 99, L"Extended key: %s", cptr ) ;
        break ;
     case wktMOUSE:
        swprintf ( wOut, 99, L"Mouse event" ) ;
        break ;
     case wktESCSEQ:
        swprintf ( wOut, 99, L"Un-translated escape sequence" ) ;
        break ;
     case wktERR:
        swprintf ( wOut, 99, L"Key-wait timeout" ) ;
        break ;
  } ;
  nc.WriteString ( 2, 0, wOut, nc.bw ) ;
  

  For a more complete example, please refer to the Dialog2 test
  application, Test #5. (see Dialog2 App)

Color Attributes

• ncurses Color Support
• Platform Color Support
• NcDialog API Color Support
• NcDialog Color Variables

Keycode Constants

What Is a Character?

The native language of Linux is UTF-8. UTF-8 encoding is a byte-oriented way of representing all characters of all human languages.

’Curses’ was developed long before UTF-8 encoding, so character encoding and processing in curses world is not as simple as one would hope. The original 7-bit and 8-bit curses C-language library was completely inadequate for international communication, so the ’wide character’ library (ncursesw) was developed. The ’wide’ library is based on a ’wchar_t’ (32-bit integer) character type. At the lowest level, some tricks are played to enable ’wide’ character support in the ’ncursesw’ library. Fortunately, an NcDialog API application doesn’t need to worry about these details because the printing characters are equivalent to ’Unicode code points’. However, a few things must be kept in mind.

The first thing to remember is that character codes fall into two general categories.

Because the ’ncursesw’ library has only a very limited number of codes available, the numerical values for characters and for commands overlap; therefore, a character is always handled as a pair of codes.

In general, it is not possible to know whether a given code is a character or a command code unless we look at both of these elements (see below for examples).

The ’ncursesw’ C-language library provides basic support for all printing characters (and meta-characters) as well as a useful selection of function-key definitions; however, the way the ’ncursesw’ library handles the code pairs is inconvenient, to say the least. For this reason, the NcDialog API encapsulates all the underlying messiness into the wkeyCode class.

The wkeyCode Class

The wkeyCode class, defined in NCurses.hpp, is the workhorse of character processing. The wkeyCode class has three public data members:

  wchar_t    key ;
  wkeyType   type
  MouseEvent mevent ;

First, let’s look at the ’type’ member. The type is specified by the enumeration list, ’wkeyType’:

  enum wkeyType : short
  {               // == INDICATES ==
     wktPRINT,    // a printing character or metacharacter
     wktFUNKEY,   // a command code (function-key code)
     wktMOUSE,    // a mouse event code
     wktEXTEND,   // a member of the 'extended' command-key group
     wktESCSEQ,   // an untranslated escape sequence
     wktERR       // an invalid code
  } ;

wktPRINT and wktFUNKEY correspond roughly to the designations in the underlying ncurses(w) library.

wktMOUSE indicates that a mouse event has been captured and that the mouse data have been stored in the ’mevent’ data member. For more information on the mouse interface, please see NCurses Mouse Access.

wktEXTEND indicates that the code is one of the extended command-keys defined by the NcDialog API. These command keys are mostly 'ALT+x' key combinations. For instance, if the user presses and holds the ’ALT’ key and then presses the ’A’ key, that combination, 'ALT+A' is a non-printing command key (defined as 'nckA_A').

wktESCSEQ indicates that an unknown sequence of bytes has been received from the underlying keyboard interface. Because the ncurses(w) library has only a limited number of keycodes available, and because the ncurses(w) library must support a very wide variety of modern and legacy keyboards, not all escape sequences can have a keycode assigned to them. As an example, the ncurses(w) library does not translate the following sequence of hexadecimal bytes received from the keyboard. An escape sequence like this is generally meaningless at the application level, and so should be ignored.

  1B 5B 31 7E     // represents numeric keypad 'Home' key

wktERR indicates than the attempt to retrieve keyboard input has failed or that the data received do not represent a valid code.

Testing Key Data

Next, The wchar_t value, ’key’ defines the keycode. Before discussing the values that ’key’ can contain, it is important to understand that a given value of ’key’ can only be properly interpreted within its ’type’ context.

Here are some practical examples of testing the key input:

// define some wkeyCode-class objects
wkeyCode wk, wkesc( nckESC, wktFUNKEY );

// get key input from user
// (note that key type is also the return value)
nc.GetKeyInput ( wk ) ;

// testing for the return of the LeftArrow function key
if ( wk.type == wktFUNKEY && wk.key == nckLEFT )
{
   /* DO STUFF */ 
}

// testing for return of the extended-definition key, ALT+SHIFT+B
else if ( wk.type == wktEXTEND && wk.key == nckAS_B )
{
   /* DO STUFF */
}

// testing for equality with another wkeyCode object
else if ( wk == wkesc )
{
   /* DO STUFF */
}

// You may also test for inequality with another wkeyCode object:
if ( wk != wkesc )
{
   /* DO STUFF */
}

Printing Characters and Metacharacters

A printing character is one which can be written to the display and we can see it. Most human language characters fall into this category.

There are a few character which are known as control codes, the 'CTRL+C' (break) and the ’ENTER’ (RETURN) key are common examples. These characters are not visible, but they control the flow of the output.

However, some languages and character sets, while quite complex and beautiful when written by hand, are not so simple to render electronically. A base character may require one or more additional marks or glyphs in order to be complete. These additional glyphs are not characters in themselves, and so are never printed alone, but only in combination with a base character. These special glyphs are known as metacharacters. The Arabic language is a good example of a language which uses metacharacters.

For additional information on character encoding please
see Multi-language Support.

Defined Constants

While printing characters and metacharacters are well-defined and standardized, function keys and their associated control codes vary from system to system.

The ncurses(w) C-language library defines certain keycodes based on information in the terminal definition database (termcap, terminfo, environment variables and so on). These definitions may refer to a single key, or may refer to a key combination. Because the ncurses(w) library must support a wide variety of systems (many of which no longer exist) many of these keycodes are implemented as macros. However, macros are difficult to work with and tend to be fat and slow when converted to CPU instructions.

For this reason, the NcDialog API, and specifically the NCurses class define a large number of useful control code constants as well as some common character codes.

ASCII Control Codes

The ASCII (American Standard Code for Information Interchange) control codes are represented in various human readable forms ’^A’, ’Ctrl+A’, 0x01 and so on. In the NcDialog API, these control codes are referenced by their named constant values, e.g. ’nckC_A’ means ’NCursesKey Control+A’.

Note that the zero (0, \0, 0x00) character is designated as nckNULLCHAR.

Note that the ’Ctrl+M’ (carriage return) keycode is not used in Linux/UNIX systems. The ’Ctrl+J’ (linefeed) keycode is used instead.

Navigation Keys

The navigation keys, Up, Down, Right, Left, Tab, PageUp, PageDown, Home and End are familiar to most computer users. These keys when used alone or in combination with the ’Shift’, ’Ctrl’ and ’Alt’ (’Meta’) keys move the text cursor and/or the input focus around the window.

Some of these key combinations are not generated by the keyboard itself, some are captured by the system before they reach the terminal window, some are captured by the terminal window itself, and some cannot be handled by the underlying ncurses(w) C-language library. The remainder are available to an application running in a terminal window. The exact list of navigation keys which will be available is system dependent. For instance, this list shows an example of the possible key combinations for the DownArrow key; however, it is likely that some of these key combinations will not be available on your system.

• DownArrow
• Shift+DownArrow
• Ctrl+DownArrow
• Alt+Shift+DownArrow
• Ctrl+Shift+DownArrow
• Alt+Ctrl+DownArrow
• Alt+Ctrl+Shift+DownArrow

The following table shows the navigation-key combinations which are actually seen by an NcDialog application running in a terminal window on typical Wintel hardware.

Numeric Keypad

For keyboards which have built-in numeric keypads or for externally-mounted numeric keypads, some additional navigation keys and other keys may be available. Some of these extra keys will yield the same keycodes as the equivalent key on the main keyboard, so they cannot be individually identified. The keycodes which can be identified as belonging to the numeric keypad are indicated with a ’nckpXXX’ named constant, but within this group, note that many of the key combinations yield the same keycode as the base key, so this table contains some duplicates.

IMPORTANT NOTE: In order to see these keycodes, the ’Numlock’ key must be ON and the ’Shift’ key MUST NOT be pressed.

Function Keys

A ’Function Key’ is any keycode which represents a command rather than a printing character.

The navigation keys described above are a type of function key because they command the cursor to go somewhere. However, there are many other command keys. The most notable of these is the row of 'Fnn' keys found at the top of most keyboards. The number of these keys actually present and the way they are interpreted are system dependent.

PCs, i.e. Wintel hardware generally have either ten or twelve ’Fnn’ keys. Mainframes, minicomputers and high-end workstations often have several more.

Some of these keys, (the ’F01’ equals ’Help’ for instance), have become standard keyboard fuctionality, while the definition of other key combinations is left to the system or to individual applications. As with the navigation keys described above, function keys can be combined with the modifier keys ’Shift’, ’Alt’ ("Meta’) and ’Ctrl’ to provide the user with many ways to quickly accomplish common tasks.

Some of these key combinations are not generated by the keyboard itself, some are captured by the system before they reach the terminal window, some are captured by the terminal window itself, and some cannot be handled by the underlying ncurses(w) C-language library. The remainder are available to an application running in a terminal window. The exact list of function/command keys which will be available to your application is system dependent. The following table describes the Function Key combinations defined directly by the underlying ncurses(w) library OR translated from escape sequenced by the NcDialog API.

The ncurses(w) C-language library can store up to a maximum of sixty-four (64) function keycodes. In practice, however, the library does not use all of this reserved storage. The NcDialog API uses some of the free keycode storage for other command keys, and some slots remain undefined.

Extended Command Codes

Because the ncurses(w) C-language library has limited space for keycode storage, it does not handle most command codes generated using the ’Alt’ (’Meta’) key.

To provide a larger variety of command codes for use in your applications, the NcDialog API defines as many of the 'Alt+n' command codes as is practical. These command codes are not as portable among different hardware platforms as are the base ncurses(w) keycodes; however, for systems that support them (Wintel/PC hardware for instance), these command codes are available for application development. (see NCursesKeyDef.hpp)

A few additional ’Alt+____’ definitions using punctuation characters are also defined.

Line Drawing Characters

Text characters may be used for simple line drawings using lines, corners and intersections. These characters can be quite useful in enhancing the readability of data written to a terminal window.

High-level utility methods which are available for line drawing:
See DrawLine method.
See DrawBox method.

Two development methods are available which display examples of the line drawing characters:
See DisplayLineDrawingSet method.
See DisplayLineDrawingExamples method.

The following is a chart of the basic Unicode line-drawing characters and their constant definitions as defined in NCurses.hpp. For additional Unicode graphic characters, please refer to Unicode Consortium’s Unicode Character Table, starting with codepoint U+2500.

Note that the ncurses(w) library defines macros for line-drawing characters which live in both the ’narrow’ and ’wide’ versions of the so-called ’Alternate Character Set’ which is part of the basic Linux/UNIX terminalcharacter set. Before there was a Unicode Standard, the Alternate Character Set may have seemed like a good idea; however, use of the ACS_xxx and WACS_xxx line-drawing characters in new code is strongly discouraged. Use the Unicode/UTF-8 characters directly. For more information on the Alternate Character Set, please see Color Attributes.

NcWindow Class Overview

The NcWindow meta-layer performs three (3) major functions within the NcDialog API:

1. NcWindow provides direct access to the underlying ’ncursesw’ C-language library.
2. NcWindow is the ancestor class for most NcDialog constructs.
3. NcWindow implements thread safety for the keyboard/mouse input stream and for the text (display) output stream.

Applications should never call NcWindow methods directly, but should call the equivalent NcDialog-class method instead. That’s why the NcWindow-class it is called a ’Metalayer’. The NcWindow-class functionality is discussed ONLY to provide a greater understanding of the API’s underlying structure.

NcWindow Public Methods

What follows is a list of all public methods of the NcWindow class.
Methods are arranged in functional groups.

Some of these methods are passthroughs to the NCurses class; others are directly inherited by the NcDialog class or are redefined in the NcDialog class.

NcWindow Basics

• ~NcWindow ( void );

    Input  : none
    Returns: nothing
  

  Destructor. Erase the window from the display and release its resources back to the system.

  
  
  
• NcWindow ( short lines, short columns,
             short startY, short startX );

    Input  :
       lines   : number of lines in the window
       columns : number of columns in the window
       begin_y : vertical offset from upper left corner of screen
       begin_x : horizontal offset from upper left of screen
    Returns: nothing
  

  Constructor. Creates an NcWindow object. The constructor specifies only the size of the window and its position relative to the upper left corner of the terminal window. All other data members for the NcWindow object are initially set to their default values.

  Window background color, border and other contents must be specified separately after instantiation is complete. It is recommended that all additional configuration be completed before making the window visible for the first time.

  The underlying ’ncurses’ window is not created by the constructor, but is created by the ’OpenWindow()’ method, below.

  
  
  
• short OpenWindow ( void );

    Input  : none
    Returns:
       OK if successfully opened, else ERR
  
        Note that most likely causes of error are:
        a) terminal screen is too small to hold the window
           plus offsets from upper-left corner
        b) insufficient heap memory (unlikely)
  

  Allocate resources for the window based upon the parameters passed to the constructor. Calls a series of functions in the underlying ’ncurses’ C-language library to create the primitive window, and then makes the window visible to the user.

  Note that the ’ncurses’ C-library allows a window to be opened even if it extends beyond the borders of the terminal window; however, the NcWindow class DOES NOT allow that kind of foolishness.

  
  
  
• void WinDimensions ( short& lines, short& columns );

    Input  :
       lines   : (by reference) receives lines (rows) in window
       columns : (by reference) receives vertical columns in window
    Returns: nothing
  

  Returns the window dimensions in lines and columns.

NcWindow Formatting

• void SetInteriorColor ( attr_t cAttr );

    Input  :
       cAttr : color attribute
    Returns: nothing
  

  Set a background color for the interior of the window.
  Does not redraw the window.

  
  
  
• short DrawBorder ( attr_t cAttr, const char* title=NULL,
                     ncLineType style = ncltSINGLE,
                     bool rtlText = false );

    Input  :
       cAttr  : color attribute
       title  : (optional, default==NULL)
                if non-NULL, points to window title string
       style  : (optional, ncltSINGLE by default)
                member of enum ncLineType
       rtlText: (optional, false by default)
                if 'title' != NULL, then:
                if false, draw as LTR text, if true, draw as RTL text
    Returns:
       If no title string is specified:
         OK on success,
         else ERR (window too small, must be at least 2 lines by 2 cols)
       If a title string IS specified:
         returns the X offset at which the title is displayed.
         (this is optionally used to position a hotkey indicator)
  

  Draw an inside border around the window, and optionally a title which is centered in the top line of the window.
  Does not refresh the window.

  
  
  
• short DrawBox ( short startY, short startX,
                  short rows, short cols,
                  attr_t cAttr, const char* title=NULL,
                  ncLineType style=ncltSINGLE, bool rtlText=false );

    Input  :
       startY : y offset for start of line
       startX : x offset for start of line
       rows   : number of rows
       cols   : number of columns
       cAttr  : color attribute
       title  : (optional, default==NULL)
                if non-NULL, points to box title string
       style  : (optional, ncltSINGLE by default)
       rtlText: (optional, false by default)
                if 'title' != NULL, then:
                if false, draw as LTR text, if true, draw as RTL text
    Returns:
       If no title string is specified:
         OK on success,
         else ERR (box would extend beyond parent window)
       If a title string IS specified:
         returns the X offset at which the title is displayed.
  

  Please see DrawBox method in the NcDialog chapter.

  
  
  
• short DrawLine ( const LineDef& ldef );

    Input  :
       lDef (by reference)
            initialized fields
         type   : ncltHORIZ or ncltVERT
         style  : normal, bold, dual-line, or one of the
                  dashed line types
         startY : y offset for start of line
         startX : x offset for start of line
         length : number of lines (vert) or columns (horiz)
         attr   : color attribute
    Returns:
       OK if success, else ERR
  

  Please see DrawLine method in the NcDialog chapter.

NcWindow Display Output

• winPos WriteString ( short startY, short startX,
                       const gString& gStr, attr_t cAttr,
                       bool refresh=false, bool rtl=false );
  
• winPos WriteString ( const winPos& startYX, const char* uStr,
                       attr_t cAttr,
                       bool refresh=false, bool rtl=false );
  
• winPos WriteString ( short startY, short startX,
                       const char* uStr, attr_t cAttr,
                       bool refresh=false, bool rtl=false );
  
• winPos WriteString ( const winPos& startYX, const wchar_t* wStr,
                       attr_t cAttr,
                       bool refresh=false, bool rtl=false );
  
• winPos WriteString ( short startY, short startX,
                       const wchar_t* wStr, attr_t cAttr,
                       bool refresh=false, bool rtl=false );
  
• winPos WriteString ( const winPos& startYX, const gString& gStr,
                       attr_t cAttr,
                       bool refresh=false, bool rtl=false );

  Please see WriteString method in the NcDialog chapter.

  
  
  
• winPos WriteChar ( short startY, short startX, const char* uChar,
                     attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( const winPos& startYX, const char* uChar,
                     attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( short startY, short startX, wchar_t wChar,
                     attr_t cAttr,
                     bool refresh=false, bool rtl=false );
  
• winPos WriteChar ( const winPos& startYX, wchar_t wChar,
                     attr_t cAttr,
                     bool refresh=false, bool rtl=false );

  Please see WriteChar method in the NcDialog chapter.

  
  
  
• winPos WriteParagraph ( short startY, short startX,
                          const gString& gStr,
                          attr_t cAttr,
                          bool refresh=false, bool rtl=false );
  
• winPos WriteParagraph ( const winPos& startYX, const gString& gStr,
                          attr_t cAttr,
                          bool refresh=false, bool rtl=false );

  Please see WriteParagraph method in the NcDialog chapter.

  
  
  
• short ClearWin ( bool clearAll=true, bool refresh=true );

    Input  :
       clearAll: (optional, true by default)
                 if false do not clear window border.
                 else, clear entire window.
       refresh : (optional, true by default)
                  if true, refresh the display
  
    Returns: OK
  

  Erase the contents of the window and optionally refresh the display.

  Note that windows of one line, by definition, have no borders, so clearAll is assumed for one-line windows.

  
  
  
• void RefreshWin ( void );

    Input  : none
  
    Returns: nothing
  

  Refresh the display of window contents.

  Any changes made to the window contents since the last refreh will become visible.

  
  
  
• short ClearLine ( short ypos, bool clearAll = false,
                    short xpos = 1, bool rtl = false ) ;

    Input  : 
       ypos    : line number (zero-based)
       clearAll: (optional, false by default) if 'true', clear entire
                 line, if 'false' do not clear border area
       xpos    : (optional)
                 starting column (zero-based)
                 Note: for LTR, default is one(1)
                       for RTL, default is (columns-2)
                 (ignored if clearAll != false)
       rtl     : (optional, 'false' by default)
                 if 'false', then clear from 'xpos' toward right
                 if 'true',  then clear from 'xpos' toward left
                 (ignored if clearAll != false)
  
    Returns: 
       OK if successful
       ERR if invalid line index
  

  Clear from specified cursor position to end of line. Display is refreshed.

  
  
  
• winPos GetCursor ( void );

    Input  : none
  
    Returns: a winPos class object containing the Y/X cursor position
  

  Get the window’s cursor position.

  
  
  
• short SetCursor ( short ypos, short xpos );
• short SetCursor ( winPos yxpos );

    Input  : 
       ypos : Y offset from upper-left corner (zero-based)
       xpos : X offset from upper-left corner (zero-based)
         OR
       yxpos: Y/X offset from upper-left corner (zero-based)
  
    Returns: 
       OK if successful
       ERR if parameter(s) out of range
  

  Set the window’s cursor position

NcWindow Keyboard Input

The meta-layer keyboard input method and the application-layer mouse interface are implemented in the NcWindow class to provide thread-safe operation. The mouse method group is directly inherited by the NcDialog class.

Please see GetKeyInput method for a description of the application-layer keyboard input method.

Please see Mouse Configuration for full descriptions and notes on configuring mouse input.

• wkeyType GetKeyInput ( wkeyCode& wKey );

    Input  : wKey (by reference, initial values ignored)
             receives the key input data
    Returns: member of enum wkeyType
  

  Get a keycode and keytype from the input stream.
  This includes all supported international character codes as well as captured-and-translated escape sequences representing function keys, cursor keys and other special-purpose key combinations.

  If mouse input has been enabled, mouse events will also be returned in caller’s wkeyCode-class object’s ’mevent’ data member.

  • This method is the thread-safe version of the lower-level keyboard interface in the NCurses class.
  • In addition to the simple filtering of invalid input done by the NCurses-class version of this method, significant filtering of unrequested and/or broken mouse input is performed.
  
  
  
• short meEnableStableMouse ( short dclick = ncmiSTABLE
                              bool swheel = true );

  Please see meEnableStableMouse method.

  
  
• short meEnableMouse ( mmask_t eventTypes,
                        short interval=ncmiDFLT );

  Please see meEnableMouse method.

  
  
• short meDisableMouse ( void );

  Please see meDisableMouse method.

  
  
• bool meMouseEnabled ( void );

  Please see meMouseEnabled method.

  
  
• short meSetEventTypes ( mmask_t eventTypes );

  Please see meSetEventTypes method.

  
  
• short meGetEventTypes ( mmask_t& eventTypes );

  Please see meGetEventTypes method.

  
  
• short meSetClickInterval ( short waitMax, short* oldMax=NULL );

  Please see meSetClickInterval method.

  
  
• short meGetClickInterval ( short& waitMax );

  Please see meGetClickInterval method.

  
  
• short meFlushEventQueue ( void );

  Please see meFlushEventQueue method.

  
  
• short meAutoConvert ( bool enable );

  Please see meAutoConvert method.

  
  
• short meAutoFilter ( bool filter );

  Please see meAutoFilter method.

  
  

NcWindow Data Scrolling

One of the basic methods for viewing and selection of data items is scrolling the items up and down in a window. The following methods implement the meta-layer of data scrolling. For application-layer scrolling, please refer to the NcDialog-class user-interface control objects:

see Scrollbox Controls
see Scrollext Controls
see Dropdown Controls
see Menuwin Controls

Note than an example of scrolling using the NcWindow methods can be found in Test03 of the Dialog1 test application.

• short PaintData ( const char* dataPtr[], short count,
                    short hiliteIndex, attr_t color,
                    bool hilite=true, bool rtlFmt=false );

    Input  :
       dPtr   : pointer to an array of character pointers
       count  : number of data items
       hIndex : index of highlighted data item
       color  : text color attribute
       hilite : (optional, true by default)
                hilight currently indexed item
       rtlFmt : (optional, false by default)
                draw data as RTL (right-to-left) text
  
    Returns:
       index of currently highlighted data item
  

  Write into the window the display data to be scrolled and initialize the tracking variables. See also the ’RepaintData’ method.

  Note that the data item specified by the ’hIndex’ parameter is positioned as near to top of window as possible, even when withHilte==false. This guarentees that the specified item will be displayed when the window is first opened.

  This version of ’PaintData’ is for single-color data only (all data items are displayed in the same color).

  Note: It is assumed that the caller has properly sized the display strings to fit within the window’s width. If not, we may experience unsightly or uneven edges.

  
  
  
• short PaintData ( const char* dataPtr[], const attr_t colorData[],
                    short count, short hiliteIndex, 
                    bool hilite=true, bool rtlFmt=false );

       dPtr   : pointer to an array of character pointers
       cPtr   : pointer to an array of (attr_t) color attributes
       count  : number of data items
       hIndex : index of highlighted data item
       hilite : (optional, true by default)
                hilight currently indexed item
       rtlFmt : (optional, false by default)
                draw data as RTL (right-to-left) text
  
    Returns:
       index of currently highlighted data item
  

  Write into the window the display data to be scrolled and initialize the tracking variables. See also the ’RepaintData’ method.

  Note that the data item specified by the ’hIndex’ parameter is positioned as near to top of window as possible, even when withHilte==false. This guarentees that the specified item will be displayed when the window is first opened.

  This version of ’PaintData’ is for multi-color data (one color per data item).

  Note: It is assumed that the caller has properly sized the display strings to fit within the window’s width. If not, we may experience unsightly or uneven edges.

  
  
  
• short PaintMenuData ( const char* textData[], short count,
                        short hiliteIndex, attr_t color, 
                        bool hilite=true, bool rtlFmt=false );

    Input  :
       dPtr   : pointer to an array of character pointers
       count  : number of data items
       hIndex : index of highlighted data item
       color  : text color attribute
       hilite : (optional, true by default)
                hilight currently indexed item
       rtlFmt : (optional, false by default)
                draw data as RTL (right-to-left) text
  
    Returns:
       index of currently highlighted data item
  

  Write menu data including strings with hotkey indicators into a window to be scrolled, and initialize the scroll-tracking variables.

  This version of ’PaintMenuData’ is for single-color data only (all data items are displayed in the same color).

  Important Note: We do not make a local copy of the caller’s text strings because menu text can change dynamically based on action in the application code. Therefore, we use the actual application data each time this method is called.

  Note: This method scans the display strings for the hotkey character indicator ’^’ (caret) and displays the character that follows it with the Underline attribute.

  Note: It is assumed that the caller has properly sized the display strings to fit within the window’s width. If not, we may experience unsightly or uneven edges.

  
  
  
• short PaintMenuData ( const char* textData[],
                        attr_t colorData[], short count,
                        short hiliteIndex,
                        bool hilite=true, bool rtlFmt=false );

    Input  :
       dPtr   : pointer to an array of character pointers
       cPtr   : pointer to an array of color attributes
       count  : number of data items
       hIndex : index of highlighted data item
       hilite : (optional, true by default)
                hilight currently indexed item
       rtlFmt : (optional, false by default)
                draw data as RTL (right-to-left) text
  
    Returns:
       index of currently highlighted data item
  

  Write menu data including strings with hotkey indicators into a window to be scrolled, and initialize the scroll-tracking variables.

  This version of ’PaintMenuData’ is for multi-color data (one color per data item).

  Important Note: We do not make a local copy of the caller’s text strings because menu text can change dynamically based on action in the application code. Therefore, we use the actual application data each time this method is called.

  Note: This method scans the display strings for the hotkey character indicator ’^’ (caret) and displays the character that follows it with the Underline attribute.

  Note: It is assumed that the caller has properly sized the display strings to fit within the window’s width. If not, we may experience unsightly or uneven edges.

  
  
  
• void RepaintData ( bool hilite=true );

    Input  :
       hilite : (optional, true by default)
                hilight currently indexed item
  
    Returns: nothing
  

  Redraw data controlled by the scrollData structure previously initialized through a call to ’PaintData’.

  Although ’RepaintData’ appears to do the same thing as the ’PaintData’ methods above, this method is much faster because the display data and tracking variables do not need to be range-checked and recalculated. It is assumed that all data members of the control structure are valid.

  
  
  
• short EraseData ( void );

    Input  : none
  
    Returns: OK
  

  Erase currently displayed data and reset the tracking variables.

  Note that the display and color data belong to the application’s memory space; there is no memory allocated for it within the NcWindow class.

  
  
  
• short ScrollData ( wchar_t scrollKey );

    Input  :
       scrollKey : key input (non-scroll-keys are ignored)
                   nckUP     = scroll up by one line
                   nckDOWN   = scroll down by one line
                   nckPGUP   = scroll up by one page
                   nckPGDOWN = scroll down by one page
                   nckHOME   = scroll to top of data
                   nckEND    = scroll to bottom of data
  
    Returns:
       index of currently highlighted data item
  

  Scroll the display data by one scrolling unit.

  If the target item is already visible in the window, then simply move the highligh to it. If the target item is not visible, then first re-index the list to bring the target item into the viewable area before positioning the highlight.

  
  
  
• short ScrollMenuData ( wchar_t scrollKey );

    Input  :
       scrollKey : key input (non-scroll-keys are ignored)
  
    Returns:
       index of currently highlighted data item
       (if highlight moved, window is refreshed before return)
  

  Scroll through the items in a menu. Menu data may or may not have hot-key associations, indicated by the caret (’^’) before the character. If a caret is present in the data, the data are displayed with the character following the caret underlined to indicate the hot-key. See also PaintMenuData().

  Note that unlike regular scrolling display lists, menu data are all visible in the menu window. For this reason, only the highlight is moved. Scrolling the data elements up and down is not required.

  Note also that unlike regular scrolling display lists, if nckUP is pressed while highlight is on first item, highlight will wrap to the last item; and similarly, if nckDOWN is pressed while highlight is on last item, highlight will wrap to the first item.

  
  
  
• short ScrollView ( wchar_t scrollKey );

    Input  :
       scrollKey : key input (non-scroll-keys are ignored)
  
    Returns:
       index of data item at top of window
  

  Scroll the disp display data by one scrolling unit.

  This method performs the same task as the ScrollData method above, EXCEPT that there is no visible highlight to indicate the current line.

  Because there is no visible highlight, the return value is the index of the item currently visible at the top of the window.

  
  
  
• short GetHilightIndex ( void );

    Input  : none
  
    Returns:
       index of currently highlighted data item
  
  

  Returns the index of the currently-highlighted item in the scrolling-data array.

  
  
  
• bool IsScrollKey ( wkeyCode wk );

    Input  :
       wk  : wkeyCode-class object containing 
             keycode and key classification
  
    Returns:
       returns true if a scroll key, else false
  

  Tests caller’s key datum to determine whether it is one of the scrolling keys, nckUP, nckDOWN, nckLEFT, nckRIGHT, nckHOME, nckEND, nckPGUP, nckPGDOWN.

  
  
  
• void HilightItem ( bool show, bool refresh=false );

    Input  :
       show   : 'true' to add hilight, 'false' to remove hilight
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns: nothing
  

  Hilight or remove hilight from the display line referenced by the ’hIndex’ data member, i.e. the logically-highlighted item.

  Removing the highlight (un-hilighting) the data means drawing the data using the base color attribute for that line.

  Highlighting the data means TOGGLING the Reverse video (ncrATTR) bit of the base color attribute and then drawing the data. If the base color data for the string does not include the ncrATTR bit, then the data are drawn with ncrATTR SET. If the base color data for the string does include the ncrATTR bit, then the data are drawn with ncrATTR RESET.

  
  
  
• short Track2Top ( bool refresh=false );

    Input  :
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns:
       index of the logically-highlighted item (i.e. ZERO)
  
  

  Move the logical highlight to the first item in window, and optionally update the display.

  If display ’refresh’ not specified, then call the ’RepaintData’ method to refresh the display and make the changes visible.

  
  
  
• short Track2Bottom ( bool refresh=false );

    Input  :
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns:
       index of the logically-highlighted item
  

  Move the logical highlight to the last item in window, and optionally update the display.

  If display ’refresh’ not specified, then call the ’RepaintData’ method to refresh the display and make the changes visible.

  
  
  
• short Track2Next ( bool refresh=false );

    Input  :
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns:
       index of the logically-highlighted item
  

  Move the logical highlight to the next (lower) item in window, and optionally update the display.

  If display ’refresh’ not specified, then call the ’RepaintData’ method to refresh the display and make the changes visible.

  
  
  
• short Track2Previous ( bool refresh=false );

    Input  :
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns:
       index of the logically-highlighted item
  

  Move the logical highlight to the previous (higher) item in window, and optionally update the display.

  If display ’refresh’ not specified, then call the ’RepaintData’ method to refresh the display and make the changes visible.

  
  
  
• short Track2Item ( short iIndex, bool refresh=false );

    Input  :
       iIndex : index of target item
       refresh: (optional, false by default)
                if 'true', repaint the data and refresh the display
                           (highlight will be visible)
                if 'false', then display is not updated,
                           (i.e. the changes are not yet visible)
  
    Returns:
       index of the logically-highlighted item
         If iIndex out-of-range, then index of currently-highlighted
         item is returned.
  

  Move the logical highlight to the specified item in window, and optionally update the display.

  If display ’refresh’ not specified, then call the ’RepaintData’ method to refresh the display and make the changes visible.

NcWindow Passthroughs

Pass-through methods to the NCurses class. These methods are fully described in the indicated chapter on the NCurses Engine. Please note however, that the NcWindow passthroughs are the thread-safe versions of the low-level methods.

• wkeyType GetKeyInput ( wkeyCode& wKey );
• wkeyType KeyPeek ( wkeyCode& wKey );
• short UngetKeyInput ( wkeyCode& wKey );
• short FlushKeyInputStream ( void );
  (see NCurses Keyboard Input)
  
  
• ncCurVis GetCursorState ( void );
• short SetCursorState ( ncCurVis state );
• short RestoreCursorState ( void );
  (see NCurses Display Output)
  
  
• void ScreenDimensions ( short& scrLines, short& scrColumns );
• ncKeyProc GetKeyProcState ( void );
• short SetKeyProcState ( ncKeyProc procState );
• short GetKeyDelay ( void );
• short SetKeyDelay ( short delay );
  (see NCurses Configuration)
  
  
• void Hibernate ( void );
• void Wake ( void );
• const char* Get_NCurses_Version ( void );
• const char* Get_nclibrary_Version ( void );
  (see NCurses Utility Methods)

NcWindow Utility Methods

• const char* Get_NcWindow_Version ( void );

    Input  : none
    Returns: a const pointer to the class-version string
  

  Returns a pointer to NcWindowVersion, the NcWindow class version number.

  
  
  
• void DebugMsg ( const char* msg, short startY = -1,
                  short startX=1, bool pause=false );

    Input  :
       msg    : pointer to null-terminated message string
       startY : Y cursor start position
                (optional, default == -1, write to last line of window
       startX : X cursor start position
                (optional, default == 1, write to 2nd column of window
       pause  : (optional, default==false)
    Returns: nothing
  

  Write a message to the current window and refresh the window.
  This method has some special properties that the WriteString() method does not.

  • The application’s cursor position is saved and then restored after the message is written to avoid interferring with the application flow.
  • The target line is cleared before the message is written.
  • Color attribute for the message is the window default color, but with ’Standout’ attribute added.
  • The method optionally waits for user to press a key.

NcWindow Hotkey Selection

A ’hotkey’ is a special key combination which is used as a shortcut access to a particular application function or information item. For instance, the 'F01' function key is traditionally used to invoke the application’s 'Help' information.

The NcWindow class implements hotkeys for window objects and for individual data items in menus. The NcDialog derived class builds on this basic hotkey functionality.

A complete discussion of using hotkeys may be found in the NcDialog chapter on hotkey definition and uses.
See Select Control via Hotkey.

NcWindow Thread Handling

The NcDialog API thread-safety mechanism is implemented in the NcWindow-class meta-layer. This thread-safe operation carries through all classes derived from the NcWindow class. For a full discussion of multithreaded access to the NcDialog API, please see Thread Safety.

NcDialog Class Overview

In previous chapters, we have examined the interface to the underlying ’ncursesw’ C-language library which implements the low-level curses interface for GNU/Linux systems.

In this chapter, we will describe the application layer interface. This is where the action is, and the information presented here provides nearly everything you need to create sophisticated, fast and bulletproof applications in a terminal environment.

We outline all the public methods of the NcDialog class, how they are used and when they are used. There is always a learning curve when working with a new tool, but we hope that once you have read this chapter, you will have no trouble easily and quickly building sophisticated applications without the kind of frustrating and time-consuming research which would be needed for some gigantic GUI API.

If you find that any of the concepts presented here are confusing or difficult to understand, please see Operational Overview for a review of basic concepts.

Eye Candy for Techies

We will present several screen captures for various dialogs and the controls they contain. We apologize that the Texinfo documentation system info-format document cannot render them in color, so some detail may be lost; but note that the HTML-format version of this document shows screen captures in eight(8) colors.

The screen capture below is the dialog we create in the chapter,
see Your First Application

Note that the screen captures in this document use a simplified, but essentially accurate
color attribute map to compress the captured data. For details, see CSS for screenshots.

NcDialog Public Methods

Dialog Window Methods

This chapter describes the NcDialog methods that affect the NcDialog-class object (dialog window) as a whole.

• virtual ~NcDialog ();

    Input  : none
  
    Returns: nothing
  

  Destructor for an NcDialog object.
  Release all resources held by the dialog window and its associated control objects. Erase dialog from the display.

  
  
  
• NcDialog ( InitNcDialog& dDef );

    Input  :
       dDef: a fully initialized InitNcDialog class object (by reference)
             See definition of InitNcDialog class for details.
  
    Returns:
       constructors implicitly return a pointer to the object
  

  Constructor for an NcDialog object.
  Creates an instance of the NcDialog class, initializes all public and private data members, and then calls the constructors for all specified dialog control objects.

  Important Note: Every effort is made to maintain the integrity of the dialog’s initialization parameters for future reference by the application-level code. However, certain critical errors in the initialization parameters, if found, will be automatically and silently corrected. The most critial is that the first dialog control in the array of control definitions must be set as ’active’, that is, it must be able to receive input focus.

  For a complete description of initialization data passed to the constructor, please see InitNcDialog class.

  For a complete description of how to define dialog control objects, please see InitCtrl class.

  
  
  
• short OpenWindow ( void );

    Input  : none
  
    Returns:
       OK if successful
       else ERR 
         Note that most likely causes of error are:
         1. terminal screen too small to hold the window plus
            offsets from upper-left corner
         2. insufficient heap memory (unlikely)
  

  Allocate additional resources for a previously-instantiatiated dialog and draw the dialog and all its control objects in the terminal window.

  
  
  
• void RefreshWin ( void );

    Input  : none
  
    Returns: nothing
  

  Refresh display of dialog window and all its controls.
  Any changes made to the dialog window or any of its control since the previous refresh will become visible.

  If the dialog had previously been marked as ’obscured’, re-draw the dialog using the saved image and then discard the saved image data. In the unlikey case that changes were made to the dialog window after the backup image was created, those changes will be lost.
  (See HideWin method.)

  
  
  
• short ClearWin ( bool clearAll = false );

    Input  :
       clearAll: (optional, false by default)
                 if 'false' clear interior, leaving border
                 if 'true' clear entire window including border
  
    Returns: OK
  

  Erase (overwrite with spaces) contents of the window using the window’s background color. Does not refresh display.

  IMPORTANT NOTE: Please use extreme caution with this method!
  Please call the ’ClearWin’ method ONLY if there are no user-interface controls defined, or if only Pushbutton controls have been defined.

  Calling ’ClearWin’ when controls have been defined may have unexpected results, specifically, all control labels will disappear, and if specified, the border will also disappear. The controls themselves are self-contained, so calling ’RefreshWin’ will redraw the controls, but really, the dialog will have become useless to the user, so again: use caution!.

  Please see ClearLine method for a more controlled form of erasing data from the window.

  
  
  
• short HideWin ( attr_t blankingColor=ZERO );

    Input  :
       blankingColor: (optional) specifies a background color to be
                      used for erasing the dialog window
                      default: use parent window's background color
   
    Returns: OK
  

  Hide the dialog window from view, that is, save its display data, then erase it from the screen.

  • If display data have not already been saved by a previous call to SetDialogObscured(), data will be saved before erase.
  • If application has already saved the display data through a previous call to SetDialogObscured(), just erase the dialog’s display data.
  • A call to RefreshWin() will make window visible again and release the saved data.
  
  
  
• short SetDialogObscured ( void );

    Input  : none
  
    Returns: 
       OK if successful
       ERR if window data has already been saved
  

  Capture the dialog window display data and set the winObscured flag.

  The application should call this method in anticipation of the dialog being wholly or partially obscured by another object. Similar to HideWin() except that the dialog is not erased.

  Note that you must call this method BEFORE the dialog is actually obscured.

  
  
  
• short MoveWin ( winPos& ulYX, bool relative=false );

    Input  : 
       ulYX    : Y/X offset of new position
       relative: (optional, false by default)
                 if 'true', coordinates are interpreted as an offset
                            from current dialog position.
                 if 'false', coordinates are interpreded as an offset
                            from upper left of terminal window.
  
    Returns: 
       OK if successful
          On successful return, the ulYX parameter has been updated
          with the previous coordinates of the dialog window.
       ERR if:
         1. window data has already been saved (see SetDialogObscured()).
         2. if the new position would place all or part of the dialog
            outside the terminal window's display area
         3. memory-allocation error
  

  Move the dialog window from its current position in the terminal window to the specified position.

  Note that this is not simply a matter of erasing the display data at the current position and displaying it somewhere else. Significant behind-the-scenes adjustments are made which cascade through all layers of code abstraction.

  See the test application Dialog1, Test08 for an example which uses this method.

  
  
  
• winPos GetDialogPosition ( void );

    Input  : none
  
    Returns: Y/X window position
  

  Report the dialog window’s current position as an offset from the upper left corner of the terminal window. Please see winPos class for a description of the data returned.

  While the position of the dialog in the terminal window is generally fixed, some applications will find it convenient to allow the user to move the dialog window within the terminal window (see MoveWin method above). ’GetDialogPosition’ allow the application to determine the dialog’s current position.

  
  
  
• void GetDialogDimensions ( short& dLines, short& dColumns );

    Input  :
       dLines : (by reference)
                 receives the number of display lines in dialog
       dCols  : (by reference)
                 received the number of display columns in dialog
  
    Returns: nothing
  

  Report the dialog window’s dimensions as the number of display lines and display columns.

  
  
  
• winPos SetDialogTitle ( const char* dTitle,
                          attr_t cAttr=attrDFLT );
  
• winPos SetDialogTitle ( const wchar_t* dTitle,
                          attr_t cAttr=attrDFLT );
  
• winPos SetDialogTitle ( gString& dTitle,
                          attr_t cAttr=attrDFLT );

    Input  : 
       dTitle : title string
                maximum character columns <= dialog width minus 4
                (truncated if necessary to fit available display area)
                title may be in UTF-8, wchar_t or gString format
       cAttr  : (optional, default: dialog's border color)
                alternate color attribute for title text
  
    Returns:
       Y/X position for start of centered title
       (This return value is seldom useful, but see   )
       (the title of our FileMangler utility where the)
       (title and the menu bar share the same space.  )
  

  Create a centered title in line ZERO of the dialog window.

  If a title for the dialog window was not specified during instantiation (see InitNcDialog class), or if you wish to change the existing title, then a title may be specified for the dialog. It is customary (but not enforced) that one or two leading and trailing spaces be included in your title string for visual appeal.

  Note that if either the title or the dialog window require an odd number of display columns, then the centering may be off by one. (It’s algebra, not magic.)

  Note: While an existing title may be replaced using this method, try not to confuse the user. The most common replacement title would be to draw the same title text, but in a different color.

  Example:
  
  Line zero of a dialog which has no title:

  ╔════════════════════════════════════════════════════════╗

  dp->SetDialogTitle ( "   My Killer App   ", nc.reR ) ;

  Line zero of the dialog after inserting title:

  ╔══════════════════╣ My Killer App ╠═══════════════════╗
  
  
  
  
• short EstablishCallback ( CUPTR methodname );

    Input  : 
       methodname: valid pointer to caller's method of the correct type
                   OR NULL pointer to disable existing callback
  
    Returns: OK
  

  Establish (or disable) a callback method that allows the mainline code to dynamically update the controls within the dialog window.

  The external method handles situations that the dialog code cannot. For example:

  • secondary validation of text data in a text box
  • manual update of non-active controls i.e. display-only controls that user can view, but cannot access.
  • Transfer of data to or from the system clipboard,
    but see Clipboard Interface.
  
  
  Example: . . . NcDialog* dp = new NcDialog ( dInit ); // Instantiate dialog window if ( (dp->OpenWindow()) == OK ) // Open dialog window { dp->RefreshWin () ; // Make everything visible dp->EstablishCallback ( &cbMethod ); . . . } //* This is the callback method * short cbMethod ( const short currIndex, const wkeyCode wkey, bool firstTime ) { if ( firstTime != false ) { // do stuff here... } // do stuff here... }

  See the Dialog1 test application for examples of how to establish and utilize callback methods. The callback for Test08 (T8_ControlUpdate method) is particularly exciting.

  
  

  The macro CUPTR defines the callback method reference used during the call to EstablishCallback. This macro is located in NcDialog.hpp.

  typedef short (*CUPTR)( const short currentIndex, 
                          const wkeyCode wkey, bool firstTime ) ;
  

  Programmer’s Note: Since C++11 it has been possible to specify a member method as a callback method; however, we have resisted using the std::function and std::bind functions, or the std::invoke (since C++17) functionality because it would break existing code. If we can find a way to do it transparently we will implement it in a future release.

  
  

  Notes on using a callback method:

  • Dialog must be instantiated (see NcDialog constructor) AND opened (see OpenWindow method) before calling the EstablishCallback method since the callback will be performed for the first time immediately after it is established.
  • The EstablishCallback method calls the specified method once with the parameter firstTime==true, to perform any required initialization. (wkey parameter will be meaningless for first call) Subsequently, the NcDialog class always calls with firstTime==false.
  • It is sometimes useful for the application to call the callback method directly, but you will need to fake the parameters carefully.
  • IMPORTANT NOTE: If caller passes an invalid method pointer to EstablishCallback, the application will immediately crash. So there!

Dialog Control Objects

A dialog control object is a logical device used for collecting input from the user and displaying information to the user. Several different types of controls are available, so you can present and collect information in the way that is most convenient for that type of information.

• Using Dialog Controls
• Pushbutton Controls
• Radiobutton Controls
• Textbox Controls
• Billboard Controls
• Scrollbox Controls
• Scrollext Controls
• Dropdown Controls
• Menuwin Controls
• Spinner Controls
• Slider Controls
• Select Control via Hotkey

//* If there is file data to display 'Just Do It' (tm Nike) *
char*       blkPtr ;
ssetData    sData( NULL, NULL, tlFiles, ZERO, false ) ;
if ( tlFiles > ZERO )
{
   //* Space for display strings (there is extra space for each string) *
   blkPtr = new char[dAlloc * dialogCols] ;
   //* Space for pointers to strings *
   sData.dispText  = new const char*[dAlloc] ;
   //* Space for color attributes *
   sData.dispColor = new attr_t[dAlloc] ;

   //* Create display strings *
   this->bcbStandardView ( blkPtr, sData ) ;

   //* Send the data to the scrolling control *
   dp->SetScrollextText ( scrollSE, sData ) ;
}  // if(tlFiles>ZERO)

//* Make everything visible *
dp->RefreshWin () ;