Next: Introduction [Contents][Index]
The AnsiCmd library provides a simple, organized mechanism
for controlling the setup of many terminal window functions
and display options using ANSI escape sequences and basic
terminal configuration utilities.
Next: Invoking, Previous: AnsiCmd Class Link Library, Up: (top) [Contents][Index]
The AnsiCmd class builds to a small, special purpose link library which may be used to configure color attributes for the terminal window foreground and background; text attributes such as bold, italic, and underlined; as well as cursor positioning and text erasure using ANSI escape sequences and ASCII control codes.
In addition, the AnsiCmd library can configure the input stream, "stdin" for operations such as input echo options, non-blocking read and capture of the "break" signal (CTRL+C).
The AnsiCmd class library is bundled with a test application, EarthPoints, (epts), which exercises the full functionality of the library. EarthPoints was born as an experiment in how global-positioning systems calcuate distances between points on the planet. It began as a pure command-line application to test the math behind the distance calculations; however, your author is a simple creature, and he was easily distracted by the possibility of using ANSI escape sequences to add color to the output. (Geeks-R-Us :-)
This distraction quickly became a project in itself, and the full list of ECMA-48, ANSI X3.64 escape sequences is now supported by the AnsiCmd library.
ANSI - American National Standards Institute
(ECMA-48, ISO/IEC-6429, FIPS 86, ANSI X3.64, JIS X 0211)
https://en.wikipedia.org/wiki/American_National_Standards_Institute
https://www.ecma-international.org/publications-and-standards/standards/ecma-48/
ASCII - American Standard Code for Information Exchange.
(ISO-IR-006, ANSI_X3.4-1968, ANSI_X3.4-1986, ISO_646.irv:1991, ISO646-US,
IBM367, cp367)
https://en.wikipedia.org/wiki/ASCII
Next: AnsiCmd Library, Previous: Introduction, Up: AnsiCmd Class Link Library [Contents][Index]
There are three (3) groups of command-line options for invoking the application (invocation menu below). Each option group is independent of the others (with some exceptions). The 'help' and 'version' options override all other specified options. When one of the testing options is specified, it overrides any request for application-level (GPS) data.
To interactively invoke the application’s help menu, at the command-line type:
epts --help
epts -h
or redirect the help menu through the “less” utility:
epts --helpless
epts -hl
Please See Invoking - EarthPoints for more information.
Next: Invoking - AnsiCmd Tests, Up: Invoking [Contents][Index]
When invoking the EarthPoint application (epts), terminal setup options are
specified through the “--term” command-line option:
epts --term=SETUP_OPTIONS
Options may be specified in any order and in any combination.
Multiple options may be concatenated, seperated by commas (','):
If the argument string contains whitespace, enclose the entire argument
string in single- or double-quotes.
OPTION DESCRIPTION W option stream Width C option Color attributes A option Ansi compliant B option input Buffering L option Locale name P option Panic button S option cursor Style
The term “Stream Width” refers to the character width for input and output streams for the application. Typically, the character width is either 8-bits (char) or 32-bits (wchar_t).
For console applications, the I/O stream width is established either directly by declaring the width or by locking in the character width with the first data read from, or written to the the I/O streams. Once locked in, the stream width cannot be changed without closing and re-opening the stream(s), which is not as straightforward as it sounds, and is therefore discouraged.
w - Use the wide (wcin/wcout) input/output streams.
This is the default, and is strongly recommended.
n - Use the legacy narrow (cin/cout) input/output streams.
The narrow I/O streams are not recommended for modern applications,
but may be used for testing the interface.
Example:
epts --term=W:w # set Wide stream width
To set this option directly, call the AnsiCmd method: acSetStreamWidth.
Specify the text foreground, and optionally the background color attribute(s). The foreground color argument is required, and the background argument is optional, and if not specified, the terminal default background will be used.
Within a console application, it is often useful, to use contrasting colors to draw the user’s attention to important information. For applications which include the AnsiCmd library, these color attributes may be specified as a command line option.
The -C option is used to specify one of the basic eight(8) colors (or default) for foreground and background.
Examples:
epts --term=C:r # set Red foreground with Default background
epts --term=C:cb # set Cyan foreground with Blue background
epts --term=C:dg # set Default foreground with Green background
To set this option directly, call the AnsiCmd method: acSetFgBg.
The most popular terminal emulator software, Gnometerm, Konsole and XTerm all support the core set of ANSI escape sequences. However, some terminal software may not understand some of the basic commands such as those which reset (disable) certain individual settings.
For terminals with this limited support, the AnsiCmd library functions can substitute the full reset command for the unsupported individual reset commands. While the full reset is slower and less convenient for the application programmer, it provides a way to produce a reliable application interface.
For example, the standard way to reset the Bold attribute is with the
aesBOLD_OFF sequence:
acSetMod ( aesBOLD_OFF );
If this command or similar commands is not supported by the terminal, then
the global attribute reset can be called:
acSetMod ( aesRESET );
This substitution is done automatically if the internal non-compliance flag
is set.
The level of ANSI compliance is specified by:
y - Yes, the host terminal supports the common ANSI escape sequences.
This is the default, and should be correct in most cases.
n - No, the terminal is unable to handle some of the necessary sequences.
Use the reliable reset when disabling an attribute.
To set this option directly, call the AnsiCmd method: acFullReset.
Specify the buffering options for the input stream (stdin).
By default, keyboard input at the terminal prompt is stored in the stream
buffer until the user presses the Enter key; however, application control
of the keyboard input stream is, in the author’s view, critical to the success
of the application.
(Our opinions are plentiful and provided free-of-charge.)
If your applications would benefit from having full control of keyboard input, then the -B option is used to specify the way keyboard input is captured, filtered and presented to the application.
To set this option directly, call the AnsiCmd method: acBufferedInput.
Specify the “locale” to be used within the application.
A locale is the set of rules used to interpret the way text and numeric data are processed and presented. A few examples of locale-dependent data are, currency values, telephone numbers, timestamps and measurements.
Two command-line options are available:
It is very likely that the terminal environment in which your console
application runs specifies the locale via one or more environment variables.
At the command line type:
echo $LANG
To list the types of formatting handled by the current locale, at the
command line type:
locale
To list the UTF-8 compliant locales supported by your system, at the
command line type:
locale -a | grep -i 'UTF'
This should yield a list of filenames such as
en_US.UTF-8, zh_CN.utf8, es_AR.utf8
Technical Note: Except for Windoze(tm), the civilized world uses UTF-8 character encoding exclusively. Be sure that any locale specified for use in your application is based on UTF-8 encoding.
Technical Note: If a console application does not explicitly specify a locale, the so-called “C-locale” is used. This is not actually a locale at all but the complete lack of a locale—resulting in a complete lack of coherent data formatting.
The Break Signal, otherwise know as the Panic Button or Control+C is the primary method of killing a console application which has locked up or has gone off into the weeds.
By default, the terminal receives the break signal and immediately kills the application, leaving your data in an indeterminate state.
This is fine if you don’t care about your data, but if you actually don’t care about your data, please step away from the keyboard — and pursue a career in marketing. Otherwise, your application may benefit one of these options.
Please see Capturing the Break Signal for additional information.
To set this option directly, call the AnsiCmd method: acCaptureBreakSignal.
Specify the shape and animation (blinking or steady) of the visible cursor.
To set this option directly, call the AnsiCmd method: acSetCursorStyle. Note that this method may also be used to set cursor as invisible.
Technical Note:
The blinking-cursor options are impacted by the terminal software’s blink timeout value. For Gnome, the default timeout is ten seconds, after which the cursor will stop blinking and become steady state. To adjust this timeout value under Gnome, use either the 'dconf' editor or the 'gsettings' utility.
Get the current timeout value:
gsettings get org.gnome.desktop.interface cursor-blink-timeout
Get the range of valid values for this option:
gsettings range org.gnome.desktop.interface cursor-blink-timeout
Set a new timeout value in seconds:
gsettings set org.gnome.desktop.interface cursor-blink-timeout 25
Other desktop schemes will have a similar mechanism for adjusting the cursor blink timeout value.
Next: Invoking - EarthPoints, Previous: Invoking - Terminal Setup, Up: Invoking [Contents][Index]
Tests for the AnsiCmd library are specified as arguments to the
"–ansi" command-line option.
epts --ansi=TEST_OPTION
The specific test within a group of related tests is specified by from one
to four characters as detailed in this chapter. The first character indicates
the test group. For instance, the letter 'C' designates the group
of color-attribute tests. If a test group is invoked without indicating a
specific test, then the menu of available tests in that group will be
displayed and the application will exit.
epts --ansi=C will display the color test menu:
Color Attribute Testing Options:
-----------------------------------------------
'f' Four-bit Fgnd/Bkgnd color attributes.
'b' Background color attribute options.
't' Table lookup, 8-bit color attributes.
'r' R/G/B color-attribute matrix (6x6x6).
'g' Greyscale color attributes.
'a' Aixterm Fg/Bg extensions (non-standard).
'd' Decode tracking data for attribute mods.
Similarly, if a test group and a test are specified, but the test requires
an argument or arguments, then a menu of available arguments for that
test will be displayed and the application will exit.
epts --ansi=Cr will display the RGB color test arguments:
RGB Test Options:
---------------------------------------------------
'r' Red : Display full range of red colors.
'g' Green: Display full range of green colors.
'b' Blue : Display full range of blue colors.
'y' greY : Display full range of greyscale colors.
'w' Web : Display "web-safe" colors.
A few test require two(2) arguments, for example:
epts --ansi=Tec Terminal group, Echo test, Cursor keys
If a test and its argument(s) are fully specified, then optionally, the
next character indicates the text color attribute to be used for outputting
the results of the test. The available color attributes are:
'k' blacK 'r' Red
'g' Green 'n' browN
'b' Blue 'm' Magenta
'c' Cyan 'y' greY
If not specified, the terminal default color is used.
Note: The color-attribute tests will ignore this argument.
Examples:
epts --ansi=Eb — Perform 'E'rasure test
with 'b'lue text.
epts --ansi=Ac — Perform 'A'SCII code test
with 'c'yan text.
epts --ansi=Tig — Perform 'T'erminal 'i'nput
test with 'g'reen text.
OPTION DESCRIPTION test C Color tests test P Positioning tests test E Erasure tests test A Ascii control code tests test F Font switch test test I Ideograph test test T Terminal setup tests test W Window tests test S Sandbox
Options for testing the functionality of the AnsiCmd-class library.
For options which require arguments, the option must be immediately followed by the EQUAL sign (’=’) which must be immediately followed by its argument. If the argument string contains space characters, enclose it in quotation marks.
Please see Development and Testing or study the AnsiCmdTest.cpp source file for more information about how the individual tests are constructed.
The majority of escape sequences definined in the ECMA-48 (ANSI) standard are related to setting foreground and background color attributes. These definitions reflect the evolution of color support on hardware terminals and within terminal emulators from 3-bit (8 colors) to 4-bit (16 colors) through today’s so-called true-color (usually 24-bit) systems.
Each of the color palettes supported by the standard is exercised by one or more of the color-attribute tests listed here.
One group of the escape sequence defined by the standard provides various ways to set the cursor position. Some of these sequences set an “absolute” (terminal-relative) position. Others define a move relative to the current cursor position. All the supported variations are used during this test.
In the early days of computing, terminals were extremely slow. For this reason, several innovative ways of erasing an area of the display were implemented to increase the speed of display updates. Some of these include erasing part of a line, a whole line, and either the top half or bottom half of the display. It is even possible to “erase” the data which has already been scrolled out of the window. (It was a whole thing....don’t ask :-)
ASCII control codes (00h - 1Fh) were an important part of systems which used serial communication (e.g. Teletype machines) for user interaction. On modern systems, most of these codes are swallowed by the terminal software and never become available to the console application. A few however are vital to operation. The most common are null(00h), bell(07h), backspace(08h), horizontal-tab(09h), linefeed i.e. newline(0Ah), vertical-tab(0Bh), form-feed(0Ch), carriage-return(0Dh), and of course Escape(1Bh). Others may be used in specialized circumstances.
This test transmits each of the ASCII control codes to the terminal and reports the terminal’s response (if any).
A “font” is a set of glyphs (visible pictures) which are used to represent the “codepoints” of a character set. The ECMA-48 (ANSI) standard defines a method for selecting any of ten(10) fonts to be used for display text.
The "Primary Font" is specified in the aeSeq enumerated type as:
aesPRIMARY_FONT (decimal 10)
The "Alternate Fonts" are specified by the aeSeq value of:
aesALTERNATE_FONT
with a numeric argument between 1 and 9 (inclusive).
These are translated to ANSI command codes 11 through 19, respectively.
Please see acSetFont for more information.
Testing thusfar indicates that setting alternate fonts is not supported by the terminal emulators used during development. The font is set in the terminal’s Preferences/Settings and appears to be unavailable to console applications; however, this tests exercises the font commands, and further research will be conducted.
An “ideogram” is technically a symbol representing a concept or and idea, or what today we would call a “meme”. Street signs without words, mathematical-operator symbols or a photo of a cat hanging onto a branch with one paw could be considered as ideograms.
The ideograms defined by the ECMA-48 (ANSI) standard appear to have
been indended as line-drawing tools or text decorations; however, they
seem to have been abandoned before they were completed. As such,
they are unlikely to be supported by modern terminals; however, this test
issues the associated escape sequences to see what happens i.e. nothing:
aesIDEO_UNDER // ideogram underlined
aesIDEO_UDOUBLE // ideogram double-underlined
aesIDEO_OVER // ideogram overlined
aesIDEO_ODOUBLE // ideogram double-overlined
aesIDEO_STRESS // ideogram stress marking
aesIDEO_OFF // all ideogram attributes off
This test exercises the various terminal configuration options and the internal tracking data related to those options.
The window group consists of API-level algorithms which are implemented at a higher abstraction level compared to the basic ANSI escape sequences.
At an intermediate level are the line-drawing and box objects which simply draw lines and rectangles to the display. These objects are defined by the acDrawLine method and the AC_Box Class, respectively.
At the higher level of abstraction is the ACWin Class which defines a relatively primitive dialog window which optionally contains a user-defined array of text fields (skForm Class), with more sophisticated input and output methods which may be used to display information or to interact with the user.
The “Sandbox” is a common name among nerdy types to indicate a work area in which experimental operations may be performed without compromising the platform as a whole.
Invoking the Sandbox executes user-defined functionality created for
ad hoc testing. Note that code created in the Sandbox may be affected
by the AnsiCmd class initialization as specified by arguments to the
“--term” command-line option.
See Invoking - Terminal Setup for more information.
Invoking the Sandbox test may include one or two optional arguments which are passed as parameters to the Sandbox method. Each of these optional arguments consists of a single alpha-numeric character, (case insensitive).
Examples:
epts --ansi=S # invoke the Sandbox with no arguments
epts --ansi=St # invoke the Sandbox with one argument
epts --ansi=S4c # invoke the Sandbox with two arguments
The specified arguments will be displayed in the top row of the window as
shown, and these parameters may be referenced in the usual way.
(A question mark will be displayed for unspecified argument(s)).
Previous: Invoking - AnsiCmd Tests, Up: Invoking [Contents][Index]
OPTION DESCRIPTION coa option Specify the first set of global coordinates. cob option Specify the second set of global coordinates. file option Specify a file containing global coordinate pairs. formula option Specify the formula to be used to calculate distance. convert option Convert coordinate-pair format to alternate formats color option Specify color attribute for reporting results. verbose option Display verbose output for results of calculation. window option Display the report within a window object. dump option Display and verify contents of a file of GPS records. version option Reports EarthPoints version number and copyright info. help option Display all EarthPoints and AnsiCmd options helpless option Same as '--help' option except pipe through 'less'
Options may be specified in any order.
For each option that requires one or more arguments, the option name and its argument(s) may be separated by either '=' or ' ' (space). Note that if the argument contains whitespace, then the entire argument sequence must be enclosed within single-quotes or double-quotes. This prevents the terminal’s shell program from “interpreting” (trashing) your argument formatting.
Examples: --coa=Miami:25.775163:80.208615 --coa 'Miami: 25.775163 : 80.208615' --cob="Buenos Aires: -34 36 12.0 : -58.381666667" --file='Europen Capitol Cities - 2007.txt'
Note: As a convenience, the long-form options may be uniquely specified in a truncated form. At least six (6) characters of the option must be specified. This consists of the two 'dash' characters, plus the first four characters of the option name. Example: The “--verbose” option may be uniquely specified as “--verb”.
A GPS coordinate record has the following format:
[LABEL:] LATITUDE : LONGITUDE
where:
Whitespace between fields of the record is optional, and will be ignored.
Whitespace within a coordinate field delimits the tokens within that field:
Examples: '25 46.50978' _or_ '25 46 30.5868'
The label field is simple text, and may contain spaces if desired.
(Note the trailing colon ':').
Example: "Miami, Florida, USA:"
Latitude and longitude pairs may be expressed in either degrees or radians.
Within a latitude:longitude pair, each value may take one of the following
formats.
Examples: --coa='Miami: 25.775163 : -80.208615' --cob='Buenos Aires: -34.603333333 : -58.381666667'
Note that positive degree values indicate North latitude or East longitude, while negative values indicate South latitude or West longitude."
Examples: --coa='Miami: 0.449861R : 4,883281R' --cob='Buenos Aires: 5.679243R : 5.264233R'
Note that the trailing ’R’ character of each value indicates radians. Note also that an arc in radians is expressed as a positive value only.
Examples: --coa='Miami: 25 46.50978 : -80 57.948611'" --cob='Buenos Aires: -34 36.20 : -58 22.90'
Examples: --coa='Miami: 25 46 30.5868 : -80 57 56.91666' --cob='Buenos Aires: -34 36 12 : -58 22 54.0'
Specify the record containing the first pair of GPS coordinates.
Formatting of the record is described in the GPS Coordinate Records section, above.
Two sets of GPS coordinates are needed to calculate arc length. See the "cob" option, below.
Please See verbose option, below for sample output formatting.
Specify the record containing the second pair of GPS coordinates.
Formatting of the record is described in the GPS Coordinate Records section, above.
Two sets of GPS coordinates are needed to calculate arc length. See the "coa" option, above.
Please See verbose option, below for sample output formatting.
Specify a file containing a database of GPS coordinate pairs and identify two specific records from that database. These records represent the endpoints of the arc distance to be calculated.
The target file is a plain text file containing any number of GPS records. The individual records follow the same format as command-line record specification described at the beginnig of this chapter. An example database file is shown below. (Not that you would ever do anything so foolish, but the filename may not contain the colon ’:’ character.)
Each target record is specified by its label, either the full label text, or a substring which uniquely identifies the beginning of the record label. The scan is case-insensitive. Specifying the database filename and record labels takes the form:
--file='FILENAME:LABEL_A:LABEL_B'The following record specifications are equivalent.
epts --file='GPS_Records.txt:Chicago, IL:Miami, FL'
epts --file='GPS_Records.txt:chi:Mia'Alternatively, the records may be specified using the index of of the record(s) within the database using the special token: “LABn” where 'n' is a zero-based index.
Examples:
epts --file='GPS_Records.txt:Chicago, IL:LAB14'
epts --file='GPS_Records.txt:LAB2:Miami, FL'
epts --file='GPS_Records.txt:LAB2:LAB16'Example GPS Record Database
Each record lives on a seperate line. Note the range of available coordinate formats. Blank lines and lines beginning with the hash character (’#’), are interpreted as comments and will be ignored.
# --------------------------------------------------- # The Not Fully United Kingdom. # --------------------------------------------------- # INDEX # ----- # London, England 0 London : 51 30 26.0 : -0 7 39.0 # Edinburgh, Scotland 1 Edinburgh : 55.953056 : -3.188889 # Cardiff, Wales 2 Cardiff : 0.898525R : 3.086106R # Belfast, Northern Ireland 3 Belfast : 54.596521 : -5.930578Three GPS database files are included with the AnsiCmd package:
US_Capitols.txt, UK_GPS.txt and testpoints.txt.
Select the formula to be used for calculation of the arc distance between the two specified GPS coordinates.
(Three(3) characters are sufficient to uniquely identify the argument.)Available formulae:
lambert The Lambert formula calculates the arc on an ellipsoid. haversine The Haversine formula calculates the arc on a sphere. all Displays the calculations for all supported formulae. Examples: epts --coa='36.1:-14.3' --cob='37.7:-12.4' --form=lambert (default) epts --coa='36.1:-14.3' --cob='37.7:-12.4' --form=haversine epts --coa='36.1:-14.3' --cob='37.7:-12.4' --form=allAdditional formulae may be implemented in a future release.
Convert one(1) latitude or longitude value from the given format to the alternate supported formats and display the results.
The 'convert' option takes one argument of the form:
--convert=GPS_COORDINATE_VALUEThis option is useful primarily for debugging the input-parsing routines; however, it may also be useful for experimenting with the various GPS coordinate value formats.
Example coordinate values and the report generated:
epts --convert='-80 57 56.91666' Converted Value: dec:-80.965810 decimal degrees (degrees+minutes+seconds) deg:-80.000000 degrees component min: 57.000000 minutes component sec: 56.916660 seconds component rad: 1.728473 radians fmt: vfSec source format identifier (enum valFmt) epts --convert=4.2579R Converted Value: dec:-63.959700 deg:-63.000000 min: 57.000000 sec: 34.918520 rad: 4.257900 fmt: vfRad
Specify the foreground and background color attributes for display of the output. The terminal window’s color attributes are used by default.
If the --window option is used, then the window’s border attributes may also be specified. (Border attributes, if specified, are ignored for TTY output.)
The '--color' option may be used to specify alternate attributes. The format of the arguments takes the form:
--color=text_fgnd:text_bkgnd[:border_fgnd:border_bkgnd]Each color is specified as one of the following:
'black' 'blue' 'red' 'magenta' 'green' 'cyan' 'brown' 'grey' 'dflt' use terminal default attribute (The first four characters of the name uniquely identify the color.) Examples: epts --color=blue:grey // blue text on grey background epts --color=green:dflt // green text on default background epts --color=dflt:blue // default text color on blue background // blue text, grey bkgnd, cyan border fgnd, black border bkgnd epts --color=blue:grey:cyan:black // default text fgnd:bkgnd, magenta border fgnd, blue border bkgnd epts --color=dflt:dflt:magenta:blue
The standard arc-distance report displays the coordinates in both degrees and radians, and then displays the arc-distance in both kilometers and miles, calculated using the specified formula.
The verbose arc-distance report displays the same information, except that the coordinate values in degrees are broken down into their component parts: Degrees, Minutes and Seconds.
Standard Report:
Miami, FL Buenos Aires, AR ====================== ====================== LATITUDE LONGITUDE LATITUDE LONGITUDE ---------- ---------- ---------- ---------- 0.44986 1.74169 Radians 2.53765 2.12264 25.77516 -80.20862 Degrees -34.60333 -58.38167Distance: 12905.069560 km (8018.838378 mi)
Verbose Report:
Miami, FL Buenos Aires, AR ====================== ====================== LATITUDE LONGITUDE LATITUDE LONGITUDE ---------- ---------- ---------- ---------- 0.44986 1.74169 Radians 2.53765 2.12264 25.77516 -80.20862 Degrees -34.60333 -58.38167 25 -80 Deg(int) -34 -58 46 12 Minutes 36 22 31 31 Seconds 12 54Distance: 12905.069560 km (8018.838378 mi)
By default, the arc-distance report is displayed in the terminal window using common TTY (Teletype) style output. This output is formatted using basic ANSI escape sequences.
Optionally, the arc-distance report may be formatted within an ACWin-class window object positioned within the terminal window. The ACWin class is derived from the base AnsiCmd class and implements more advanced ANSI formatting. It is designed to resemble an 'ncurses' dialog window. Please See ACWin Class for more information.
By default, the dialog window is positioned with the origin (upper-left corner) at row one(1), column four(4) of the terminal window. However, any position within the terminal window may be specified using parameters of the form: 'row:column'.
The row and column are 1-based offsets from the upper-left corner of the terminal window. See cursor offsets for a discussion of 1-based versus 0-based terminal offsets.
Additionally, specifying a zero (0) value for either parameter indicates that the dialog is to be centered in that dimension. See examples below.
If the specified position would place any part of the dialog beyond the boundaries of the terminal window, then the position will be automatically adjusted to ensure that the entire dialog is visible.
Examples:
epts --window // no position specified, use default 1:4
epts --window=2:1 // positioned at row 2, column 1
epts --window=12:0 // positioned at row 12, centered horizontally
epts --window=0:5 // centered vertically, and at column 5
epts --window=0:0 // centered both vertically and horizontally
In the following example, the row specified is beyond the number of rows in the terminal window, so the vertical offset will be automagically adjusted such that the lower edge of the dialog is on the bottom row of the terminal window:
epts --window=99:0 // auto-adjusted row, and centered horizontally
┌─┤ EarthPoints v:0.0.03 (c) 2022-2023 The Software Samurai ├─┐ │ Miami, FL Buenos Aires, AR │ │ ====================== ====================== │ │ LATITUDE LONGITUDE LATITUDE LONGITUDE │ │ ---------- ---------- ---------- ---------- │ │ 0.44986 1.74169 Radians 2.53765 2.12264 │ │ 25.77516 -80.20862 Degrees -34.60333 -58.38167 │ │ Distance: 12905.069560 km (8018.838378 mi) │ │ │ │ Press Any Key To Exit... │ └──────────────────────────────────────────────────────────────┘Please visit the author’s website to download the NcDialog API, and for a discussion of full-featured dialog windows based on the ncurses library. See By the Same Author for details.
Display and verify the formatting of GPS coordinate records contained in the specified file.
A database of GPS coordinate records is a plain text file with a series of records in the form:
Phoenix, AZ : 33 26 53.15 : -112 5 49.54
consisting of three(3) fields, seperated by colons (’:’).
Label : Latitude : LongitudeFormatting of the record is described in the GPS Coordinate Records section, above.
When constructing a database of GPS coordinate records, the syntax of the records should be verified.
The syntax of each record in the database is verified using the "--dump" option.Example:
epts --dump='US Capitols.txt'The following is the output for the scan of the 'testpoints.txt' file included in this package.
EarthPoints (epts) v:0.0.03 Copyright(c) 2022-2023 The Software Samurai ======================================================================== Validate contents of GPS record file: 'testpoints.txt' ------------------------------------------------------ 00) :25 46 30.5868 : -80.208615 (OK) 01) Miami, FL : 25 46 30.5868 : -80.208615 (OK) 02) Buenos Aires, AR : -34 36 12.0:-58 22.90 (OK) 03) Indianapolis, IN : 39.768611 : -86.158056 (OK) 04) Lafayette, IN : 40.417222 : -86.878611 (OK) 05) San Francisco, CA : 37.7775 : -122.416389 (OK) End-Of-FileIf a syntax error is found, it will be indicated by a status of “(?)”.
For example, this record is missing the madatory field delimiter ':' between the Label and Latitude fields.
01) Miami, FL 25 46 30.5868 : -80.208615 (?)
Command-line Help. Display a brief summary of command-line usage and options. (overrides everything on command line except '--version')
EXAMPLES: epts --help epts -h
Display command-line help. Same as the '--help' option above except that the help menu will be piped through the 'less' utility.
EXAMPLES: epts --helpless epts -hl
Display the EarthPoints version number and copyright information.
(overrides everything else on the command line)To also report the AnsiCmd-class version number, append an 'a' to the argument.
EXAMPLES: epts --version epts --versionA
Next: ACWin Class, Previous: Invoking, Up: AnsiCmd Class Link Library [Contents][Index]
Next: ANSI Escape Sequences, Up: AnsiCmd Library [Contents][Index]
For those who are new to the terminal (emulator) environment, or for those who are interested in the technical details of terminal configuration, this chapter provides an overview of the challenges the author faced during development of this project, and our responses to those challenges.
A common saying in Linux is that “Everything is a file.” While it is true in general that most things are acessed as if they were files, many of the underlying targets are not actually files on the storage media. This is nowhere more apparent than with the input and output data streams of the terminal emulator. Generically, these are known as Standard Input(stdin), Standard Output(stdout) and Standard Error(stderr).
Within the AnsiCmd library, these are referred to by their so-called file handles which are named by the 'TermStream' enumerated type:
These streams are not actual files, but the terminal’s VIRTUAL
configuration files. Therefore, practically speaking, when modifying
terminal settings, it doesn’t matter whether the stdIn, stdOut or stdErr
stream is referenced because they are not actual file descriptors. Instead,
they reference the underlying terminal-attributes structure.
For more information, see Terminal Configuration.
Next: Terminal Configuration, Previous: Introductory Notes, Up: AnsiCmd Library [Contents][Index]
ANSI (American National Standards Institute) escape sequences are simply a well-defined set of byte sequences that may be used to communicate with the host terminal. They are hopelessly old-fashioned, slow, unreliable, difficut to use and all-around relics from the mid-20th century. That being said, they are also widely supported and a lot of fun to play with.
ANSI escape sequences include functionality for cursor positioning, erasing blocks of text, setting color attributes and text modifiers such as bold, italic etc., and all other attributes defined by the ECMA-48, ANSI X3.64 standard. See also ISO/IEC 6429, FIPS 86, ISO/IEC 2022, JIS X 0211.
Wikipedia:
https://en.wikipedia.org/wiki/ANSI_escape_code
Within the AnsiCmd library, the individual ANSI escape sequences are referenced by the “enum aeSeq” enumerated type.
aeSeq (ANSI Escape Sequence) is located in the AnsiCmdDef.hpp header file and includes all the ANSI escape sequences defined by the ECMA-48, ISO/IEC-6429 standard.
Note that each member begins with “aes” to indicate that it belongs specifically to this enumerated type. The short example below should give the basic idea of how aeSeq is constructed.
enum aeSeq : short { //** Text Modification Options. ** aesRESET = 0, // reset all attributes aesBOLD, // bold (increase intensity) aesFAINT, // faint/dim (decrease intensity) aesITALIC, // italic (or inverse) . . . //** Foreground Color Attributes (3-bit and 4-bit color selection) ** aesFG_BLACK, // set foreground color to black (i==24) aesFG_RED, // set foreground color to red aesFG_GREEN, // set foreground color to green . . . //** Background Color Attributes (3-bit and 4-bit color selection) ** aesBG_BLACK, // set background color to black (i==41) aesBG_RED, // set background color to red aesBG_GREEN, // set background color to green . . . //** Indexed Color Attribute Options (8-bit color and greyscale) ** aesFG_INDEX, // set foreground color by lookup table index (0-255) aesBG_INDEX, // set background color by lookup table index (0-255) //** Red/Green/Blue Color Attribute Options (24-bit color) ** aesFG_RGB, // set foreground color by r/g/b register number aesBG_RGB, // set background color by r/g/b register number //* Cursor-positioning Options * aesCUR_HOME, // set cursor at 1,1 aesCUR_ABSPOS, // set (absolute) cursor at specified row;column position aesCUR_ROWSUP, // move cursor upward by specified number of rows . . . //* Text Erasure Options * aesERASE_BOW, // erase from cursor to bottom of window aesERASE_TOW, // erase from cursor to top of window aesERASE_WIN, // erase entire window ('clear') . . . //* Alternate Font group * aesPRIMARY_FONT, // primary font (font 0) aesALTERNATE_FONT, // alternate fonts (font 1 through font 9) //* ASCII Control Codes. * aesBELL, // '\a' terminal "bell" (beep, ping, etc.) aesBKSP, // '\b' backspace aesHTAB, // '\t' horizontal tab . . . //* Ideogram (logogram) group of options * aesIDEO_UNDER, // ideogram underlined aesIDEO_UDOUBLE, // ideogram double-underlined aesIDEO_OVER, // ideogram overlined . . . //** Aixterm codes are not part of the ** //** ANSI standard, but may be supported. ** aesAIXFGb_BLACK, // set foreground color to bright black (grey) aesAIXFGb_RED, // set foreground color to bright red aesAIXFGb_GREEN, // set foreground color to bright green . . . aesCOUNT // number of items in enumerated type list } ; // enum aeSeq
The members of aeSeq index the corresponding byte sequences which are
private data located in the AnsiCmd.cpp source module.
static const wchar_t *ansiSeq[aesCOUNT];
A majority of the element of this array are constant byte sequences; however, the sequences which require parameters are defined as formatting templates as shown in these examples.
Constant byte sequence:
L"\x1B[22;31m" // aesFG_RED
Formatting template:
L"\x1B[38;5;%hhum" // aesFG_INDEX
Note that these sequences are defined as wide character strings because as explained elsewhere (Terminal Configuration), 8-bit character streams are so very 1970s.
ANSI escape sequences should not be used in multi-threaded applications due to timing issues and resource conflicts. For multi-threaded applications, the author recommends our NcDialog API, which is a fully thread-safe ncurses-based library for creating formatted-text console applications.
One practical effect of avoiding multi-threading is in the area of library functions which handle timing and delays.
In C++, the accepted way to delay the action is to use the ’chrono’ class to define the delay, and the ’sleep_for’ method to execute it. However, ANSI escape sequences are inherently incompatible with a multi-threaded environment. For this reason, the AnsiCmd class uses the C-language nanosleep() function. This function is technically sophisticated, but clunky in implementation; so please refer to our iplementation of nanosleep(): nsleep() for details. (see nsleep)
Next: AnsiCmd Class Methods, Previous: ANSI Escape Sequences, Up: AnsiCmd Library [Contents][Index]
Initial terminal configuration is specified by passing an initialized
TermConfig object to the AnsiCmd constructor.
See TermConfig Class.
Subsequent modifications to the terminal environment are specified by calling
the associated AnsiCmd-class method(s).
See AnsiCmd Class Methods.
The actual configuration commands are issued by the TermSet object,
which is a private member of the AnsiCmd class as described below.
See TermSet Class.
Initialization of the TermConfig object may be done directly by the
application when invoking the AnsiCmd constructor:
AnsiCmd constructor,
or may be performed by the user through command-line options:
Invoking - Terminal Setup.
The options provided by the user are validated and stored in the data
members of the TermConfig object.
Note: In practical terms, the selection of the target stream is not important because changes made to one stream are reflected in all streams. Internally, 'stdIn' is used when not specified otherwise.
For those not familiar with the purpose of the 'locale' specification, the locale selected controls how characters are encoded, formatting of numbers, timestamps and currency, interpretation of punctuation, comparisons of text strings and other text formatting decisions. By default, applications start in the so-called “C-locale” which is not really a locale, but a lack of locale which interprets everything in terms of ASCII and English, rendering the application basically useless. For this reason, it is strongly recommended that all application set the locale for the language, character set and text conventions in use by the target system.
Characters received through 'stdin' will be echoed (displayed) in the terminal window according to the specified member of enum EchoOpt.
When system buffering of input is active, the application has no direct
control over input echo, so this option will be ignored. However, when
input buffering is disabled (see the 'bufferInput' variable,
below), the specified echo option will be used:
The keycodes in each special-key group may be adjusted, as we receive more feedback from users about how they uses these options.
Please see Soft Echo Options below for more information.
See Capturing the Break Signal, below for more information.
The break signal is generated by the user pressing the Control+C key combination. By default, the break signal is captured by the terminal which then sends the kill signal to the application running within the terminal window. It is often useful, however, to redirect the break signal to application control. The AnsiCmd library can perform this redirection in either of two ways.
While the first option always invokes the AnsiCmd library’s default handler, the 'acCaptureBreakSignal' call can specify either the default handler or an alternate handler provided by the application.
The 'acCaptureBreakSignal' method can also be used to return control to the terminal’s signal handler.
The mechanics of transferring control of the break signal to the application
are straightforward, but non-trivial. It is accomplished by
“registering” a signal-handler function with the system using the
C-library function:
'signal( int SIGNUM, sighandler_t ACTION )'.
This function is defined in the 'signal.h' header file.
The SIGNUM parameter in this case is the macro 'SIGINT' (the interrupt signal).
The ACTION parameter is the address (name) of the function to which the break
signal will be directed.
The terminal’s signal handler is defined by the macro 'SIG_DFL', while the application’s handler may be specified by the name of any (non-member) function in the application which is configured to process the signal.
The non-member function in the AnsiCmd library is cryptically named
'BreakSignal_Handler'. The system call is then:
signal ( SIGINT, BreakSignal_Handler );
Because we want to provide for potential user interaction when the break
signal is received, we perform the slightly dangerous operation of allowing
the non-member function to call a private AnsiCmd-class member method:
breaksignalReceived ( int sigNum );
This is where the action takes place.
The type of operation to perform has been specified during handler setup, and is a member of enum CCH_Type (Control_C_Handler Type).
“Soft Echo” options define a range of ways in which keyboard input can be captured and filtered before it is echoed (written) to the terminal window.
The primary method for selecting the the soft-echo option is to specify it during a call to the acBufferedInput method which disables input buffering and optionally specifys the character-echo option and whether the input stream uses a blocking or non-blocking read.
The soft-echo option may also be specified as a command-line option.
See the 'echoOption' member in the discussion of the
TermConfig Class, above.
If the echo option is termEcho, then the terminal decides what input is echoed to the display. If the echo option is noEcho, then keyboard input is not written to the display.
Specifying one of the soft-echo options disables automatic echo of keyboard input to the display, and then sorts the incomming keycodes into two main groups: graphing (printing) characters and non-printing control codes.
Graphing (printing) characters are written to the display in the usual way, but control codes are captured, and either converted to one of the “special” keys or discarded according to the selected soft-echo option.
See the next section for more information on the “ special” keycodes.
Decoding the “Special” Keys
The “special” keycodes consist of certain keycodes which are presented to a console application in the form of escape sequences. Many keyboard keys are encoded in this way: the Function Keys, the Cursor Positioning keys, the Backspace/Delete/Insert keys, and most of the keycodes generated in combination with the so-called conditioning keys: Shift, Control, Alt.
For a (nearly) complete list of keystrokes that generate escape sequences and the sequences they generate, please download the author’s NcDialog API package and study the source files NCursesKeyDef.hpp and NCursesKeyDef_auto.hpp.
For the AnsiCmd library, only a small subset of these escape sequences are captured and decoded. These include:
Note: Encoding of Backspace and Delete keys are specified in terminal settings.
Key Function Esc Seq (hex) Key Name Glyph/Keycode Up Arrow 1B 5B 41 wcsUARROW ↑ 2091h Down Arrow 1B 5B 42 wcsDARROW ↓ 2093h Right Arrow 1B 5B 43 wcsRARROW → 2192h Left Arrow 1B 5B 44 wcsLARROW ← 2190h Home Key 1B 5B 48 wcsHOME ↖ 2196h End Key 1B 5B 46 wcsEND ↘ 2198h Page Up 1B 5B 35 7E wcsPGUP ↗ 2197h Page Down 1B 5B 36 7E wcsPGDN ↙ 2199h Tab 09 wcsTAB ↱ 211Bh Shift+Tab 1B 5B 5A wcsSTAB ↲ 21B2h Backspace 7F wcsBKSP ↰ 21B0h Delete 1B 5B 33 7E wcsDELETE ↳ 21B3h Insert 1B 5B 32 7E wcsINSERT ↥ 21A5h Alt+Enter 1B 0A wcsAENTER ↧ 21A7h The Copy/Cut/Paste keys (Ctrl+C, Ctrl+X, Ctrl+V) will be integrated into this group for a future release. Until then, the terminal equivalents, in concert with the system mouse, may be used: Ctrl+Shift+C, CtrL+Shift+V.
Taken together, these keycodes comprise all the standard keycodes used to edit text within an individual field or on a form consisting of multiple fields.
Please see skForm Class for a description of how these keycodes are interpreted within a form or a field.
The TermSet class encapsulates the low-level access to terminal-configuration options. The AnsiCmd class methods calls the private TermSet object ('tset' member) for configuration options such as input buffering, input-echo options, cursor style, blocking vs. non-blocking input, flushing the I/O buffers and capture of the break signal (CTRL+C).
All methods and data members of the TermSet class are private, and are accessed only by the AnsiCmd (or ACWin) class. This ensures that there is only one point of access to the terminal configuration in order to avoid unfortunate configuration conflicts.
Although the functionality discussed here is not directly available to the application, it is interesting and educational to understand what is going on under the floorboards, so-to-speak.
The application may request a copy of the current terminal settings to
verify that the terminal is configured as desired. The data consist of
the bitfields defined in the C-language termios structure.
See acGetTermInfo for details.
This data set is used to return the terminal settings to their original values when the application exits, i.e when the AnsiCmd/TermSet destructors are called.
Please see AnsiCmd constructor for additional information.
As noted elsewhere (see Introductory Notes), this has little practical value as a file handle because it references a virtual file which manages all three streams as a unit.
Please See S option for specifying the cursor style as a command line option, and the TermConfig Class for a detailed description of cursor styles.
Please See Capturing the Break Signal for a discussion of the break-signal handlers built into the AnsiCmd library.
Please See Soft Echo Options and TermConfig Class for a discussion of input-echo options.
Please See B option for specifying the input buffering option as a command line option, and the TermConfig Class for a description of input buffering. See also, the acBufferedInput method.
The term “blocking read” refers to whether the execution thread should go to sleep while waiting for keyboard input.
By default, blocking read is active, meaning that when the application requests keyboard input from the user (see acRead), the execution thread goes into a hibernation state until the terminal signals that input is available in the buffer.
When blocking read is disabled, a request for user input will return the first keycode in the buffer, or will immediately return a "WEOF" (zero) if no data are available in the input buffer.
The AnsiCmd library uses non-blocking read primarily for receiving escape
sequences from the terminal program and for flushing the input buffer.
The acBlockingInput method makes non-blocking input available
in case the application needs similar functionality.
NOTE: This functionality can be dangerous, so use it wisely.
Please See Capturing the Break Signal, and also the acCaptureBreakSignal method for a discussion of the break-signal handlers.
For additional information on terminal configuration please refer to the documentation for the C-library functions: tcgetattr, fcntl, signal and the termios structure and related macro definitions defined in termios.h and unistd.h
Previous: Terminal Configuration, Up: AnsiCmd Library [Contents][Index]
Next: Configuration Methods, Up: AnsiCmd Class Methods [Contents][Index]
The following is a list of AnsiCmd public methods, grouped by function.
Most public methods begin with the letters “ac” (Ansi Command).
The basic methods use ANSI escape sequences directly. Some of these methods use C-library function calls to perform terminal configuration.
A few methods are implemented at a higher abstraction level (API level). These are referred to in the documentation as Application-Program-Interface API methods. These methods typically do not use the ANSI escape sequences directly, but instead call a sequence of low-level (primitive) methods to provide a less cluttered interface between the application and the AnsiCmd library.
See also the ACWin Class in the next chapter which provides a more
sophisticated user interface whose functionality lies somewhere between the
raw ANSI escape sequences and the dialog-oriented interface of the
author’s NcDialog API.
Please see By the Same Author for more information.
Method Name | Description |
---|---|
──── Configuration ────── | ───────────────────────────────────────── |
AnsiCmd constructor | Constructors |
AnsiCmd destructor | Destructor |
acGetTermSize | Calculate size of terminal window |
acGetTermDimensions | Get a copy of stored terminal size |
acGetTermInfo | Get current terminal configuration |
acSetLocale | Specify a non-default locale |
acGetLocale | Get current locale setting |
acSetStreamWidth | Lock in wide or narrow I/O streams |
acBufferedInput | Configure input-stream buffering |
acEchoOption | Echo option (unbuffered input only) |
acBlockingInput | Input blocking (unbuffered input only) |
acCaptureBreakSignal | Enable/disable capture of Ctrl+C |
acRestoreTermInfo | Set terminal configuration to defaults |
──── Color Attributes ─── | ───────────────────────────────────────── |
acSetFg | Set text foreground (3-bit, 4-bit) |
acSetBg | Set text background (3-bit, 4-bit) |
acSetFgBg | Set text fgnd and bkgnd (3-bit, 4-bit) |
acSet8bitFg | Set text foreground (8-bit color) |
acSet8bitBg | Set text background (8-bit color) |
acSetRgbFg | Set text foreground (r/g/b color) |
acSetRgbBg | Set text background (r/g/b color) |
acSetWebFg | Set text foreground (web-safe r/g/b) |
acSetWebBg | Set text background (web-safe r/g/b) |
acSetGreyscaleFg | Set text foreground (greyscale) |
acSetGreyscaleBg | Set text background (greyscale) |
acSetAixFg | Set text foreground (AIX Intel) |
acSetAixBg | Set text background (AIX Intel) |
acReset | Reset attributes and tracking data |
──── Text Modifiers ───── | ───────────────────────────────────────── |
acSetMod | Set or reset a text modifier |
acResetMods | Reset all text modifiers |
acFullReset | Reset all colors and text modifiers |
─── Cursor Position ───── | ───────────────────────────────────────── |
acSetCursor | Position the visible cursor |
acGetCursor | Get current cursor position |
acSetCursorStyle | Specify cursor shape |
───── Input Methods ───── | ───────────────────────────────────────── |
acRead | Read from stdin |
acFlushIn | Flush the input stream (stdin) |
──── Output Methods ───── | ───────────────────────────────────────── |
acWrite | Write formatted data to stdout |
ttyWrite | Write unformatted data (TTY style) |
acFlushOut | Flush the output stream (stdout) |
acFlushStreams | Flush both input and output streams |
──── Text Erase ───────── | ───────────────────────────────────────── |
acEraseArea | Erase specified area of terminal window |
──── Misc Methods ─────── | ───────────────────────────────────────── |
acBeep | Make some noise |
nsleep | Put thread to sleep |
acVersion | Get AnsiCmd class version number |
acSetFont | Seldom supported alternate font |
acSetIdeogram | Seldom supported line drawing |
──── API Methods ──────── | ───────────────────────────────────────── |
acSetAttributes | Set bit-field color and text-mod data |
acComposeAttributes | Encode bit-field color and text-mods |
acGetAttributes | Get decoded bit-field color/text-mods |
acClearScreen | Erase all data from terminal window |
acClearArea | Erase specified area of terminal window |
acDrawLine | Draw a horizontal or vertical line |
acDrawBox | Draw a rectangle in the terminal window |
acEraseBox | Erase a rectangular area of terminal |
acBoxDraw | Display an AC_Box object in terminal |
acBoxErase | Erase an AC_Box object from terminal |
acBoxClear | Clear the interior of an AC_Box object |
── Development Support ── | ───────────────────────────────────────── |
ansiTest | Manage AnsiCmd library testing |
getDataMembers | Get a copy of internal data members |
Next: Color Attributes, Previous: Table of Public Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : none Returns: implicitly returns a pointer to object
Default Constructor: Terminal configuration parameters are set to default
values.
Please See TermConfig Class for details on default values.
The usefulness of the default constructor is miniscule, and possibly full of surprises for the programmer and the user alike. It is strongly recommended that the initialization constructor (see below) be used for all non-trivial applications.
Input : tCfg : (by reference) terminal configuration parameters Returns: implicitly returns a pointer to object
Initialization Constructor: Terminal configuration parameters are passed in the TermConfig object.
Configuration options can be established directly by the application startup code, or if preferred, can be specified by the user as command-line options See Invoking.
Please See TermConfig Class for details on parameter values passed to the constructor.
Programmer’s Note: The AnsiCmd class should be instantiated before any data is sent to the terminal’s output stream. This is because the first output may override any subsequent output-stream width designation for the current session. Note that the wide (32-bit character) stream is strongly recommended for all modern applications. The narrow stream is outdated due to its close ties to ASCII text (and to 1970).
Input : none Returns: nothing
Destructor. Return all resources to the system before exit.
The destructor is invoked either by deleting the object:
AnsiCmd *ansicmdPtr = new AnsiCmd( termConfig );
delete ansicmdPtr;
OR when the object goes out-of-scope.
Input : none Returns: current terminal dimensions in a WinSize object
Returns the terminal dimensions in both character cells and pixels.
The WinSize structure is defined in /usr/include/bits/ioctl-types.h, and is one of the many system configuration parameters handled by the C-library ioctl function.
struct winsize { unsigned short int ws_row; unsigned short int ws_col; unsigned short int ws_xpixel; unsigned short int ws_ypixel; };
Note on terminal dimensions: Although the environment may contain the terminal dimensions when the application was invoked, this is a _copy_ of the environment, not the active environment, and therefore will not reflect user changes to the terminal window size while the application is active.
The $LINES and $COLUMNS are available from the environment at the command line (“echo $LINES” and “echo $COLUMNS”), but are not exported to programs running in the terminal window.
Note also that the pixel dimensions will probably be returned as zeros because under Wayland, the terminal program likely doesn’t know the screen resolution.
Input : rows : (by reference) receives number of terminal rows cols : (by reference) receives number of terminal columns Returns: 'true' if terminal dimensions are known 'false' if system call to get terminal dimensions failed
Reports the dimensions of the terminal window in rows and columns.
Input : tStream : one of stdIn, stdOut, stdErr tios : (by reference) receives settings orig : (optional, 'false' by default) 'false': the current terminal settings are returned 'true' : the original terminal settings are returned Returns: 'true' if settings captured 'false' if system error
Get a copy of the current terminal I/O stream configuration (or the original settings captured on application start-up).
This is a pass-through to the private TermSet method.
(This method is primarily for development and debugging.)
Input : (optional, null pointer by default) If specified, pointer to name of UTF-8 compliant locale filename. If null pointer (or empty string: "\0"), set locale from terminal environment. Returns: 'true' Currently, we do not verify that 'localeName' is a valid UTF-8 compliant locale filename.
Set the "locale" for the application.
By default, the application locale is taken from terminal environment.
Type: echo $LANG at the command prompt to get the terminal’s locale. If desired, an alternate locale may be specified.
For a complete listing of locales supported by your system, at the command prompt, type: locale -a
Input : none Returns: pointer to locale name
Returns a pointer to the name of the current locale.
Input : widechar : select 'true' (wide stream) or 'false' (narrow stream) Returns: current state of character-width flag
Set input/output streams’ character width.
This determines which input/output streams will be used:
IMPORTANT NOTE: This method will have no effect if called after the
application has performed I/O.
The first input or output performed by the application locks in the
character-stream width used for the application.
C++ offers a way to set stream width directly (std::freopen), but it’s
better to get it right the first time.
Input : buffered : if 'true', enable input buffering by the terminal if 'false', disable buffering and allow local control over the input stream echoType : member of enum EchoOpt: referenced ONLY when 'buffered' == false noEcho : data from the stdin stream will not be echoed to the terminal window termEcho: terminal echoes all stdin data to the window softEchoA, softEchoC, softEchoD, softEchoE: terminal echo is disabled, but the acRead() methods will echo PRINTING characters to the terminal window according to the specific soft-echo sub-option. block : (optional, 'true' by default) enable or disable blocking-read of input stream referenced ONLY when 'buffered' == false if 'true', enable blocking read of stdin if 'false', disable blocking read of stdin Returns: current state of the 'buffered-input' flag (inpBuf).
Disable buffering so each keystroke can be received as soon as the key is pressed, or restore terminal’s control over input buffering.
Normally, user input to the terminal (stdin) is buffered. That is, typed characters are stored in the terminal’s private input buffer and are returned to the application only when the ENTER key is pressed.
In some circumstances, however, when a “Press any key to continue...”
functionality is desired. Local control of the input buffer is also necessary
when capturing ANSI sequences transmitted from the terminal in order to prevent
cluttering the window with data which is meaningless to the user.
see acRead for additional info.
IMPORTANT NOTE: When buffering is enabled (buffered!=false), then the 'echoType' and 'block' parameters are ignored.
To bake a cake and eat it too, see the soft-echo option.
Input : echoType: member of enum EchoOpt: noEcho : data from the stdin stream will not be echoed to the terminal window termEcho : terminal echoes all stdin data to the window For the soft-echo options, terminal echo is disabled, and echo of input characters to the display is handled locally by the acRead() methods which will echo all PRINTING characters to the display, and will decode the "special keys" (cursor keys, etc.) according to the specific soft-echo sub-option. softEchoA: all special keys (default soft-echo option) softEchoC: cursor-movement keys only softEchoD: disable all special keys softEchoE: edit keys only: Backspace, Delete, Insert, plus the Tab and Shift+Tab keys Returns: 'true' if echo option modified 'false' if input buffering currently enabled (or invalid type)
Select the input character echo type. (enum EchoOpt).
Echo of user keyboard input (writing the received keycode to the display can be handled in a number of ways as listed above. The terminal can be allowed what key input is echoed to the display, or the application can take control of key input to provide a smoother user interface.
The “soft-echo” options are available for customizing the
user interface.
Please see Decoding the Special Keys for more information on
the soft-echo options.
This option is available ONLY when input buffering has been disabled. Please see acBufferedInput method for additional information.
Input : block : if 'true', enable blocking read of input stream if 'false', disable blocking read of input stream Returns: current state of the inpBlk flag 'true' == blocking-read of stdin 'false' == non-blocking read of stdin Returns:
Enable or disable blocking read from the input stream (stdin).
This is a pass-through method for the TermSet function which sets/resets
The blocking/non-blocking functionality.
IMPORTANT NOTE: Non-blocking input requires that unbuffered input be enabled. If not already enabled, unbuffered input (with ’noEcho’) will be automatically enabled.
Input : enable : if 'true', enable application capture of the break key if 'false', disable application capture of the break key terminal handles the break signal handlerType: (optional, cctDefault by default) member of enum CCH_Type, specify the break-handler type. alert : (optional, 'false' by default) Referenced only when 'handlerType' == cchIgnore. Optionally sound a beep when the break signal is received and discarded. if 'false', silently discard the break signal. if 'true', beep when discarding the break signal. handlerAddr: (optional, null pointer by default) - by default, the internal AnsiCmd method, BreakSignal_Handler() will provide an orderly response to receipt of the break signal. See below for details. - if the address of a handler method is specified, that method will be activated by the break signal. That method controls the response (if any) to the signal. Note: The name of the target method is the address of that method. This argument is referenced only if 'enable' is set. Returns: current state of capture flag 'true' break key will be captured by the application 'false' break key will be handled by the terminal program
Enable or disable application-level capture and processing of the BREAK key (CTRL+C).
By default, the terminal software processes the break signal by immediately killing the application which is running in the terminal window. While this is certainly an efficient and reliable way to terminate an application, it is grossly messy and potentially dangerous. For instance, what if the application is editing a critical system file when it is terminated in mid-update? Chaos.
In contrast, if the application itself captures the break signal, the application can shut down in an orderly manner, ask the user what to do, or simply ignore the break signal.
The handler type is specified by the ’ccType’ member variable which is initialized here.
Input : restoreAll : (optional, 'false' by default) if 'false' this method restores input buffering, input echo, and blocking-read settings only. Break-handler, cursor style, and other terminal configuration options are not affected. if 'true', all terminal setting under control of the TermSet object will be returned to the states when the object was instantiated. (see list below) Returns: 'true' if settings restored 'false' if original settings not previously saved or if system error
Restore terminal stream settings to original values captured during the first access to the terminal settings. This probably occurred during creation of the TermSet-class object which is done as part of the AnsiCmd-class constructor sequence. The TermSet object manages the the current terminal settings. The settings restored depend on the state of the 'restoreAll' flag, and include:
Next: Text Modifiers, Previous: Configuration Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : fg : foreground color attribute (member of aeSeq) Returns: 'true' if valid color attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set text foreground color attribute (3-bit and 4-bit color).
Input : bg : background color attribute (member of aeSeq) synth: (optional, 'true' by default) if 'true', use synthesized background color attributes if 'false', use standard ANSI background color attributes Returns: 'true' if valid color attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set text background color attribute (3-bit and 4-bit color).
Note on synthesis of intense background color attributes
The default color attributes for intense (bold) backgrounds are inadequate because the
'intense' ('bold') bit affects only the foreground color.“Synthesized” bold backgrounds are used by default, which bypasses the ’bold’ flag problem by
using a member from the color lookup table which is outside the basic sixteen color (4-bit) group.
Input : fg : foreground color attribute (member of aeSeq) bg : background color attribute (member of aeSeq) Returns: 'true' if valid color attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set text foreground AND background colors (3-bit and 4-bit color).
Programmer’s Note: The foreground is set AFTER the background so that if
the ‘bold’ flag is used in the foreground escape sequence, it will not be masked
by a subsequent non-bold background. Note also that bold background color escape sequences include the ‘bold’ flag,
but unfortunately, because of the way the terminal interprets this flag, it affects
only the foreground attribute. Exception: "synthesized" bold backgrounds are used by default, which bypasses the ’bold’ flag problem by using a different member from the color lookup table which is outside the basic sixteen (4-bit) color group. |
Input : fg : index into the lookup table for 8-bit color attributes Returns: 'true' if valid color attribute specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set foreground color from 8-bit-color lookup table.
Select an index number between min8BIT through max8BIT (16-231).
Input : bg : index into the lookup table for 8-bit color attributes Returns: 'true' if valid color attribute specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set background color from 8-bit-color lookup table.
Select an index number between min8BIT through max8BIT (16-231).
Input : rReg : red value gReg : green value bReg : blue value Returns: 'true' if valid R/G/B registers specified and set 'false' if specified parameters are out-of-range (attribute will not be modified)
Set foreground color using R/G/B register numbers.
Each of the basic Red, Green and Blue color attributes may be displayed in any of 216 shades, and the color values may be in any combination.
Each of the values may be specified as any register number between minRGB (16) and maxRGB (231).
Smaller values indicate less saturation (darker colors), and larger values indicate greater saturation (lighter, more intense colors). If desired, the special value zero (0) may be used to indicate minimum saturation.
Input : rReg : red value gReg : green value bReg : blue value Returns: 'true' if valid R/G/B registers specified and set 'false' if specified parameters are out-of-range (attribute will not be modified)
Set background color using R/G/B register numbers.
Each of the basic Red, Green and Blue color attributes may be displayed in any of 216 shades, and the color values may be in any combination.
Each of the values may be specified as any register number between minRGB (16) and maxRGB (231).
Smaller values indicate less saturation (darker colors), and larger values indicate greater saturation (lighter, more intense colors).
If desired, the special value zero (0) may be used to indicate minimum saturation.
Input : hue : member of enum WebSafeRGB wsrgbBLACK : black color index wsrgbRED : base color index (red color block) wsrgbGREEN : base color index (green color block) wsrgbBLUE : base color index (blue color block) wsrgbBROWN : base color index (brown color block) wsrgbMAGENTA : base color index (magenta color block) wsrgbCYAN : base color index (cyan color block) wsrgbGREY : base color index (grey color block) Remaining members of WebSafeRGB are reserved for other purposes. shade : intensity of the color specified by 'hue' wsrgbSHADE_MIN <= shade <= wsrgbSHADE_MAX where: wsrgbSHADE_MIN == minimum saturation (subdued) wsrgbSHADE_MAX == maximum saturation (brightest) Returns: 'true' if valid hue and shade values specified 'false' if specified parameters are out-of-range (attribute not be modified)
Set foreground color using "web-safe" R/G/B register value combinations.
In the early days of the internet and using early versions of color display hardware, it was necessary to define a set of color attributes that could be reliably duplicated on any standard hardware with any of the early graphics-based web browsers. (Yes, we used to surf the web using text-only browsers; but you must remember that like Mister Spock, we were trying to build a mnemonic memory circuit using stone knives and bear skins.)
The solution was to create the so-called “web-safe” set of color attributes. This was done by creating a 6 x 6 x 6 matrix of Red/Green/Blue register values yielding 216 discrete colors. Conceptually, each color can take one of six hex values: 00 33 66 99 CC FF. For each color, the actual index into the 256 entry color lookup table is selected according to this model. See enum WebSafeRGB for the way this mapping is done.
In the modern world of “true-color” computing, the idea of web-safe colors is a bit outdated, but it is still a valid concept in the simpler world of console applications, where we are limited to the palette specified by the terminal configuration.
Please see Development and Testing for a fuller discussion of the color attributes available to console applications.
Input : hue : member of enum WebSafeRGB wsrgbBLACK : black color index wsrgbRED : base color index (red color block) wsrgbGREEN : base color index (green color block) wsrgbBLUE : base color index (blue color block) wsrgbBROWN : base color index (brown color block) wsrgbMAGENTA : base color index (magenta color block) wsrgbCYAN : base color index (cyan color block) wsrgbGREY : base color index (grey color block) Remaining members of WebSafeRGB are reserved for other purposes. shade : intensity of the color specified by 'hue' wsrgbSHADE_MIN <= shade <= wsrgbSHADE_MAX where: wsrgbSHADE_MIN == minimum saturation (subdued) wsrgbSHADE_MAX == maximum saturation (brightest) Returns: 'true' if valid hue and shade values specified 'false' if specified parameters are out-of-range (attribute not be modified)
Set background color using "web-safe" R/G/B register value combinations.
See acSetWebFg, above for a description of “web-safe” colors.
Input : shade : brightness of grey color: minGSCALE <= shade <= maxGSCALE example: acSetGreyscaleFg ( minGSCALE + 2 ) ; Returns: 'true' if valid greyscale attribute specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set Greyscale foreground color attribute. (background unchanged)
For systems that have at least 256 colors, 24 shades of greyscale intensity
are available.
These are accessed through indices 232-255 of the terminal’s
256-color lookup table.
Input : shade : brightness of grey color: minGSCALE <= shade <= maxGSCALE example: acSetGreyscaleBg ( minGSCALE + 2 ) ; Returns: 'true' if valid greyscale attribute specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set Greyscale background color attribute. (foreground unchanged)
For systems that have at least 256 colors, 24 shades of greyscale intensity
are available.
These are accessed through indices 232-255 of the terminal’s
256-color lookup table.
Input : fg : AIX foreground color attribute (member of aeSeq) Returns: 'true' if valid color attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set text foreground color using the non-standard AIX extensions.
The members of enum aeSeq recognized by this method are:
aesAIXFG_B_BLACK aesAIXFG_B_BLUE
aesAIXFG_B_RED aesAIXFG_B_MAGENTA
aesAIXFG_B_GREEN aesAIXFG_B_CYAN
aesAIXFG_B_BROWN aesAIXFG_B_GREY
The AIX color attributes were defined by IBM to provide interoperability of the terminal interface between their proprietary systems and the Linux/UNIX world. Although these attributes are not part of the ANSI standard, they are widely supported and provide basic foreground and background colors using a slightly different (brighter) combination of Red/Green/Blue register values.
The differences are demonstrated in the color-attribute tests included with
the AnsiCmd library.
See Development and Testing for more information.
Input : bg : AIX background color attribute (member of aeSeq) Returns: 'true' if valid color attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set text background color using the non-standard AIX extensions.
The members of enum aeSeq recognized by this method are:
aesAIXBG_B_BLACK aesAIXBG_B_BLUE
aesAIXBG_B_RED aesAIXBG_B_MAGENTA
aesAIXBG_B_GREEN aesAIXBG_B_CYAN
aesAIXBG_B_BROWN aesAIXBG_B_GREY
Input : none Returns: 'true'
Return all ANSI attributes to terminal defaults. Set all tracking members to their default values. Flush the input and output buffers.
This method does not modify the terminal configuration. It resets only the ANSI control environment as defined by the set of escape sequences.
Programmer’s Note: It is not possible to programatically check whether each attribute was actually reset; however, the ANSI reset escape sequence should be trustworthy.
Next: Cursor Positioning, Previous: Color Attributes, Up: AnsiCmd Class Methods [Contents][Index]
Input : mod : text modification attribute (member of aeSeq) Returns: 'true' if valid modifier attributes specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Set or reset the specified text modifier.
Any text written after setting a modifier using this command will be displayed using the specified modifier (bold, italic, etc.). Any text written after resetting a modifier will be displayed without the specified modifier.
See the list of valid text modifiers in the description of the acResetMods method below.
Input : full: (optional, 'false' by default) if 'true', write a reset command instead of writing the ANSI modifier-off sequences. This option is available in case the host terminal does not support some or all of the modifier-off sequences. NOTE: this ALSO resets the color attributes. if 'false', write only the individual modifier commands, do not write the reset command Returns: nothing
Reset all text modifiers, leaving the base foreground and background color attributes unchanged.
The text modifier attributes are:
aesBOLD, // bold (increase intensity) aesFAINT, // faint/dim (decrease intensity) aesITALIC, // italic (or inverse) aesUNDERLINE, // underline aesBLINK_SLOW, // slow blink aesBLINK_FAST, // fast blink aesREVERSE, // reverse foreground and background colors aesCONCEAL, // hide text aesXOUT, // crossed out text (marked for deletion) aesFRACTUR, // a variety of German calligraphy aesDBL_UNDERLINE, // double-underline (or bold off) aesFRAMED, // "frame" the text aesENCIRCLE, // "encircle" the text aesOVERLINE, // overlined text
Calling this method is equivalent to calling acSetMod() nine times, once for each of the modifer resets.
aesBOLD_OFF, // normal intensity (neither bold nor faint) aesITALIC_OFF, // italic off (and Fractur off) aesUNDERLINE_OFF, // not underlined aesBLINK_OFF, // not blinking aesREVERSE_OFF, // not reversed aesCONCEAL_OFF, // conceal off aesXOUT_OFF, // not crossed out aesFRM_ENC_OFF, // not framed, not encircled aesOVERLINE_OFF, // overline off
Input : enable : 'true' to enable full reset for attribute modifications 'false' to disable full reset and rely upon the setting/resetting the flag which controls the specific attribute being modified Returns: current state of the full-reset flag
Enable or disable reset of all ANSI display attributes before modifying a text attribute.
The AnsiCmd class is constructed so that when modifying an ANSI parameter other parameters will be affected as little as possible. Specifically, when enabling or disabling an attribute such as Bold, Underline, etc., the intent is to avoid disturbing the existing forground and background color settings.
However, some console software or their underlying system software may not support all of the single-attribute commands such as aesBOLD_OFF, aesITALIC_OFF, aesUNDERLINE_OFF, aesBLINK_OFF aesREVERSE_OFF, aesCONCEAL_OFF, aesXOUT_OFF, aesFRM_ENC_OFF, aesOVERLINE_OFF, aesIDEO_OFF.
If these reset commands are not supported on a given platform, then set the ’fullReset’ flag, and the AnsiCmd class will use the full reset command, aesRESET when changing terminal settings. The aesRESET command is supported by nearly all terminal emulators.
See Invoking - Terminal Setup (-A option) which enables the full-reset flag as part of the startup sequence.
Next: Input Methods, Previous: Text Modifiers, Up: AnsiCmd Class Methods [Contents][Index]
Important Note On Cursor Positioning
Cursor positions within a terminal window are always defined as offsets from some reference position. In general, offsets are relative to the upper-left corner of the terminal window, also known as the “origin”.
The window origin is defined as position 1:1 (not the logically correct 0:0).Unfortunately, the developers of terminal software and the authors of the ANSI commands and other utilities are not always on the same page regarding whether cursor offsets should be 0-based or 1-based. Be aware that a zero(0) value may be silently converted to a one(1) value, OR it may cause an operation to fail, or worse, produce unexpected results.
The AnsiCmd cursor-positioning methods will accept an “absolute” value of zero and silently convert it to a one(1). This prevents artifacts such as unexpected scrolling or pushing text out of the window. However, be aware that not all utilities are so user friendly. Be aware!
Input : curcmd: one of the members of the cursor-positioninng group which are included in enum aeSeq. Example: acSetCursor ( aesCUR_HOME ) ; arga : (optional, 1 by default) for options which require arguments, 'arga' specifies the first argument. Example: acSetCursor ( aesCUR_ABSCOL, 30 ) ; argb : (optional, 1 by default) for options which require arguments, 'argb' specifies the second argument. Example: acSetCursor ( aesCUR_ABSPOS, 12, 60 ) ; Returns: 'true' if valid cursor command (and valid arguments, if required) 'false' if invalid parameter(s) specified (position will not be modified)
Set cursor position within terminal window.
Some ANSI cursor commands perform cursor movements relative to the current position, while other commands set the cursor at an absolute position within the terminal window.
See cursor offsets above regarding 1-based vs. 0-based cursor positioning.
This method invokes the specified ANSI escape sequence directly; however, there are two variations on this method, described below, which may also be used to set the cursor position. Please choose the one that best suits your needs.
NOTE: One member of the cursor-positioning group: aesCUR_REPORT, is not handled by this method.
Instead please see acGetCursor(). If aesCUR_REPORT is received, it will be ignored and ’false’ will be
returned to indicate that the request was not handled.Also:
Digital Equipment Corporation (DEC) and the SCO Group (UnixWare) defined some of the
cursor-management commands differently. On our test systems, the SCO commands work correctly,
while the DEC commands do not. Your mileage may vary.
Input : One of the following: row : target row col : target column or: wp : (by reference) target row and column Returns: 'true' if specified row/column are within the terminal window 'false' if invalid position (cursor position not modified)
Set absolute cursor position within terminal window.
These methods reformat the parameters and call the low-level acSetCursor method described above.
Input : none Returns: an initialized WinPos object (If system error or parsing error, window origin is returned.)
Get the current cursor position within terminal window.
This method requires that input buffering be disabled and that input echo
be set to ’noEcho’. The reason for this is that when buffering is active,
the response from the terminal will not become available to the
application until the Enter key is detected in the input stream.
In addition, echo of input characters to the terminal window must also
be disabled because when the system writes the response to the position
query, it is written to stdin, which if echo were enabled would likely
trash the currently-displayed text, or at minimum would move the cursor,
causing a big surprise at the application level. While setting and
restoring the buffering/echo options is an expensive operation in terms
of CPU cycles, it is necessary for smooth operation at the application level.
-- Write the ANSI sequence requesting the current cursor position. -- Read the response (binary data) from stdin. -- Decode the response which is of the form: 1B 5B (row) 3B (col) 52 1B escape character 5B left square bracket row one or more ASCII numeric chars indicating row number 3B ';' (ASCII semicolon) col one or more ASCII nummeric chars indicating column number 52 ASCII 'R'
Input : style : member of enum CurStyle color : (optional, default from terminal profile) member of aeSeq, foreground attribute group: aesFG_xxx color attribute for cursor [CURRENTLY IGNORED] Returns: 'true' if valid argument(s), else 'false'
Set cursor type i.e. the shape of the cursor.
Three basic cursor shapes are available in either a steady state or blinking: Block:'█' Underline:'▁' Vertical Bar:'▎'
In addition, the cursor can be made invisible. The style is specified as a member of enum CurStyle which is the parameter for the escape sequence to be transmitted. (Note that cursor style settings are not part of the ANSI standard.)
csBblock = 0, // Full-character cell, blinking block csDflt = 1, // Cursor type defined by terminal configuration csSblock = 2, // Full-character cell, steady (non-blinking) block csBuline = 3, // Blinking underline csSuline = 4, // Steady underline csBvbar = 5, // Blinking vertical bar csSvbar = 6, // Steady vertical bar csHide = 7, // Hide cursor (make it invisible) csShow = 8, // Show cursor (make it visible)
Note on cursor blink timeout: Although the cursor shape and blinking/steady status can be specified using this method, the terminal settings specify a timeout on the blinking status. For instance, the Gnometerm terminal emulator specifies a default timeout on the cursor’s blink status of ten(10) seconds. This timeout can be adjusted using the “gsettings” utility. Example: Get current settings: gsettings get org.gnome.desktop.interface cursor-blink-timeout Report the range of valid values: gsettings range org.gnome.desktop.interface cursor-blink-timeout Set a new timeout of 25 seconds: gsettings set org.gnome.desktop.interface cursor-blink-timeout 25 |
Note: The cursor color attribute is automatically set by the terminal to the same color as the text. Theoretically, the "gsettings" utility and other utilities can also be used to set the cursor color, but early testing shows that such commands are ignored. Testing continues.
Next: Output Methods, Previous: Cursor Positioning, Up: AnsiCmd Class Methods [Contents][Index]
Input : gsIn : (by reference) receives captured text (null terminated) limit : (optional, size of gString object by default) If specified, 'limit' indicates the maximum number of characters (wide-stream input) OR the maximum number of bytes (narrow-stream input) that will be extracted from the stdin buffer. Important Note: This argument is referenced only when unbuffered input is active. This argument is ignored when input-stream buffering is enabled. Returns: number of characters captured (NOT the number of bytes)
Capture user input as a sequence of characters terminated by the Enter key, OR when input buffering is disabled and the number of characters specified by the 'limit' parameter has been reached.
Note that the gString object which receives the data can hold up to gsMAXCHARS (1024) characters.
Internally, this method loops a call to the single-character acRead (see below). The called method contains most of the intelligence of the operation.
Please See Soft Echo Options for a discussion of when and how key input is echoed to the display.
Input : none Returns: keycode from user
Capture a single keystroke from the user.
The functionality of this method is dependent upon three factors:
1) Whether input buffering is enabled,
(see acBufferedInput)
2) The active input echo option,
(see Soft Echo Options)
3) Whether input is configured for blocking or non-blocking read.
(see acBlockingInput)
Please study these options carefully and configure the input stream according
to the needs of your application. A good place to start would be with
1) unbuffered input, 2) softEchoA, and 3) blocking read.
Input : none Returns: nothing
Flush stdin, (the active input stream, wcin or cin).
Any data still in the input stream will be discarded.
Flushing the input buffer relies on an unbuffered input stream
to reliably extract the stale data from the stream. If input buffering is
enabled when this method is called, this method disables buffering before
the flush and re-enables buffering after the flush.
While this is effective, it does produce a small performance hit.
For this reason, it is recommended that unless there is a clear reason
to do otherwise, the application should disable input buffering during
startup and then re-enable buffering just before exit.
Please see acBufferedInput for more information.
See also acFlushStreams, below.
Next: Text Erase, Previous: Input Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : starting cursor position in one of the following formats: wp : a WinPos object (by reference) OR row : target row col : target column text data to be written in one of the following formats: gsTxt : (by reference) a gString object OR wTxt : a wchar_t string (32-bit characters) OR cTxt : a char (byte) string OR wchar : a single wchar_t (wide) character OR cbyte : a single byte flush : (optional, 'true' by default) if 'true, flush the output buffer before return if 'false', do not flush the output buffer newln : (optional, 'true' by default) if 'true', a newline will cause the following line to begin on the same column as the previous line if 'false', a newline will cause the following line to begin at column one (left edge of window) Returns: current cursor position (WinPos object)
Write text data (or ANSI escape sequences) to stdout beginning at the specified cursor position. The final cursor position is at the end of the output. This is the return value.
The primary difference between this method and traditional TTY-style output is that newline ('\n') characters are handled as a special case. When a newline character is encountered in the output stream, it causes the cursor to be placed on the next row at the same column as the first column of the previous row. This automatic formatting allows the application to write formatted paragraph data without the painful task of having to count columns. (“You’ll thank me later.” — Adrian Monk)
This method is actually a group of overloaded methods which provide flexibility in the way parameters are passed.
Cursor position may be specified either as a WinPos object or as seperate row and column values.
The source text may be formatted as 1) a gString object, 2) a wide-character array, 3) a byte (char) array, or 4) as a single character or single byte.
Note that the length of the source data is limited by the size of the gString object: gsMAXCHARS (wchar_t characters), or gsMAXBYTES (bytes). For longer text strings, call the ttyWrite method which can handle arbitrary data length.
By default, the output buffer is flushed after all data have been written.
This is equivalent to the C++ sequence:
wcout << "text_data" ;
wcout.flush() ;
However, flushing the output buffer is a slow operation (relatively speaking),
so if multiple writes are performed in sequence, it is more efficient to
flush the stream only once, after the last write of the sequence. For example,
the following sequence writes three text strings, each in a different color,
with the 'flush' flag set (default value) for the last write.
WinPos wp( 4, 30 ) ;
acSetFg ( aesFG_RED ) ;
wp = acWrite ( wp, "Red textdata.\n", false ) ;
acSetFg ( aesFG_BLUE ) ;
wp = acWrite ( wp, "Blue text data.\n", false ) ;
acSetFg ( aesFG_GREEN ) ;
wp = acWrite ( wp, "Green text data.\n" ) ;
Note that this method DOES NOT check whether a line has automatically wrapped at the right edge of the terminal window. If a line wrap occurs, then the returned cursor position may be incorrect.
Note also that this method will not cause displayed data to scroll upward when the bottom row of the window is reached. If scrolling is desired, then call the ttyWrite method instead.
Note that the width of the output stream (wide or narrow stream) is
established during the application startup sequence; therefore, regardless
of the width of the source data, it will be transmitted using the established
stream width.
Please see acSetStreamWidth, or the
W option command-line option for more information on stream
configuration.
Input : text data to be written in one of the following formats: gsTxt : (by reference) a gString object OR wTxt : a wchar_t string (32-bit characters) OR cTxt : a char (byte) string OR wchar : a single wchar_t (wide) character OR cbyte : a single byte (generally: an ASCII control code) flush : (optional, 'true' by default) if 'true, flush the output buffer before return if 'false', do not flush the output buffer Returns: nothing
Write text data (or ANSI sequence) to stdout beginning at the current
cursor position. This emulates the action of a teletype machine (TTY).
(If you don’t know what a teletype machine is, your grandparents will
explain it to you.)
Any newline characters encountered will cause the cursor to be positioned
on the first (leftmost) column of the line below, and if on the last line
in the window, all data will be scrolled upward.
Text will automatically wrap at the right edge of the window.
This method is actually a group of overloaded methods which provide flexibility in the way parameters are passed. The source text may be formatted as 1) a gString object, 2) a wide-character array, 3) a byte (char) array, or 4) as a single character or single byte.
By default, the output buffer is flushed after all data have been written.
This is equivalent to the C++ sequence:
wcout << "text_data" ;
wcout.flush() ;
However, flushing the output buffer is a slow operation (relatively speaking),
so if multiple writes are performed in sequence, it is more efficient to
flush the stream only once, after the last write of the sequence. For example,
the following sequence writes three text strings, each in a different color,
with the 'flush' flag set (default value) for the last write.
acSetCursor ( 4, 1 ) ;
acSetFg ( aesFG_RED ) ;
ttyWrite ( "Red textdata.\n", false ) ;
acSetFg ( aesFG_BLUE ) ;
ttyWrite ( "Blue text data.\n", false ) ;
acSetFg ( aesFG_GREEN ) ;
ttyWrite ( "Green text data.\n" ) ;
Note that the width of the output stream (wide or narrow stream) is
established during the application startup sequence; therefore, regardless
of the width of the source data, it will be transmitted using the established
stream width.
Please see acSetStreamWidth, or the
W option command-line option for more information on stream
configuration.
Input : none Returns: nothing
Flush stdout, (the active output stream, wcout or cout).
Any data still in the output stream will be written to the terminal window.
Note that the output methods acWrite and ttyWrite by default, flush the output stream at the end of each write. The acFlushOut method may be used to explicitly flush the data from the stream.
See also acFlushStreams, below.
Input : none Returns: nothing
Flush (write) any data in the stdout stream and discard an stale data in the stdin stream.
This method combines calls to acFlushIn and acFlushOut as described above.
Technical Note: Although every effort has been made to clear the I/O buffers as needed, transmission and receipt of ANSI escape sequences can be interrupted or broken, causing display artifacts or other problems. Explicitly flushing the buffers at critical moments can help to reduce such accidents.
Next: Misc Methods, Previous: Output Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : cur : one of the members of the text-erasure group within enum aeSeq. example: acEraseArea ( aesERASE_WIN ) ; rowOff: (optional, ZERO by default) If a non-zero value is specified, the cursor will be shifted upward (negative values) or downward (positive values) from the current cursor position before the erasure occurs. colOff: (optional, ZERO by default) If a non-zero value is specified, the cursor will be shifted leftward (negative values) or rightward (positive values) from the current cursor position before the erasure occurs. Returns: 'true' if successful 'false' if invalid parameter(s) specified
Erase the specified area of the terminal window.
The area to be erased is specified by one of the ANSI erasure commands.
aesERASE_BOW, // erase from cursor to bottom of window
aesERASE_TOW, // erase from cursor to top of window
aesERASE_WIN, // erase entire window (’clear’)
aesERASE_SAVED, // erase "saved" lines
aesERASE_EOL, // erase from cursor to end of line
aesERASE_BOL, // erase from cursor to beginning of line
aesERASE_LINE, // erase entire line
The specified erasure is performed relative to the current cursor position
UNLESS an offset is specified:
rowOff : row offset from current row
colOff : column offset from current column
Important Note: If the specified offset moves the cursor beyond the
edge of the terminal window, unexpected side-effects may occur.
See also the direct erasure method, acClearArea.
Next: API Methods, Previous: Text Erase, Up: AnsiCmd Class Methods [Contents][Index]
Input : repeat : (optional, 1 by default) repeat count Range: 1 - 32,767 delay : (optional, 5 by default i.e. 1/2 second) delay between successive beeps in tenths of a second in the range: 2 - 600 (0.2sec through 1.0min) Note: The system is unable to handle short delays, so a delay of two-tenths second is the safe minimum. freq : (optional, -1 by default) if specified, this is the frequency of the beep [CURRENTLY IGNORED] Returns: nothing
Invoke the console’s default auditory alert (beep).
When called without parameters, the acBeep method produces a single beep (or whatever sound your terminal is set up to produce when the ASCII Bell control code is received.
Three optional parameters are available: 'repeat', 'delay', and freq' as shown above.
The repeat parameter is straightforward, specifying the number of individual beeps to produce from 1 (default) to 32,767, although we can attest that anything over about 200 will cause everyone in your household to toss the nearest loose object in your direction.
The delay parameter specifies the (approximate) pause between beeps.
The quality and repeatability of the tone is heavily dependent upon the
delay between beeps. This is because the the actual physical timer used and
the system code which controls it are both shared resources.
The delay interval may be specified as a multiple of 0.10 (1 tenth) second,
with the default being 0.5 (5 tenths) second, and the maximum being one
minute (600 tenths). For a stable repeatable sound, the practical
minimum is two or three tenths (0.2 - 0.3) of a second.
The freq parameter specifies the frequency of the tone that will
be produced. For the current (pre)release, this parameter is ignored, and the
tone is produced by simply issuing the ASCII Bell control code.
For the production release, however, we hope to implement a more robust and
flexible sound control.
Input : tenths : specifies the sleep interval in tenths of a second (1/10 sec == 0.10 sec) millisec: (optional, zero by default) for finer control over the length of the delay, specify a delay in milliseconds. nanosec : (optional, zero by default) for even finer control over the length of the delay, specify a delay in nanoseconds. [CURRENTLY IGNORED] Returns: nothing
Sleep (pause) execution for the specified time period. This method encapsulates access to the C-language 'nanosleep' function. It is intended to simplify the the interface and replaces direct calls to the obsolete C-language sleep and usleep functions.
The primary delay value is specified in tenths of a second (0.10sec), with
a secondary delay specification in milliseconds (0.001sec).
The sum of the two values specifies the total duration of the delay.
Thus the effective minimum delay is 1 millisecond, while the theoretical
maximum delay is: 65535/10 or 6553 minutes + 65535 milliseconds or
approximately 6618 minutes.This is an impractically large number, so we
arbitrarily limit the maximum delay to 61 minutes, which is approximately
60 minutes more than anyone will likely ever need.
1 millisecond <= delay <= 61.0 minutes
Note that the 'nanosec' parameter is currently ignored. (see tech notes below)
The philosophy here is that delays of less than one tenth of a second are not very useful for a human interface, while smaller delays are oriented toward computer-oriented tasks and which are limited only by the resolution of the clock referenced by the called function.
In C++, the cosmopolitan way to delay the action is to use the 'chrono'
class to define the delay, and the 'sleep_for'
method to execute it.
Example: chrono::duration<short>aWhile( 10 );
this_thread::sleep_for( aWhile );
Example: chrono::duration<short, std::milli>aMoment( 250 );
this_thread::sleep_for( aMoment );
The chrono/sleep_for C++ implementation is much cleaner and more
intuitive than nanosleep(); however, ANSI escape sequences are by
definition incompatible with multi-threaded environments, so we do
not introduce multi-threading in the AnsiCmd class.
Instead, we use the 'nanosleep' function which is technically
sophisticated, but clunky in implementation. That is why we isolate it
here to avoid cluttering up our otherwise lovely code.
The nanosleep C-library function is defined in time.h and takes as parameters two 'timespec' structures as shown.
The first parameter 'req' (the ‘request’) specifies the duration of the sleep interval in seconds and nanoseconds. Note that the nanosleep function rounds the nanosecond value ('tv_nsec') upward to the resolution of the clock. Note also that the ('tv_nsec') value is limited to 9,000,000,000 (nine billion nanoseconds). Any larger value will generate an error.
If the requested interval is completed without interruption, the second parameter ('rem') (the ‘remainder’) remains unused. If however, the sleep interval is interrupted by some system event, then the second parameter receives the remainder of the delay so that nanosleep can be called again to complete the specified sleep interval.
The resolution of the clock used for this interval is also a significant
factor in the accuracy of the operation.
It is important to keep in mind that although nanosleep claims to
be accurate in the nanosecond range, a number of factors may affect
the results. For instance, the default Linux scheduler is based on
ten-millisecond intervals, so sequential calls may be limited to
this resolution. Some newer systems with newer kernel support may
be able to provide a resolution of one(1) millisecond.
See the documentation for the C-library 'clock_getres' function for
more information on the clocks available on the host system.
See also: "man 7 time", which indicates that the effective
resolution is between 1 and 10 milliseconds.
Also see the resolutions specified in the file: "/proc/timer_list".
Most of the entries in that file specify a resolution of 1 nanosecond,
but we see this as more aspirational, than mathematical.
While the nanosleep function cannot be relied upon by timing-critical operations which may be affected by these factors, for user-oriented delays, into the tens-of–milliseconds range, however, the nanosleep function is a welcome addition to the C-language library.
Input : none Returns: pointer to version string
This method return a const pointer to a string containing the AnsiCmd class
version number. The version number takes the form: x.y.zz, where
'x' is the major version, 'y' is the minor version and 'zz'
is the step version.
Example: 0.0.03
Unlike some other developers whom we will politely not name (Firefox), this author does not advance the major or minor version number without a very good reason. Therefore, even packages we have had in circulation for twenty years seldom advance beyond version 0.2.00. For instance, the gString class distributed with package, which we first released in 2011 is now at version 0.0.32, and yes, it is absolutely solid.
Input : font : one of aesPRIMARY_FONT or aesALTERNATE_FONT which are members of enum eSeq. fontnum: (optional, zero(0) by default) specify the alternate font, range: 1 through 9 Returns: 'true' if valid greyscale attribute specified and set 'false' if invalid parameter(s) specified (attributes will not be modified)
Specify the terminal font used to write subsequent text data.
Specify the 'font' parameter as a member of enum aeSeq:
These commands are not recognized on any of our development platforms, but the font test is available for testing them on your particular system: (see Test_AltFonts).
Input : idea : member of enum aeSeq within the ideogram-command group. Returns: 'true' if valid argument 'false' if invalid parameter(s) specified (attribute will not be modified)
Interface to the seldom-supported and little-used "ideogram" (logogram) group of ANSI commands.
It is unclear what this group of commands was originally intended to do.
Presumably they were intended to provide some kind of border or
highlighting around a block of text.
aesIDEO_UNDER // ideogram underlined
aesIDEO_UDOUBLE // ideogram double-underlined
aesIDEO_OVER // ideogram overlined
aesIDEO_ODOUBLE // ideogram double-overlined
aesIDEO_STRESS // ideogram stress marking (italic?)
aesIDEO_OFF // all ideogram attributes off
These are probably non-functional, but they can be tested using this method.
See acDrawBox and acDrawLine methods for line drawing options.
Next: Development Support, Previous: Misc Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : newAttr : bitfield containing the logical OR of the desired foreground/background attributes and text modifiers. resetAll: (optional, 'false' by default) if 'false', only the the attributes specified by 'newAttr' will be modified. if 'true', all attributes and modifiers will be reset to their default values before the new attributes are applied. Returns: 'true' if successful, else 'false' (currently always 'true')
Modify or replace the current color attributes and/or text modifiers.
The basic group of AnsiCmd methods set or reset one attribute per call by issuing the corresponding ANSI escape sequence designated as a member of enum aeSeq (ansi escape Sequence). The acSetAttributes method, by contrast, takes as a parameter the logical OR of an arbitrary number of attributes designated as members of enum acAttr (ansi cmd Attribute). Arguably, this provides a cleaner interface between the application layer and the display-formatting functionality.
The individual enum acAttr members are OR'd together to produce the 'newAttr' parameter sent to acSetAttributes.
The examples below demonstrate how a logical OR of acAttr values specifies the attribute(s) to be modified.
Note that when performing any mathematical operation using members of an
enumerated type such as enum acAttr, the compiler will complain.
For instance, when performing a logical OR using members of enum acAttr,
the compiler insists that the result be cast back into the acAttr type.
For example, the compiler will complain about this assigment:
acAttr newAttr = acaFG_BLUE | acaBG_GREEN ;
so to make the compiler happy we perform a cast back to the type:
acAttr newAttr = acAttr(acaFG_BLUE | acaBG_GREEN) ;
Please See enum acAttr, below for more detailed information.
RGB attribute values combine 'acaFG_RBG' and/or 'acaBG_RGB' with
“web-safe” color indices in the range: wsrgbMIN <= index <= wsrgbMAX.
This example sets both foreground and background to web-safe RGB attributes:
acAttr aca = acComposeAttributes( 14, 221, true, true );
acSetAttributes ( aca );
Eight-bit attributes combine 'acaFG_INDEX' and/or 'acaBG_INDEX' with
8-bit color indices in the range: min8BIT <= index <= max8BIT.
This example sets both foreground and background to 8-bit attributes:
acAttr aca = acComposeAttributes( 32, 112, false, false );
acSetAttributes ( aca );
See acComposeAttributes below for additional examples.
Input : fgVal : foreground index (8-bit index or web-safe RGB index) -- if 'rgb' reset, then value interpreted as 8-bit index. Range: 16-231 (or greyscale:232-255) -- if 'rgb' set, then value interpreted as web-safe RGB index. Range: 0-252 -- if 'rgb' reset AND 'fgVal' 0-15, then assume 4-bit color bgVal : background index (8-bit index or web-safe RGB index) -- if 'rgb' reset, then value interpreted as 8-bit index. Range: 16-231 (or greyscale:232-255) -- if 'rgb' set, then value interpreted as web-safe RGB index. Range: 0-252 -- if 'rgb' reset AND 'fgVal' 0-15, then assume 4-bit color rgbfg : if set, fgVal is interpreted as a (web-safe) RGB index if reset, fgVal is interpreted as a 4/8-bit index rgbbg : if set, bgVal is interpreted as a (web-safe) RGB index if reset, bgVal is interpreted as a 4/8-bit index mods : (optional, acaPLAINTXT by default) logical OR of acAttr text-modifier flags) Returns: the constructed acAttr value (if a value is out-of-range, terminal default will be used)
Construct an acAttr attribute bitmap from component values:
Call this method when composing attributes with 8-bit fgnd/bgnd indices or
web-safe RGB fgnd/bgnd indices.
Use the constructed value as the parameter for a call to acSetAttributes, above.
Examples:
acAttr aca ; // receives the constructed value Construct an 8-bit foreground and background value: aca = acComposeAttributes ( min8BIT + 2, min8BIT + 27, false, false ); Construct a value with a 4-bit foreground on an 8-bit background: aca = acComposeAttributes ( 3, max8BIT - 32, false, false ); Construct the same attribute value, but adding italic text. aca = acComposeAttributes ( 3, max8BIT - 32, false, false, acaITALIC ); Construct a web-safe RGB foreground and background value: aca = acComposeAttributes ( wsrgbMIN + 16, wsrgbMAX - 32, true, true ); Construct a value with an 8-bit foreground on an RGB background. aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true ); Construct the same attribute value, but adding underlined text. aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true, acaUNDERLINE ); Construct the same attribute value, but with italic _and_ underlined text. aca = acComposeAttributes ( 201, wsrgbMIN + 32, false, true, acAttr(acaITALIC | acaUNDERLINE) ); Use the constructed value to set the specified attributes: acSetAttributes ( aca ); or acSetAttributes ( acAttr(aca | acaITALIC | acaUNDERLINE) );
Note on 4-bit values:
The 4-bit color attributes are individually named, so the attributes may be
specified directly.
Examples: acSetAttributes( acAttr(acaFG_BLUE | acaBGb_BROWN) );
acSetAttributes( acAttr(acaFG_DFLT | acaBGb_BLUE) );
acSetAttributes( acAttr(acaFG_DFLT | acaBG_DFLT) );
Although this method is not designed to configure 4-bit color indices (0-15),
they will be handled correctly, EXCEPT THAT it is not possible to specify
terminal default foreground or background using this method.
aca = acComposeAttributes ( 3, 12, false, false );
Input : decodedAttr: (by reference) instance of an acaExpand object to receive data. Returns: nothing
Get a decoded copy of the current color attributes and text modifier flags.
The bitfield containing the attributes is decoded into it component values.
Refer to the description of the acaExpand class data members for more information.
Input : fillchar: (optional, space character ' ' by default) specify a (single-column) character to be written to each character cell of the terminal window fillattr: (optional, default: terminal default attribute) color attribute for clearing the terminal window. Note: If a non-default attribute is specified, that will be the current fg/bg attribute on return. Returns: nothing
Clear the entire terminal window using the specified fill character and color attribute.
On return, the visible cursor will be at the HOME position (1,1).
Input : row : top row of target area col : left column of target area OR wpOrig : top row and left column of target area height : number of rows in target area width : number of columns in target area fillchar: (optional, ' ' by default) specify a (single-column) character to be written to each character cell in the target area fillattr: (optional, default: terminal default attribute) color attribute for clearing the target area. Note: If a non-default attribute is specified, that will be the current fg/bg attribute on return. Returns: 'true' if successful 'false' if parameter(s) out-of-range
Clear the specified rectangular area using spaces (default), or using the
specified fill character.
See acDrawLine below for an example invocation.
Position, height and width of the area are adjusted as necessary to remain within the terminal window. See also the note in cursor offsets regarding 1-based vs. 0-based cursor positioning.
Input : pos : offset from upper-left corner of terminal window to upper-left corner of box (1-based) length : length of the line: number of number of rows (vertical), or number of columns (horizontal). vertical: 'true' : vertical line 'false' : horizontal line lType : (optional, ltSINGLE by default) line style member of enum LineType: either ltSINGLE or ltDUAL begChar : (optional, null character by default) specify the beginning endpoint character endChar : (optional, null character by default) specify the final endpoint character Returns: cursor position at the end of the line: For horizontal lines, this is the column following the last character. For vertical lines, this is the column below the last character.
Draw a horizontal or vertical line in the terminal window.
Horizontal lines are drawn left-to-right.
Vertical lines are drawn top-to-bottom.
Optionally, the endpoint character(s) may be specified for the beginning and/or end of the line. The valid endpoint characters include any of the line-drawing glyphs defined in AnsiCmdDef.hpp. Note however, that the 'begChar' and 'endChar' parameter are not range checked, so the character specified (if any), will be written. (Use single-column characters only.) If the endpoint(s) are not specified, the line-drawing character is used as the endpoint character.
Example: // define the dimensions of the box short hgt = 9, wid = 25 ; // define the upper left corner of the box object WinPos wp( 9, 9 ) ; // clear target area using optional color attributes, and note that // on return, the specified colors are still active. acClearArea ( wp, hgt, wid, L' ', acAttr(acaFGb_CYAN | acaBG_BLUE) ) ; // draw the box acDrawBox ( wp, hgt, wid, ltDUAL ) ; // move downward to start position of first line wp.row += 4 ; // draw a line the full width of the box with connections on each end acDrawLine ( wp, 25, false, ltSINGLE, wcsLTEEdv, wcsRTEEdv ) ; // move to the top center of the box wp = { 9, 21 } ; // draw a line that connects with the box at the top and terminates // with a line-intersection character wp = acDrawLine ( wp, 5, true, ltSINGLE, wcsTTEEdh, wcsINSECT ) ; // draw a line from below the intersect character to the bottom // of the box, and which terminates with a connector character acDrawLine ( wp, 4, true, ltSINGLE, NULLCHAR, wcsBTEEdh ) ; ╔═══════════╤═══════════╗ ║ │ ║ ║ │ ║ ║ │ ║ ╟───────────┼───────────╢ ║ │ ║ ║ │ ║ ║ │ ║ ╚═══════════╧═══════════╝
Input : pos : offset from upper-left corner of terminal window to upper-left corner of box (1-based) height: number of rows for box width : number of columns for box lType : (optional, ltSINGLE by default) line style member of enum LineType: either ltSINGLE or ltDUAL text : (optional, null pointer by default) If specified, text to be written to interior of box. Returns: current cursor position within the box
Draw a box in the terminal window and optionally write text in the box.
This is a greatly simplified form of drawing a window. It simply draws a
rectangle in the terminal window at the specified position and of the
specified dimensions.
The box is drawn using the currently active foreground and background colors.
If parameters are out-of-range, the position and dimensions will be modified as necessary to fit within the terminal window.
The position of the visible cursor is returned.
If the 'text' parameter specifies text data to be written into the box,
then the cursor will be positioned at the end of the text. Otherwise, the
cursor will be positioned at the top-left corner of the interior of the box.
See acDrawLine above for an example invocation.
Input : pos : offset from upper-left corner of terminal window to upper-left corner of box (1-based) height: number of rows for box width : number of columns for box Returns: nothing
Erase the specified area. This is a companion method to the acDrawBox method above. acEraseBox simply calls the low-level method to clear the text from the specified area.
Input : box : (by reference) configuration parameters for the object text: (optional, null pointer by default) If specified, text to be written to interior of box. Returns: coordinates of upper-left corner of text area within the box (These coordinates are the one-based offset from the ) (upper-left corner of the terminal window. )
Display the data of an AC_Box object in the terminal window.
AC_Box Example
WinPos boxOrigin( 1, 16 ) ; short boxHEIGHT = 11 ; short boxWIDTH = 48 ; LineType lType = ltSINGLE ; aeSeq borderFg = aesFGb_GREY ; aeSeq borderBg = aesBG_BLUE ; aeSeq textFg = aesFG_BLUE ; aeSeq textBg = aesBG_CYAN ; const char* title = " Life Is A.. What?! " ; AC_Box box( boxOrigin, boxHEIGHT, boxWIDTH, lType, borderFg, borderBg, textFg, textBg, title ) ; acBoxDraw ( box, "\n\n Life is like a box of chocolates.\n" " You never know what you're gonna get.\n" " -- Forrest G." ) ;
Input : box : (by reference) configuration parameters for the object Returns: nothing
Erase the rectangular area drawn by the acBoxDraw method, above.
The current color attributes will be used to clear the area.
Input : box : (by reference) configuration parameters for the object Returns: coordinates of upper-left corner of text area within the box
Erase the text area of of an AC_Box object.
The acAttr (AnsiCmd Attributes) enumerated type provides application-level color-attribute and text-modifier configuration for terminal applications.
Members of this type specify color attributes and text modifiers in a consistent format which encapsulates the primitive ANSI escape sequences defined for terminal-window text formatting. (see enum aeSeq).
Within the AnsiCmd class, these values are decoded and mapped to their corresponding ANSI escape sequences (or group of sequences). This allows the application to focus on algorithms and user interaction rather than reading and writing binary data within the terminal window.
Although acAttr is defined as an enumerated type, is constructed
as a group of macros defining bitfields. This allows the macros to be
grouped in a coherent manner while also allowing bitwise OR operations
for the desired foreground, background and text-modifier attributes.
For example, combine foreground, background attributes PLUS the
“bold” and “italic” text attributes, then pass the
value as an argument to one of the application-level methods.
acAttr txtAttr = acAttr(acaFG_GREEN | acaBG_GREY | acaBOLD | acaITALIC) ;
acSetAttributes ( txtAttr ) ;
Technical Note: The compiler will complain when performing any mathematical
operations on members of an enumerated type; therefore, be sure to cast the
OR’d value back to the acAttr type. For instance, the following would cause
a compiler warning: acAttr a; a |= acaBOLD;
Instead, use the following syntax: a = acAttr(a | acaBOLD);
See also the acaExpand class below for more information on encoding and decoding the bitfield values.
Late Night host, Seth Meyers once defined nerds as people “with coffee-breath and crippling anxiety.” While that characterization was a bit rude, he actually wasn’t wrong. For all OCD sufferers, (otherwise known as technically proficient people), having more information is like having a mug of hot cocoa and a warm blanket.
So, while accessing the API method group (which includes the ACWin class), does not require an understanding of the bit manipulations that occur within the AnsiCmd library, our nerd DNA insists that we have at least a general idea what’s going on in the binary jungle.
All significant bit-oriented operations are encapsulated within the acaExpand class. The data managed by the acaExpand class are derived from the acAttr enumerated type and the WebSafeRGB enumerated type. These are both defined in AnsiCmdDef.hpp.
The acaExpand class is also defined in AnsiCmdDef.hpp, and is implemented in the AnsiCmdWin.cpp source module.
All methods and data members of the acaExpand class are “public”;
however, the live data are not available to the application (Duh!). If desired,
however, a copy of the live data data may be retrieved and studied.
Please see acGetAttributes, above.
acaExpand Methods
~acaExpand ( void ) ; // destructor
acaExpand ( void ) ; // default constructor
acaExpand ( acAttr bits ) ;
Initialization Constructor:
The 'bits' parameter consists of one or more members of enum acAttr
combined using a logical OR.
void decode ( acAttr bits ) ;
Decode the specified bitfield value into it component parts and store
them in the data members.
acAttr modify ( acAttr acaValue, bool add, uint8_t webRGB = 0 ) ;
Add (or remove) one or more elements to (from) the bitfield value.
'acaValue' specifies the item(s) to be modified.
'add' if true, add the ’acaValue’ items to the existing bitfield
if false, remove (reset the specified items
'webRGB' for R/G/B items only, this specifies the web-safe index
void update ( aeSeq aesValue, uint8_t colorIndx = ZERO );
Update attribute tracking data using a member of enum aeSeq.
'aesValue' aeSeq item specifying attribute to be updated
'colorIndx' for aeSeq items requiring a color-attribute index value
acAttr compose ( void );
Construct an acAttr attribute bitmap from the data in the data members:
fgIndex, bgIndex and the boolean (flag) members. This is the reverse of the
'decode' method, above, and is used to encode 8-bit and RGB attribute
indices.
See also the API-level method acComposeAttributes which calls this
method with consistent formatting.
aeSeq bits2aeseq ( acAttr acaBits, uint8_t byteIndx, bool isFgnd, bool isRgb );
Convert between acAttr (bitfield) and aeSeq (ANSI escape sequence).
'acaBits' acAttr bitfields to be converted
'byteIndx' byte index value (either foreground or background index)
'isFgnd' true if foreground target, false if background target
'isRgb' (optional, false by default) true if 'acaBits' references
one of the web-safeRGB register indices.
acAttr aeseq2bits ( aeSeq aesCmd, bool& setFlag );
Convert between aeSeq (ANSI escape sequence) and acAttr (bitfield).
'aesCmd' member of enum aeSeq to be converted
'setFlag' (by reference) receives the state of the internal
set/reset flag associated with the attribute
bool web2regs ( uint8_t webrgb, bool fgnd );
Convert web-safe RGB index into red/green/blue RGB register values.
'webrgb' value indicating one of the web-safe RGB register groups
in the range: wsrgbMIN <= webrgb <= wsrgbMAX.
'fgnd' true if fgnd attributes, false if bgnd attributes
216 web-safe colors are defined by the standard, which are mapped to the
256 color indices defined for terminal color attributes and are then
translated to individual R, G and B register values as shown.
DARK >>>> LIGHT CORRESPONDING RGB REGISTER INDICES Black : 0 16;16;16 Red group : 1 36 22;16;16 >>>> 231;16;16 Green group : 37 72 16;22;16 >>>> 16;231;16 Blue group : 73 108 16;16;22 >>>> 16;16;231 Brown group : 109 144 22;22;16 >>>> 231;231;16 Magenta group: 145 180 22;16;22 >>>> 231;16;231 Cyan group : 181 216 16;22;22 >>>> 16;231;231 Grey group : 217 231 22;22;22 >>>> 231;231;231
void reset ( bool modsOnly = false ) ;
Reset (clear) all data members. Optionally, reset text-mod flags only.
'modsOnly' if true, reset only the text-modifier attributes
if false, reset all color and text-modifier attributes
acaExpand Data Members
Note that while there is some redundancy among the members, the layout of the data members is constructed for speed of access and to minimize the need for higher-level methods to perform bitwise operations. This in turn reduces the chance of processing errors.
acAttr acaVal; full, encoded acAttr value
uint32_t fgBits; nine bits defining foreground:
index byte + fg default flag
uint32_t bgBits; nine bits defining background:
index byte + bg default flag
uint32_t allFlags; all binary flags (excludes fg/bg indices)
uint32_t modFlags; text-modification flags (subset of ’allFlags’)
acAttr acaFgnd; 8-bit field defining the foreground index
acAttr acaBgnd; 8-bit field defining the background index
aeSeq aesFgType; Foreground attribute type:
aesFG_DFLT: 4-bit color
aesFG_INDEX: 8-bit color
aesFG_RGB: r/g/b color
aeSeq aesBgType; Background attribute type:
aesBG_DFLT: 4-bit color
aesBG_INDEX: 8-bit color
aesBG_RGB: r/g/b color
aeSeq aesFgnd; 4-bit foreground (member of enum aeSeq)
aeSeq aesBgnd; 4-bit background (member of enum aeSeq)
uint8_t fgIndex; foreground byte index
uint8_t bgIndex; background byte index
uint8_t rgbFgR; if RGB foreground, Red register value
uint8_t rgbFgG; if RGB foreground, Green register value
uint8_t rgbFgB; if RGB foreground, Blue register value
uint8_t rgbBgR; if RGB background, Red register value
uint8_t rgbBgG; if RGB background, Green register value
uint8_t rgbBgB; if RGB background, Blue register value
bool fgDflt; if set, terminal default foreground
(ignore fg index bits)
bool bgDflt; if set, terminal default background
(ignore bg index bits)
bool boldMod; if set, Bold (intense) text
bool italicMod; if set, Italic text
bool ulineMod; if set, Underlined text
bool olineMod; if set, Overlined text
bool xoutMod; if set, X-out (strikethrough) text
bool blinkMod; if set, Blinking text
bool invisMod; if set, Invisible (concealed) text
bool revMod; if set, Reversed foreground and background
bool clrMods; if set, Clear existing mods before setting new mods
bool fgRgb; if set, rgbFgR, rgbFgG and rgbFgB contain
the foreground color
bool bgRgb; if set, rgbGbR, rgbBgG, and rgbBgB contain
the background color
acaExpand Decoding Examples
AnsiCmd (enum acAttr) color-attribute bit fields: 0x000000FF index for foreground color ......00-......0F 16 4-bit color attributes ......10-......E7 216 8-bit color attributes ......E8-......FF 24 greyscale color attributes ......00-......FC 232 RGB color attributes 0x0000FF00 index for background color ....00..-....0F.. 16 4-bit color attributes ....10..-....E7.. 216 8-bit color attributes ....E8..-....FF.. 24 greyscale color attributes ....00..-....FC.. 232 RGB color attributes 0x00FF0000 text modifier flags ..00.... plain text (no modifiers) ..01.... bold (intense) ..02.... italic ..04.... underline ..08.... overline ..10.... x-out (strike-through) ..20.... blink ..40.... concealed (invisible) ..80.... reversed fg/bg 0xFF000000 additional flags 01...... clear existing modifiers before setting the new ones 02...... use terminal default foreground attribute (foreground index ignored) 04...... if set, it indicates that foreground index is the index of a "web-safe" RGB foreground color attribute with a range of: minRGB <= value <= maxRGB 08...... use terminal default background attribute (background index ignored) 10...... if set, it indicates that background index is the index of a "web-safe" RGB background color attribute with a range of: minRGB <= value <= maxRGB 20...... (reserved) 40...... (reserved) 80...... (reserved as internal placeholder value) The following shows some examples of how the bitfield is constructed. The contruction is performed by creating a logical OR of enum acAttr members; or in the case of 8-bit and RGB color attributes by using the 'compose' method described above. See also the AnsiCmd 'acComposeAttributes' public method. To specify the terminal default foreground attribute, set the acaFG_DFLT flag. The foreground index value will be ignored. Fgnd: xxxx-x01x-xxxx-xxxx-xxxx-xxxx-....-.... To specify the terminal default background attribute, set the acaBG_DFLT flag. The background index value will be ignored. Bgnd: xxx0-1xxx-xxxx-xxxx-....-....-xxxx-xxxx To specify a 4-bit foreground attribute, _reset_ the acaFG_DFLT and acaFG_RGB flags and insert the desired member of enum acAttr in the range: acaFG_BLACK through acaFGb_GREY inclusive. To specify a 4-bit background attribute, _reset_ the acaBG_DFLT and acaBG_RGB flags and insert the desired member of enum acAttr in the range: acaBG_BLACK through acaBGb_GREY inclusive. To specify an 8-bit indexed color foreground attribute, initialize the foreground index and _reset_ both the acaFG_DFLT and acaFG_RGB flags. Fgnd: xxxx-x00x-xxxx-xxxx-xxxx-xxxx-nnnn-nnnn To specify an 8-bit indexed color background attribute, initialize the background index and _reset_ both the acaBG_DFLT and acaBG_RGB flags. Bgnd: xxx0-0xxx-xxxx-xxxx-nnnn-nnnn-xxxx-xxxx To specify one of the "web-safe" RGB register combinations, initialize the foreground or background index and set the acaFG_RGB or acaBG_RGB flag, respectively. Fgnd: xxxx-x10x-xxxx-xxxx-xxxx-xxxx-nnnn-nnnn Bgnd: xxx1-0xxx-xxxx-xxxx-nnnn-nnnn-xxxx-xxxx To set one or more text modifiers, _reset_ the acaCLEAR_MODS flag and create a logical OR of the desired attributes. (include existing fg/bg bits.) Ex: acAttr fgbg = acAttr(acaFG_BLUE | acaBGb_RED); acAttr((fgbg |acaBOLD | acaITALIC | acaUNDERLINE) & ~acaCLEAR_MODS) Mods: xxxx-xxx0-xxxx-x111-xxxx-xxxx-xxxx-xxxx To reset one or more text modifier, set the acaCLEAR_MODS flag and _set_ the flag(s) for the modfier(s) to be reset. (include existing fg/bg bits.) Ex: acAttr(fgbg | acaITALIC | acaCLEAR_MODS) Mods: xxxx-xxx1-0000-0010-xxxx-xxxx-xxxx-xxxx
Next: Coding Example, Previous: API Methods, Up: AnsiCmd Class Methods [Contents][Index]
Input : args : (by reference) test to perform and test options major : specifies the test to perform minor : specifies test sub-section supp : specifies sub-test for RGB, etc. Returns: nothing
This method is a gateway to the debugging code. If debugging disabled (DEBUG_ANSICMD == 0), then a warning message is displayed.
Perform the specified test of terminal functionality. This functionality is divided into different groups. See ansiTest_Menu method for details.
Input : lo : receives a pointer to current locale structure tr : (by reference) receives terminal rows tc : (by reference) receives terminal columns fn : (by reference) receives current font number fr : (by reference) receives the 'full-reset' flag value ws : (by reference) receives the 'wide-stream' flag value Returns: nothing
Returns a copy of the protected data members of the class.
Used primarily by the ACWin class to synchronize terminal configuration, but may be used by the curious app designer.
Previous: Development Support, Up: AnsiCmd Class Methods [Contents][Index]
The following example demonstrates application startup including creation of an AnsiCmd-class object which provides terminal setup and color attribute control capabilities.
Under C++, the 'main' function does as little as possible.
It simply passes the command-line arguments and terminal environment to the
application class, which returns to 'main' only when it is time to exit.
The application class is unique to each application, allocating data storage and providing the functionality and user interface needed to complete the tasks for which it was designed.
The EarthPoints application class is typical of such classes in that it leverages well-established classes and library functions to do most of the work of the application. The application class provides coordination among the various components to produce the desired results. A really good application will also add something the world has never seen before.
The EarthPoints application does not aim so high. It is simply a vehicle for development and testing of the AnsiCmd class library, which is itself interesting, but not particulary innovative. The AnsiCmd library could be characterized as a nerd’s version of binge-watching a Netflix series during a long, long Covid-19 lockdown while on vacation in Guangxi Province.
Next: Development and Testing, Previous: AnsiCmd Library, Up: AnsiCmd Class Link Library [Contents][Index]
The AnsiCmd Window class, ACWin, is a “derived” class based upon the AnsiCmd class. This means that it includes all the public methods of its parent and methods which are unique to the new class.
ACWin implements a more sophisticated level of abstraction from the basic reading and writing of ANSI escape sequences. It defines a “window”, a bordered rectangular area within the terminal display. The interior of the window can be used directly to display text data, or may contain various user-interface constructs (see skForm Class), or both direct display and user interface fields. This table lists the public methods of the ACWin class.
Method Name | Description |
---|---|
ACWin constructor | Constructors |
ACWin destructor | Destructor |
OpenWindow | Open the window (make it visible) |
CloseWindow | Close the window |
RefreshWin | Redraw the window |
HideWin | Erase window from display |
MoveWin | Move window to another position |
ClearWin | Erase interior of window |
ClearRow | Erase specified interior row |
SetFieldText | Replace text in specified field |
GetFieldText | Get a copy of text in field |
ClearField | Delete text in specified field |
SetFieldIP | Position visible cursor in field |
RefreshField | Redraw text in a field |
SetFieldAttr | Set color attributes for a field |
SetInputFocus | Set input focus to a field |
Focus2NextField | Move input focus to next field |
Focus2PrevField | Move input focus to prev field |
InsertKey | Configure the Insert key |
EditForm | User edit of skForm object |
EditField | User edit of skField object |
SetTitle | Specify window title text |
SetTextAttr | Specify window interior colors |
SetBorderAttr | Specify window border colors |
Write | Write directly to window interior |
GetCursorPos | Get cursor position in the window |
SetCursorPos | Set cursor position in the window |
Write (field) | Write text into a field |
DrawBox | Draw a rectangle in text area |
DrawLine | Draw a line in the window |
FieldOutline | Draw a border around a field |
Input : none Returns: implicitly returns pointer to object
Default Constructor:
Create a default window defined as:
posRow : offset one row from top of terminal window
posCol : centered in the terminal window
winHgt : height == eight(8) rows
winWid : width == thirty-six(36) columns
All other parameters use the initialization defaults.
The default window is rather useless, so the initialization constructor, below, is recommended.
Input : posRow : Row - position of window within the terminal window posCol : Column - position of window within the terminal window winHeight : Height of window in rows winWidth : Width of window in columns bdrLine : (optional, member enum LineType, ltSINGLE by default) border style i.e. type of line for border Note: specifying either ltHORIZ OR ltVERT will cause the border to be drawn with spaces only (no line). bdrAttrib : (optional, acaATTR_DFLT by default, terminal defaults) border color attributes OR'd value of acAttr bitfields txtAttrib : (optional, acaATTR_DFLT by default, terminal defaults) interior color attributes and text modifiers OR'd value of acAttr bitfields winTitle : (optional, null pointer by default) if specified, text for window title displayed in top border formDef : (optional, null pointer by default) an 'skForm' object which specifies the position and dimensions of the input fields Returns: implicitly returns pointer to object
Initialization Constructor:
Four parameters are required: upper-left row, upper-left column window
height (rows) and window width (columns).
Other parameters, if not specified, are set to default values.
Notes:
Input : none Returns: nothing
Destructor: Return all allocated resources to the system before exit.
The destructor is invoked by deleting the ACWin object. This example
creates the default ACWin object, opens the window, closes the window,
then deletes the object.
ACWin *winPtr = new ACWin;
winPtr->OpenWindow( "Hello World!" );
winPtr->acRead(); // wait for keypress
winPtr->CloseWindow();
delete winPtr;
If the ACWin object was created as an automatic variable, then the
destructor is called when the object goes out-of-scope; that is, when
the execution thread exits the scope in which the object was created.
void myProgram ( void )
{
ACWin acw;
acw.OpenWindow( "Hello World!" );
acw.acRead(); // wait for keypress
acw.CloseWindow();
return; // object goes out-of-scope here
}
Input : initText : (optional, null pointer by default) initial text to be written to window initField: (optional, -1 by default) [CURRENTLY IGNORED] index of target field for storing 'initText' data Ignored if 'initText' not specified. Returns: cursor position (offset) i.e. text insertion point This is the character cell following the text in 'initText', or if no initial text was specified, the upper-left corner.
Complete the window setup sequence and display the window within the terminal display.
For user input fields of the window’s skForm object which have been initialized with text data, the text will be displayed.
On return, the visible cursor will be positioned at the text insertion point (IP) of the field which has the input focus.
IMPORTANT NOTE: 'OpenWindow' should be the first ACWin method called because it completes initialization of the internal data. If any other ACWin method is called before 'OpenWindow', it may cause a reference to uninitialized data.
Input : clear : (optional, 'true' by default) if 'true', clear (erase) the display area if 'false', do not clear the display area fillColor: (optional, terminal dflt attr by default) color attribute used to erase data from window. Returns: nothing
Close the window. Relinquish control of the window object.
By default, the window is erased from the terminal display as part of the closing sequence; but the visual display may optionally be retained, even though control over the space has been returned to the system. This includes returning control of input stream buffering to the system.
Note that the window object still exists in memory. To release the window’s
resources, invoke the destructor i.e. delete the ACWin object.
Example: ACWin *winPtr new ACWin ; ... delete winPtr ;
or if the window was created as an automatic variable, the object will
be deleted when it goes out-of-scope. (see ACWin destructor)
Input : none Returns: nothing
Redraw the window to display any changes that have been made, or to recover
when other data have obscured the the window.
For instance, call RefreshWin after a previoius call to HideWin.
The border will be redrawn, the interior of the window will be cleared, and the text stored in the skForm object (if any) will be displayed.
Input : fillAttr : (optional, default: terminal default attributes) color attribute used to erase data from window. Returns: nothing
Temporarily erase the window from the terminal display.
Data in the skForm object (if any) will be retained; however, any text previously written directly into the window interior will be lost.
To make the window visible again, call RefreshWin.
Input : newPos : (by reference) new row/column position for window origin (upper-left corner of window) newText : (optional, null pointer by default) text to be written to interior of window, beginning at the upper left corner of the window interior. Returns: 'true' if success 'false' if specified position would place any part of the window outside the visible area of the terminal display.
Move the window to another position within the terminal display.
This is simply erasing the window, updating the base position and redrawing
the window at the new position.
Data in the skForm object (if any) will be redrawn as part of the move; however, any text previously written directly into the window interior will be lost. (see 'newText' parameter)
The author has found this to be a useful way to draw the user’s attention to some needed action, and of course a moving window could be the basis for a customized screen-saver application.
Input : newAttr : (optional, acaUSEDFLT by default) new color attributes for text area of window (logical OR of forground and background color) (attributes and text modifiers ) Returns: Cursor position (text insertion point) This is the upper-left corner of the text area (0/0).
Erase all text from the interior (text area) of the window.
The text in the skForm object (if any) is retained, but is not redrawn.
See also RefreshWin.
Input : trgRow : target row (0-based offset into text area) txtAttr : (optional, acaUSEDFLT by default) new color attributes for text area of window (logical OR of forground and background color) (attributes and attribute modifiers ) Returns: Cursor position (text insertion point) This is the left edge of the specified row (trgRow/0). Note: If 'trgRow' is out-of-range, window will not be modified.
Erase text from the specified row of the text area.
Note: ClearRow does not clear the stored text-field data associated with the target row. To clear a single text field within the window, use the ClearField method instead.
Input : fIndx : index of target field within the skForm object gsTxt : (by reference) new text data for field Returns: 'true' if successful 'false' if invalid field index specified
Replace the current contents of the field with new data.
The ’ip’ (text insertion point) of the field is set to zero, and the
cursor is set to the field origin.
Input : fIndx : index of target field within the skForm object gsTxt : (by reference) receives a copy of field text Returns: 'true' if successful gsTxt contains field text data 'false' if invalid field index specified gsTxt cleared to empty string
Get a copy of the current contents of the field.
Input : fIndx : index of target field txtAttr : (optional, acaUSEDFLT by default) new color attributes for the target field (logical OR of forground and background color) (attributes and attribute modifiers ) Returns: 'true' if target field cleared 'false; if fldIndex out-of-range (data not modified)
Erase text from the specified text field. The stored text is deleted, and the display area of the field is cleared.
Input : fIndx : index of target field newIp : character offset into the text of the field ZERO <= newIp <= text characters where ZERO == field origin and any value at or beyond the number of characters in the array signals that IP should be set to end-of-text. (A safe end-of-text value is: gsMAXCHARS.) Returns: 'true' if successful 'false' if invalid field index specified
Set the insertion point (IP) for the field. This will set the cursor position over the character at the specified offset.
If 'fIndx' references the field which has input focus, the visible cursor will also be updated.
Special case: If 'newIp' is greater that the number of characters in the field, IP will be set to end-of-text (over the null terminator).
Input : fIndx: index of target text field If fIndx >= total of fields defined (fCnt), all fields will be refreshed. Returns: nothing
Refresh (erase and redraw) the contents of the specified field, or optionally, refresh all fields defined by the skForm object.
Input focus remains on the currently active field, and cursor is returned to insertion point within that field.
Input : none Returns: nothing
Refresh (erase and redraw) the contents of the field which has input focus.
Input : fIndx : index of target field within the skForm object txtAttr : (acAttr bitfield) a logical OR of forground and background color attributes and attribute modifiers Returns: 'true' if attribute set successfully 'false' if invalid field index specified
Set the color attributes and modifiers for the specified text field. Refresh the field display using the modified attributes.
On return, the cursor is positioned in the field with input focus.
Input : fldIndex: index of target text field The specified field becomes the active field. Returns: index of field with focus
Set input focus to the specified field, and refresh field contents.
The cursor is placed on the text insertion point (IP) of the field.
Note: Read-only fields cannot receive the input focus.
Input : none Returns: index of field with focus
Set input focus to the next field, and refresh field contents.
If already on the last field (index==fCnt-1), wrap around to the first
field of the array.
On return, the cursor is positioned in the field with input focus.
Note: Read-only fields cannot receive the input focus.
Input : none Returns: index of field with focus
Set input focus to the previous field, and refresh field contents.
If already on the first field (index==zero), wrap around to the last
field of the array.
On return, the cursor is positioned in the field with input focus.
Note: Read-only fields cannot receive the input focus.
Input : enable : 'true' == enable user access to Insert key (this is the default) 'false' == disable user access to Insert key (the mode is locked by application) initMode: initial input mode 'true' == Insert Mode 'false' == Overstrike Mode styles : (optional 'false' by default) Enable or disable automatic change of cursor style when Insert/Overstrike is toggled. 'true' == enable cursor style change 'false' == disable cursor style change insStyle: (optional, istyleDFLT by default) cursor style for insert mode referenced only when the 'styles' flag is set ovrStyle: (optional, ostyleDFLT by default) cursor style for overstrike mode referenced only when the 'styles' flag is set Returns: 'true' if Insert/Overstrike toggle enabled, else 'false'
Enable or disable user access to the Insert/Overstrike input mode when user is editing a field, and specify the initial mode.
Insert/Overstrike toggle is active by default, and the initial mode is Insert Mode. For some fields, or some kinds of data, however, it is useful to set one mode or the other and lock out user access.
Optionally enable or disable cursor style change when
Insert/Overstrike mode is toggled. This provides a visual cue
to the user whether Insert mode or Overstrike mode is active.
Optionally, the cursor style for each mode may be specified as
a member of enum CurStyle (excluding csShow and csHide).
Input : exitChar : when this character is received, return to caller focusFld : (by reference) receives the index of the field with input focus on return to caller. Returns: keycode of last key pressed
Interactively edit the fields defined within the skForm object.
The skForm class defines an array of user-interface fields within the window which can be used to create an interactive user interface within a console application.
Keyboard input is captured, formatted and written into the fields. Certain
“special keys” are defined for navigating within and among the
fields. These keycodes are discussed in the chapter on terminal configuration.
Please See Soft Echo Options for more information.
A technical description of the skForm class and the associated skField class as well as a discussion of user interaction with these objects can be found at: skForm Class and skField Class.
Input : fIndx : (by reference) index of target field On entry, specifies the field to be edited. On return, index of field with input focus. exitChar: (optional, NEWLINE '\n' by default) This character terminates the input loop. allChar : (optional, 'false' by default) if 'false', 'exitChar' controls the loop if 'true', return to caller after each iteration of the loop Returns: last keycode captured
Interactively edit the text within the target field.
Keyboard input is captured, formatted and written into the fields. Certain
“special keys” are defined for navigating within the field or
for signalling the move to a different field. These keycodes are discussed
in the chapter on terminal configuration.
Please See Soft Echo Options for more information.
A technical description of the skField class as well as a discussion of user interaction with these objects can be found at: skField Class.
Input : newTitle : text of window title (empty string or null pointer erases title) titAttr : (optional, existing attributes by default) If specified, this is a logical OR of acAttr values specifying the foreground/background color attributes. See the 'acAttr' enumerated type for details. bdrLine : (optional, ltHORIZ i.e. invalid line type by default) If specified, new border style: ltSINGLE or ltDUAL Returns: 'true' if success 'false' if title truncated to fit
Set the window title.
Draw the title centered in the top border of the window.
Input : txtAttr : (acAttr bitfield) a logical OR of forground and background color attributes and attribute modifiers Returns: nothing
Set the color attributes and modifiers for the window interior (text area).
Input : bdrAttr : (acAttr bitfield) a logical OR of forground and background color attributes and attribute modifiers bdrStyle: (optional, ltHORIZ i.e. an invalid value by default) specify the border line style, either ltSINGLE or ltDUAL Returns: nothing
Set the color attributes and modifiers for the window border.
Optionally, the line style of the border may be changed by specifying one of the valid border line styles, either ltSINGLE or ltDUAL.
Input : txtPos : WinPos-class object indicates the zero-based offset from upper-left corner of window interior txt : text to write in one of the following formats: -- gString object by reference -- wchar_t pointer -- char pointer txtAttr: (optional, existing text attributes by default) text attributes and text modifiers clear : (optional, 'false' by default) if 'false', existing displayed text unmodified if 'true', erase window interior before write Returns: current cursor position (window offset)
Write text to the interior of the window.
This group of methods writes directly into the window’s text area, bypassing
and obscuring any defined text fields.
To write text into one of the input fields within the window, csee Write (field) below.
Input : none Returns: current cursor position (window offset)
Get the current cursor offset within the window’s text area.
Input : Cursor position may be specified in either of 2 ways: wPos : (by reference) offset from upper-left corner of window's text area (0-based offset) OR rOff : row offset cOff : column offset Returns: current cursor position (window offset)
Set the cursor offset within the window’s text area.
Input : fIndx : index of target field txt : text to write in one of the following formats: -- gString object by reference -- wchar_t pointer -- char pointer offset : (optional, -1 by default, indicating that the current insertion point 'ip' should be used) character offset into existing text at which to insert the new text clear : (optional, 'false' by default) if 'false', new text will be added to the existing text as described if 'true', new text will replace the existing text txtAttr: (optional, acaPLAINTEXT i.e. zero by default) (existing text attributes will be used) If specified, text attributes and text modifiers Returns: current insertion point ('ip'), that is, the character offset at which the cursor is positioned. This will be at the point following the inserted text, or at the last character cell of the field. (or zero if invalid field index specified)
Write text to the specified field within the window.
This group of methods inserts the specified text into the existing text of the target field at the specified offset ('ip'); or if the 'clear' flag is set, replaces the existing text. The field is then redrawn to display the updated data.
Input : pos : offset from upper-left corner of text area to upper-left corner of box (0-based) height: number of rows for box width : number of columns for box lType : (optional, ltSINGLE by default) line style member of enum LineType: (ltSINGLE or ltDUAL) bxAttr: (optional, acaUSEDFLT by default) If specified, these are the color attributes used. If not specified, stored text attributes are used. Returns: 'true' if box fits within the window text area 'false' if invalid offset or dimensions specified
Draw a rectangle within the window’s text area.
The position, dimensions, line style and color attributes may be specified. See the example below.
Note that the minimum dimensions for the rectangle are two rows by two columns (2x2). At the minimum dimension, of course there is no space for text within the box.
Input : pos : offset from upper-left corner of window (0-based) length : length of the line: number of number of rows (vertical), or number of columns (horizontal). vertical: 'true' : vertical line 'false' : horizontal line lType : (optional, ltSINGLE by default) line style member of enum LineType: either ltSINGLE or ltDUAL begChar : (optional, null character by default) specify the beginning endpoint character endChar : (optional, null character by default) specify the final endpoint character lnAttr : (optional, acaUSEDFLT by default) If specified, these are the color attributes used. If not specified, stored text attributes are used. Returns: cursor position at the end of the line: For horizontal lines, the column following the last character (limited at right edge of window) For vertical lines, the column below the last character (limited at bottom edge of window)
Draw a horizontal or vertical line within the window’s text area.
— Horizontal lines are drawn left-to-right.
— Vertical lines are drawn top-to-bottom.
This is a specialized instance of the AnsiCmd acDrawLine() method. The only difference is that the parameters are range checked to fit entirely within the window. Note that if an endpoint of the line intersects the border of the window, the endpoint will be drawn using the color attributes of the border, while the portion of the line within the text area of the window will be drawn using the color attributes of the window interior, or the attributes specified by the optional 'lnAttr' parameter.
Note: If the line intersects the window border, the endpoint character will be automatically selected to match the intersection of the drawn line and the border line style. As a corollary to this automatic character selection, avoid positioning the start of a line such that it would obscure the window title (if any). Definitions for the line-drawing characters may be found in AnsiCmdDef.hpp.
Input : fIndx : index of target field if 'fIndx' == number of fields defined, then draw an outline around each field. lType : (optional, ltSINGLE by default) line style member of enum LineType: ltSINGLE or ltDUAL lnAttr : (optional, acaUSEDFLT by default) If specified, color attributes to be used. If not specified, stored text attributes used. Returns: 'true' if successful 'false' if invalid field index or insufficient space around the target field
Draw an outline around the outside of the specified field within the window border.
The target field must have at least one space open on all sides. That is, it must not be positioned against the window border, and must not be adjacent to any other field.
This method calculates the position and dimensions for the outline and then calls the DrawBox method described above.
Note: Potential incursion into the border is range checked; however, potential incursion into other fields is not tested. Beware!
Some developers will want to write directly into the window, while others will want to design an array of text-input fields for user interactions which are defined by Some Kind of Form i.e. the skForm class.
If the ACWin constructor is called without specifying an skForm object, a default skForm object is created based on the size of the window. If the window is small (less than 1,000 character cells), then the skForm object is created with one(1) skField. Else, the skForm will generate an array of skField objects, one per row of the window interior.
To achieve direct control over the way the skForm object is configured, a pointer to an skForm template object (’formDef’)is passed to the ACWin constructor.
The position and dimensions of each field must fall entirely within the text area of the window, and the fields may not overlap. Although range checking and automatic adjustments of these fields is performed, an over-caffinated developer could still cause chaos, so it is important to carefully verify the parameters which define the individual fields.
There are several ACWin objects created in the test code included with this library. Some tests write text directly into the window, while others write into the defined fields (or some combination of the two). Please refer to those examples, as well as the discussion of skForm and skField objects below (see skForm Class).
To create an skForm template, allocate a new object specifying the number
of fields and the row/column offset from the upper left corner of the window
interior to the upper left corner of the target area for the form.
Here we define an skForm object with two(2) fields with the form origin at
offset 0,0. This is the upper left corner of the window interior space.
skForm *skfPtr = new skForm( 2, 0, 0 ) ;
Initialize the FORM-LEVEL members. Note that ’fCnt’ (the number of elements in the array) is initialized during instantiation, and must not be changed. Also, the ’base’ value (offset) is overridden by the ACWin initialization.
skfPtr->ins = false ; // insert/overstrike flag
skfPtr->insc = false ; // cursor shape for insert/overstrike
skfPtr->togg = true ; // insert/overstrike lock
skfPtr->beep = true ; // make noise if invalid user input
skfPtr->fi = ZERO ; // initial field index
Initialize the FIELD-LEVEL members:
WinPos wpul(1,1) ;
short f = ZERO ;
skfPtr->fld[f].orig = wpul ; // origin (row/column offset) for field
skfPtr->fld[f].hgt = 1 ; // field height
skfPtr->fld[f].wid = winWIDTH - 4 ; // width of field
skfPtr->fld[f].ip = ZERO ; // text insertion point (offset into field)
skfPtr->fld[f].txt = "Some text for field 0." ;
wpul.row += 2 ; // position of next field==two rows below
++f ;
skfPtr->fld[f].orig = wpul ;
skfPtr->fld[f].hgt = 1 ;
skfPtr->fld[f].wid = winWIDTH - 4 ;
skfPtr->fld[f].ip = 5 ;
skfPtr->fld[f].txt = "Some text for field 1." ;
The initialized skForm template is then passed as a parameter for the ACWin constructor.
Initialization of an skForm object as a parameter for creating a dialog window is shown above.
Accessing the form provides a user interface, either by editing the contents of the form as a whole EditForm, or by editing individual fields within the form EditField.
After the ACWin object has been created, and the window has been opened, The selected edit method is called to give the user access to the field(s).
Example of calling the EditForm method. This is a simplified version of the sequence used in the Test_Form test method.
//* Define an ACWin object * ACWin *winPtr = new ACWin ( winROW, winCOL, winHEIGHT, winWIDTH, ltSINGLE, acAttr(acaFGb_BROWN | acaBG_BLUE), acAttr(acaFG_RED | acaBG_GREY), " Window Formatted With \"skForm\" ", skfPtr // partially-initialized skForm object ) ; //* Open the window (make it visible) * wpos = winPtr->OpenWindow ( " Edit the fields as desired." ) ; //* Configure the functionality of the "special" Insert key * winPtr->InsertKey ( true, true, true ) ; //* Get User Input * winPtr->EditForm ( NEWLINE, fldIndx ) ; //* Close the window and delete the object.* winPtr->CloseWindow () ; delete winPtr ;
Example of calling the EditField method in a loop:
In this example, EditField returns to caller after each keystroke so that
the application can closely monitor user input. This is done by setting
the 'allChar' flag as the third parameter for the call to EditField.
The loop terminates when the user presses the Enter key ('\n').
while ( (wkey = winPtr->EditField ( fIndx, NEWLINE, true )) != NEWLINE ) { //* Update Insert/Overstrike report * if ( skfp->ins != insFlag ) { winPtr->Write ( wpIns, (skfp->ins ? L"<INS>" : L"<OVR>"), (skfp->ins ? acAttr(acaFG_GREEN | acaBG_DFLT) : acAttr(acaFG_BLUE | acaBG_DFLT)) ) ; insFlag = skfp->ins ; } //* Report the data members of each field * this->tseReport ( *skfp, wpRpt ) ; winPtr->RefreshField ( skfPtr->fi ) ; }
This loop is used in the "softEchoA" section of the Test_SoftEcho
test method. Invoke the test to see this loop in action:
epts --ansi=Tea
--- --- --- --- ---
Note that it is possible to create a stand-alone skForm object outside
the dialog window; however, doing so would require a deeper knowledge of the
user-interface mechanics than most applications would need to have. Therefore,
it is recommended that the windowed version of the skForm always be used.
Note also that if desired, the skForm object can be displayed in an
“invisible” (borderless) window. In fact, many of the
skForm tests included with the AnsiCmd library use a borderless window.
See the Test_SoftEcho tests for examples of this usage.
Next: Building from Source, Previous: ACWin Class, Up: AnsiCmd Class Link Library [Contents][Index]
The methods described in this chapter test all major functionality of the AnsiCmd class and the AnsiCmd library as a whole.
These methods are not required for application development, and are therefore
under a conditional compile directive so they can be disabled in a production
build. The EarthPoints test application includes these tests in order to
demonstrate all AnsiCmd functionality.
Please see Build Options for more information on conditional
compilation options.
Each test may be invoked through a command line option. Please see Invoking - AnsiCmd Tests for a list of available options.
The following is a list of the primary test methods found in the
AnsiCmdTest.cpp source file.
Each method header contains detailed information about that test, and
exhaustive comments are sprinkled throughout the test code to indicate
what is being tested, how it is being tested, and
why it is being tested. These comments should answer most
questions about the AnsiCmd library, and at the very least, they offer
an example of how code should be commented.
Editorial: Many students misunderstand the purpose of comments within the source code. Comments DO NOT explain what your code does. Rather, comments describe what your code is intended to do. That is why comments are (nearly) always written before the code itself. Comments explain to you what needs to be done, so that after the code is written and fully functional, you can compare the code with the comments to see if they agree; and if not, adjust the one that is incomplete. — Software Sam |
Many of these methods also invoke support methods for user interface duties or for various often-used calculations.
Note also that many of these test methods write diagnostic data to the debugging log: "dbg.log" created in the source code directory.
This method is called from the application layer by the public method: ansiTest which determines whether the conditionally-compiled test code is present in the library.
ansiTest_Menu is the entry point for invoking the individual tests.
The command-line arguments are validated and formatted as call parameters,
and the appropriate test (or test sub-menu) is invoked.
This method is provided so that the application developer can write experimental code and test it before moving it to the application. Because this is an AnsiCmd-class member method, the test code has access to all the internal functionality of the library.
The Test_Sandbox method is presented here in its entirety.
This is the best ride in the amusement park.
Have fun!!
void AnsiCmd::Test_Sandbox ( wchar_t parmA, wchar_t parmB ) { gString gsOut( "Welcome to the Sandbox!\n" ) ; this->ttyWrite ( gsOut ) ; //* Create Tests Here... * //* --- End of Sandbox Area - Do Not Modify This Line --- ** this->acSetCursor ( aesCUR_ABSPOS, (this->termRows - 1), 1 ) ; } //* End Test_Sandbox() *
Next: gString Text Tool, Previous: Development and Testing, Up: AnsiCmd Class Link Library [Contents][Index]
The AnsiCmd library and the EarthPoints test application are written in C++ and are built with the GNU C++ compiler and linker. No additional link libraries or third-party tools are needed.
The AnsiCmd library is compiled using the GNU/G++ compiler which is invoked through the ’gmake’ (’make’) utility. The compile and linking instructions are contained in the file named ’Makefile’.
Conditional compilation directives control the build options, both for the AnsiCmd class library and the EarthPoints application.
Because the AnsiCmd class as well as the EarthPoints application are primarily experimental in design, a large number of conditional-compilation directives are defined to assist in development and debugging of the code. The following is a list of the directives which persist beyond the immediate needs of the programming day.
The two directives which are integral to the AnsiCmd design are the DEBUG_ANSICMD and DEBUG_LOG directives. Some, or all of the other directives and the code they control may be removed when the code has become more stable.
The names of all the conditional compile directives are very intentionally
formatted in the same way. (This is a hint, dear student. :-)
To see all debugging directives in the code use the grep utility:
grep -n '[#]define DEBUG_' *.[hc]pp
Please see Development and Testing for more information.
All other debugging directives in the AnsiCmd source code are nested within this directive. Setting the definition to zero SHOULD disable all debugging code within the AnsiCmd class, including all the testing methods.
As distributed, the package should have DEBUG_ANSICMD enabled, and
all other debugging directives disabled. To test this, after unpacking
the archive, use the 'grep' utility to test this:
grep -n '#define DEBUG_' *.[hc]pp | grep '[(]1[)]'
(This is why OCD is not really a “disorder” at all. :-)
If enabled (1), the file will be created in the source code directory with the name: “dbg.log”. If a file of that name already exists, it will be overwritten. The file is closed before the program exits.
The log file contains detailed data on the program execution sequence and
the results of specific operations. For instance it can report configuration
data or interim results of binary operations such as:
decode( fgIndex:04 hue:00 shade:00 r:0 g:0 b:0 )
( bgIndex:02 hue:00 shade:00 r:0 g:0 b:0 )
---r brfc --mods--- --bgnd--- --fgnd---
b0000-0000-0000-0111-0000-0010-0000-0100
The test code uses the debugging log file (see above) to report the transmission of the ANSI escape sequence command and the capture of the response.
The ANSI escape sequence for get-cursor-position is the most complex of the escape sequences defined by the standard. This is because after issuing the command, the response is returned to the application as an escape sequence via 'stdin'. This opens the possibility of trashing the display.
For this reason, special attention is given to the algorithm used to capture the incomming data. — It works, but keep an eye on it.
The test code uses the debugging log file (see above) to report the captured byte sequences, convert them to standard keycodes and determine whether the keycode belongs to the group of “special” i.e. cursor-control keys.
The test code uses the debugging log file (see above) to report the contents of the the skForm object’s data members.
This method displays the supported “web-safe” colors by setting the background color attribute. The directive is used to temporarily render the web-safe colors by setting the foreground instead of the background.
The results of parsing the command-line arguments are written to the terminal window, and the application then waits for the user to press the ENTER key before continuing program execution.
To test the build, invoke with a request for the EarthPoints version number. You should get something similar to the following:
Documentation for the AnsiCmd library is provided in both Texinfo (info) format and HTML format.
To view the HTML-format documentation, navigate to:
AnsiCmd/Texinfo
then load the 'ansicmd.html' document into your favorite browser.
Note that the 'infodoc-styles.css' CSS style definition file
must be in the same directory as the HTML document.
To view the Texinfo (info) documentation, navigate to:
AnsiCmd/Texinfo
then view the documentation using the following command:
info -f ansicmd.info
Follow these steps to install the AnsiCmd documentation into the ‘info’ database.
For global system users, this is typically:
/usr/share/info/dir
This will open the top-level menu of the Info system.
Verify that your new entry is beautifully displayed and that
the new Info document is accessible:
First, press the forward-slash key '/' (search)
Then, type: AnsiCmd-class Library (and press ENTER)
The highlight should now be on the menu entry.
Press ENTER (RET) key again, and verify that the main page of the AnsiCmd
documentation is displayed.
Then, exit the Info system: 'q' (quit).
If you want to remove the menu entry, use the command:
Next: Technical Support, Previous: Building from Source, Up: AnsiCmd Class Link Library [Contents][Index]
’gString’ is a small, fast and flexible way to seamlessly convert, format and analyze both UTF-8 and wchar_t (’wide’) text.
Next: gString Public Methods, Up: gString Text Tool [Contents][Index]
Modern applications must be designed for a worldwide audience, and for this reason, the application designer must plan for multi-language support.
Fortunately, the Universal Character Set standard ISO/IEC 10646 and UTF-8, the most popular and flexible method of character-encoding smoothly provide all the character sets, alphabets and special characters which are currently in general use.
Unfortunately, the C and C++ languages offer only minimal support for
internationalization. std::string and std::wstring are nothing more than a
cruel joke to a serious application designer. The GTK+ toolkit’s Glib::ustring
class is an excellent internationalization tool, but it requires installation
of the GTK+ toolkit’s ’glib’ and ’glibmm’ libraries. For more information on
Glib::ustring, see:
http://library.gnome.org/devel/glibmm/unstable/classGlib_1_1ustring.html
’gString’ falls halfway between the full feature set of Glib::ustring and the meaningless garbage that is std::string. ’gString’ consists of one C++ header file and one C++ source code module. ’gString’ is integrated into the NcDialog API library, but may also be compiled independently as a small (16Kb) link library or the source may be embedded directly into your application.
Here are the basic ideas you will need to understand in order for your application to smoothly support multiple languages.
See also a discussion of multiple-language support in the NcDialog API.
Next: gString Instantiation, Previous: Introduction to gString, Up: gString Text Tool [Contents][Index]
What follows is a list of all public methods of the gString class.
Methods are arranged in functional groups.
gString Method Name | Chapter Reference |
---|---|
gString [constructor] | see gString Instantiation |
~gString [destructor] | |
operator= | see Assignment Operators |
compose | see Formatted Assignments |
formatInt | see Integer Formatting |
gstr | see Data Access |
ustr | |
copy | see Copying Data |
operator<< | |
substr | |
append | see Modifying Existing Data |
insert | |
limitChars | |
limitCols | |
shiftChars | |
shiftCols | |
padCols | |
strip | |
erase | |
replace | |
loadChars | |
textReverse | |
compare | see Comparisons |
operator== | |
operator!= | |
find | |
findlast | |
after | |
findx | |
scan | |
gscanf | see Extract Formatted Data |
gschars | see Statistical Info |
gscols | |
utfbytes | |
isASCII | |
clear | see gString Miscellaneous |
Get_gString_Version | |
dbMsg |
Next: Assignment Operators, Previous: gString Public Methods, Up: gString Text Tool [Contents][Index]
The following are the ’constructors’ for the gString class.
For those new to C++, a constructor creates an ’instance’ of the class. An instance is a particular, named object, and can be thought of as a complex variable.
Input : none Returns: nothing
Constructor: Initialize members to default values (NULL string).
Input : usrc : pointer to a UTF-8-encoded, null-terminated string charLimit : (optional, gsMAXCHARS by default) maximum number of characters from source array to convert Returns: nothing
Constructor: Convert specified UTF-8-encoded source to gString.
Input : wsrc : pointer to a wchar_t-encoded, null-terminated string charLimit : (optional, gsMAXCHARS by default) maximum number of characters from source array to convert Returns: nothing
Constructor: Convert specified wchar_t (’wide’) source to gString.
Input : iVal : value to be converted Supported value range: plus/minus 9.999999999999 terabytes fWidth: field width (number of display columns) range: 1 to FI_MAX_FIELDWIDTH lJust : (optional, false by default) if true, strip leading spaces to left-justify the value in the field. (resulting string may be less than fWidth) sign : (optional, false by default) 'false' : only negative values are signed 'true' : always prepend a '+' or '-' sign. kibi : (optional, false by default) 'false' : calculate as a decimal value (powers of 10) kilobyte, megabyte, gigabyte, terabyte 'true' : calculate as a binary value (powers of 2) kibibyte, mebibyte, gibibyte, tebibyte units : (optional) member of enum fiUnits (fiK by default) specifies the format for the units suffix. Note that if the uncompressed value fits in the field, then this parameter is ignored. Returns: nothing Note: if field overflow, field will be filled with '#' characters.
Constructor: Convert specified integer value to gString.
Please see Integer Formatting, 'formatInt' method group
for formatting details.
Input : fmt : a format specification string in the style of sprintf(), swprintf() and related formatting C/C++ functions. arg1 : pointer to first value to be converted by 'fmt' ... : optional arguments (between ZERO and gsfMAXARGS - 1) Each optional argument is a POINTER (address of) the value to be formatted. Returns: nothing
Constructor: Convert formatting specification and its arguments to gString. Please refer to the compose() method (see Formatted Assignments) for more information.
Technical Note: There is no constructor using a “const wchar_t* fmt” format specification because it would conflict with the constructor which limits the number of characters used to initialize the instance.
Input : gsf : initialized gsForm class object containing parameters for creating a formatted text string. charLimit : (optional, gsMAXCHARS by default) maximum number of characters from source array to convert Returns: nothing
DEPRECATED: May be removed in a future release.
This method seemed like a good idea back in 2011, but neither we,
nor our beta testers have ever had a desire to use it.
Constructor: Convert formatting instructions in gsForm class object to gString. See compose() for more information.
Input : none Returns: nothing
Destructor: Release all resources associated with the gString object.
Object is destroyed either when it goes out of scope, or by explicitly deleting the object.
For those new to C++, please note that if you use the ’new’ keyword to create objects, then those objects persist (take up space) until you explicitly delete them or until the application is closed, even if the pointer to the object has gone out-of-scope. See examples below.
void calling_method ( void ) { gString *gsPtr = playful_kitten ( "Hello World!" ) ; // report contents of object created by called method wcout << gsPtr->gstr() << endl ; delete gsPtr ; // delete object created by called method } gString* playful_kitten ( const char* msg ) { gString gs_local( "I love tuna!" ) ; // local object gString *gsPtr1 = new gString, // global object *gsPtr2 = new gString(msg) ; // global object (initialized) gString *gsArray = new gString[4] ; // global array *gsPtr1 = gs_local ; // be a kitten: play with the strings... gsArray[2] = *gsPtr2 ; gsArray[3] = "Scratch my belly!" ; gsArray[1] = gsArray[3] ; delete gsPtr1 ; // delete object referenced by gsPtr1 delete [] gsArray ; // delete object array referenced by gsArray return gsPtr2 ; // return pointer to object referenced by gsPtr2 // (caller is responsible for deleting object) } // 'gs_local' goes out of scope and is destroyed here
Next: Formatted Assignments, Previous: gString Instantiation, Up: gString Text Tool [Contents][Index]
For those new to C++, an assignment operator assigns (initializes) the object to the left of the ’=’ using the data on the right of the ’=’. You may also hear the term ’overloaded operator’. This just means that the ’=’ assignment operator may be defined in more than one way, so it will perform different tasks according to the context or circumstance.
Input : usrc : pointer to an array of UTF-8-encoded characters Returns: nothing
Assignment operator: converts UTF-8-encoded source to gString.
Input : wsrc : pointer to an array of wchar_t 'wide' characters Returns: nothing
Assignment operator: converts wchar_t (’wide’) source to gString.
Input : gssrc : gString object to be copied (by reference) Returns: nothing
Assignment operator. Copies one gString object to another.
Input : gsf : an initialized gsForm object (by reference) Returns: nothing
DEPRECATED: May be removed in a future release.
Assignment operator: Converts gsForm-class instructions to gString.
char utf8Data[] = { "Youth is wasted on the young." } ; gString gs1, gs2 ; gs1 = utf8Data ; gs2 = gs1 ; wcout << gs2 << endl ; - - -> Youth is wasted on the young.
Next: Integer Formatting, Previous: Assignment Operators, Up: gString Text Tool [Contents][Index]
Input : fmt : a format specification string in the style of sprintf(), swprintf() and related formatting C/C++ functions. ... : optional arguments (between ZERO and gsfMAXARGS) Each optional argument is a POINTER (address of) the value to be formatted. - Important Note: There must be AT LEAST as many optional arguments as the number of format specifiers defined in the formatting string. Excess arguments will be ignored; HOWEVER, too few arguments will result in an application crash. You have been warned. Returns: const wchar_t* to formatted data
Create formatted text data from a format specification string including between ZERO and gsfMAXARGS format specifications and their corresponding argument pointers.
Supported data types: %d, %i integer (decimal) %o integer (octal) %u integer (unsigned) %x, %X integer (hex lower or upper case) %f floating point (fixed point) %e, %E floating point (scientific notation, lower/uppercase) %g, %G floating point (normal/exponential, lower/uppercase) %a, %A floating point (hex fraction) %c character %C character (alias for %lc) %s string %S string (alias for %ls) %p pointer %b, %B (extension to swprintf - see description below) %m capture 'errno' description string (see /usr/include/errno.h) %n number of characters printed so far (value written to corresponding argument's location) %% literal '%' See man pages for the C/C++ function 'swprintf' or 'Table of Output Conversions' for additional details.
char Greeting[] = { "Hello!" } ; int iValue = 27064 ; long long int qValue = 7842561 ; long int lValue = 485772 ; short int sValue1 = 28875, sValue2 = -261, sValue3 = 529 ; bool flagValue = true ; float fltValue = 278.5610234 ; double dblValue = 9982.5610234 ; gString gs ; gs.compose( "%s - %d %12hd, %-hi, %#hx %08lXh %lld %hhd", Greeting, &iValue, &sValue1, &sValue2, &sValue3, &lValue, &qValue, &flagValue ) ; wcout << gs << endl ; - - -> Hello! - 27064 28875, -261, 0x211 0007698Ch 7842561 1 gs.compose( "floating downstream:%10.2f and doubling our pace:%.4lf", &fltValue, &dblValue ) ; wcout << gs << endl ; - - -> floating downstream: 278.56 and doubling our pace:9982.5610
See also formatted instantiation: see gString Instantiation.
Because THE PARAMETERS ARE POINTERS TO THEIR DATA, similar to the C/C++ library function ’sscanf’ and friends, the compiler cannot perform automatic promotions from short int* to int* or from float* to double*, and so-on as it would for swprintf.
This implementation was selected because a) it eliminates data-width conflicts when moving among hardware platforms, and b) it reduces code size while increasing performance.
This implementation relies on you, the designer, to use care that the data type you specify in the formatting string matches the data type of the variable referenced by its parameter pointer AND that you use the ’address-of’ (’&’) operator to reference non-pointer variables. Note also that ’literal’ values may not be used as parameters because literals have no address.
The following constructs will produce errors:
gString gs ; char grade = 'A' ; short age = 21 ; int sat = 1550 ; double gpa = 3.75 ; // These examples fail to use the 'address-of' operator for the // referenced variables, and will cause a 'segmentation fault' // i.e. an application crash. gs.compose( "My grade is an %c", grade ) ; gs.compose( "I got a %d on my SAT.", sat ) ; // The above should be: gs.compose( "My grade is an %c", &grade ) ; gs.compose( "I got a %d on my SAT.", &sat ) ; // These examples use mismatched format-specification/variable // reference. This will result in either bad data out OR will // cause a memory-access violation. gs.compose( "I can't wait to be %d.", &age ) ; gs.compose( "My GPA is %1.3f", &gpa ) ; gs.compose( "The hex value of %c is: %#x", &grade, &grade ) ; gs.compose( "My GPA is %1.3lf", 3.88 ) ; // (literal value) // The above should be: gs.compose( "I can't wait to be %hd.", &age ) ; gs.compose( "My GPA is %1.3lf", &gpa ) ; gs.compose( "The hex value of %c is: %#hhx", &grade, &grade ) ;
Parameter Type Checking:
Unfortunately, type-checking of wchar_t formatting strings is not yet
supported by the gnu (v:4.8.0) compiler, (but see wchar.h which is
preparing for the future). Thus, use care when constructing your
’wchar_t fmt’ formatting string. The ’char fmt’ string IS type-checked.
IMPORTANT NOTE:
Depending on your compiler version, you may get a warning when using
the '%b' binary format specification (described below):
"warning: unknown conversion type character ‘b’ in format [-Wformat=]"
This is because the preprocessor does not recognize our custom format
specifier. If this happens, use a ’wchar_t’ (wide) formatting template
to avoid the preprocessor type checking.
Instead of: gs.compose( "bitmask: %b", &wk.mevent.eventType ); Use this (not type checked by the preprocessor): gs.compose( L"bitmask: %b", &wk.mevent.eventType );
We implement an extension to the swprintf output-conversion-specifiers for binary formatted output. We have found this formatting option useful when working with bit masks, for verifying bit-shifting operations during encryption/decryption and other uses.
The standard library ’swprintf’ function has a design flaw for format specifications that include a field-width specifier.
’swprintf’ pads the string to the specified number of CHARACTERS, not the number of COLUMNS as it should do. For ASCII numeric source values this is not a problem because one character equals one display column. For string source data, however, if the source string contains characters that require more than one display column each, then the output may be too wide.
Therefore, for string-source-formatting specifications ONLY:
(examples: "%12s" "%-6s" "%16ls" "%5S" "%-24S")
we compensate for this ethnocentric behavior by interpreting the field-width
specifier as number-of-columns, NOT number-of-characters. For non-ASCII string
data, this will result in output that appears different (and better) than
output created directly by the ’swprintf’ function.
Conversion modifiers that are not fully supported at this time:
’j’, ’z’, ’t’, ’%[’
Also, the ’*’ field-width specification or precision specification which uses
the following argument as the width/precision value IS NOT supported.
Next: Data Access, Previous: Formatted Assignments, Up: gString Text Tool [Contents][Index]
Input : iVal : value to be converted Supported value range: plus/minus 9.999999999999 terabytes fWidth: field width (number of display columns) range: 1 to FI_MAX_FIELDWIDTH lJust : (optional, false by default) if true, strip leading spaces to left-justify the value in the field. (resulting string may be less than fWidth) sign : (optional, false by default) 'false' : only negative values are signed 'true' : always prepend a '+' or '-' sign. kibi : (optional, false by default) 'false' : calculate as a decimal value (powers of 10) kilobyte, megabyte, gigabyte, terabyte 'true' : calculate as a binary value (powers of 2) kibibyte, mebibyte, gibibyte, tebibyte units : (optional) member of enum fiUnits (fiK by default) specifies the format for the units suffix. Note that if the uncompressed value fits in the field, then this parameter is ignored. Returns: 'true' if successful 'false' if field overflow (field will be filled with '#' chars) See notes below on field overflow.
Convert an integer value into a formatted display string of the specified width. Value is right-justified in the field, with leading spaces added if necessary (but see ’lJust’ parameter).
Maximum field width is FI_MAX_FIELDWIDTH. This is wide enough to display a 18-digit, signed and comma-formatted value: '+9,876,543,210,777'
1) Simple comma formatted output if specified field-width is sufficient. 345 654,345 782,654,345 4,294,967,295 2) Output with values compressed to fit a specified field width. 12.3K 999K 12.345M 1.234G 4.3G gString gs ; // gString object 3) Convert a signed integer value: int iValue = 28954 ; // field width == 8, right justified (note: compression unnecessary) gs.formatInt( iValue, 8 ) ; wcout << ':' << gs << ':' << endl ; - - > : 28,954: // field width == 8, left justified (note: compression unnecessary) gs.formatInt( iValue, 8, true ) ; wcout << ':' << gs << ':' << endl ; - - > :28,954: // field width == 6 gs.formatInt( iValue, 6 ) ; wcout << ':' << gs << ':' << endl ; - - > :28.95K: // field width == 6 with forced sign gs.formatInt( iValue, 6, false, true ) ; wcout << ':' << gs << ':' << endl ; - - > :+29.0K: // field width == 5 gs.formatInt( iValue, 5 ) ; wcout << ':' << gs << ':' << endl ; - - > :29.0K: iValue = -28954 ; // convert negative source value // field width == 8, right justified (note: compression unnecessary) gs.formatInt( iValue, 8 ) ; wcout << ':' << gs << ':' << endl ; - - > : -28,954: // field width == 8, left justified (note: compression unnecessary) gs.formatInt( iValue, 8, true ) ; wcout << ':' << gs << ':' << endl ; - - > :-28,954: // field width == 6 gs.formatInt( iValue, 6 ) ; wcout << ':' << gs << ':' << endl ; - - > :-29.0K: // field width == 5 gs.formatInt( iValue, 5 ) ; wcout << ':' << gs << ':' << endl ; - - > : -29K: 4) Convert an unsigned long long integer value (field width == 11): unsigned long long int qValue = 39000009995 ; // decimal compression (gigabytes) with "official" IEC suffix gs.formatInt( qValue, 11, false, false, false, fikB ) ; wcout << ':' << gs << ':' << endl ; - - > :39.000010gB: // binary compression (gibibytes) with "official" IEC suffix gs.formatInt( qValue, 11, false, false, true, fiKiB ) ; wcout << ':' << gs << ':' << endl ; - - > :38.08595GiB:
Please see (NcDialog test application, ’Dialogw’ for more examples.)
The IEC (International System of Quantities) recommends lower-case for
metric (powers of 10) and upper-case for binary (powers of 2).
However, unless you must be accurate in presenting the data according to
IEC standard, it is recommended that you choose the format according to:
your space requirements, visual appeal, and clear communication with your
users.
If you blindly follow style standards against your own better
judgement, then be forever labelled as a weenie.
As described above, the actual formatting of a fixed-width integer field depends on a number of factors. Every effort is made to compress the data to fit within the field while retaining an accurate representation of the numeric value.
There are cases, however, where it is not possible to represent the data within the specified field width. When this occurs, the entire field will be filled with HASH characters '#'.
The specified field must be wide enough to accomodate either the entire, uncompressed value, or the combination of compressed value, units designator and sign (if any). The following situations may cause field overflow.
Fields of seven(7) or more columns can display any formatted value without danger of overflow.
Next: Copying Data, Previous: Integer Formatting, Up: gString Text Tool [Contents][Index]
Input : none Returns: const pointer to array of wchar_t characters
Return a const pointer to the wchar_t (wide) character array.
Input : charCount : (by reference, initial value ignored) receives number of characters in array, including null terminator Returns: const pointer to array of wchar_t characters
Return a const pointer to the wchar_t (wide) character array, along with the number of characters in the array (including the null terminator).
Input : none Returns: const pointer to array of UTF-8 characters
Return a const pointer to the char (UTF-8) character array.
Input : charCount : (by reference, initial value ignored) receives number of characters in array, including null terminator byteCount : (by reference, initial value ignored) receives number of bytes in array, including null terminator Returns: const pointer to array of UTF-8 characters
Return a const pointer to the char (UTF-8) character array, along with the number of characters and the number of bytes in the array (including the null terminator).
short charCount, byteCount ; gString gs( "Wherever you go, there you are!" ) ; const wchar_t* wPtr = gs.gstr() ; const wchar_t* wPtr = gs.gstr( charCount ) ; const char* utf8Ptr = gs.ustr() ; const char* utf8Ptr = gs.ustr( charCount, byteCount ) ;
Next: Modifying Existing Data, Previous: Data Access, Up: gString Text Tool [Contents][Index]
Input : uTarget : pointer to target array to receive UTF-8-encoded text maxBytes : maximum number of bytes to copy (incl. NULL terminator) maxCols : (optional, default == gsMAXCHARS*2) maximum number of display-columns to copy Returns: number of bytes copied (incl. NULL terminator)
Copy gString text to specified target buffer.
Input : wTarget : pointer to target array to receive wchar_t 'wide' text maxChars : maximum number of characters to copy (incl. NULL) maxCols : (optional, default == gsMAXCHARS*2) maximum number of display-columns to copy Returns: number of characters copied (incl. NULL terminator)
Copy gString text to specified target buffer.
Input : IMPLIED reference to the output stream IMPLIED reference to the gString object Returns: reference to the specified output stream
!! NON-MEMBER METHOD !!
Insertion operator: Copies the contents of the gString object into
the ’wcout’ (wide) standard output stream.
Input : IMPLIED reference to the output stream IMPLIED reference to the gString object Returns: reference to the specified output stream
!! NON-MEMBER METHOD !!
Insertion operator: Copies the contents of the gString object into
the ’cout’ (narrow) standard output stream.
Input : targ : (by reference, initial contents ignored) receives null-terminated contents of specified character range -- If target buffer is a char*, then data returned is a UTF-8 text string. -- If target buffer is a wchar_t*, then data returned is a wchar_t (wide) text string. IMPORTANT NOTE: It is the caller's responsibility to specify a target buffer large enough to hold the data. Recommended: wchar_t wbuff[gsMAXCHARS]; or char ubuff[gsMAXBYTES]; -- If target buffer is a gString object, then both UTF-8 and wchar_t data are returned (with no chance of target buffer overflow). offset : character index at which substring begins (this IS NOT a byte index) charCnt : number of characters to copy (not incl. NULL terminator) Returns: if target is a wchar_t* or gString object, then returns number of characters written to target (not including the NULL terminator) if target is a char*, then returns number of bytes written to target (not including the NULL terminator) Note: returns ZERO if either 'offset' or 'charCnt' out of range Note: If 'charCnt' extends beyond the end of the source data, then returns the available data.
Copy the specified character range to target buffer.
These methods copy the indicated substring (null terminated) to
the target buffer, leaving the original data unchanged.
If you have a fixed-format field, then the offset and character count will be known in advance. Otherwise you can use the ’find()’ method to locate the substring to be copied.
Please Note: The number of bytes can NEVER be assumed to be the same as the number of characters.
Please refer to the ’Multi-language Support’ chapter of the ’ncdialogapi’ documentation.
gString gs( "That's not flying, that's falling -- with style!\n" "Buzz Lightyear" ) ; char utf8Data[gsMAXBYTES] ; wchar_t wideData[gsMAXCHARS] ; gs.copy( utf8Data, gs.utfbytes() ) ; gs.copy( wideData, gs.gschars() ) ; gString gstream( "You're a child's TOY! -- Woody" ) ; wcout << gstream << endl ; // get a copy of the first word starting with 'c' gString AusAnimal( "Aardvark Kangaroo Cockatoo Dingo Wombat " ) ; gString gsc ; short b = AusAnimal.find( " c" ) ; if ( b >= 0 ) { short e = AusAnimal.find( L' ', b + 1 ) ; if ( e > b ) { AusAnimal.substr( gsc, (b + 1), (e - b - 1) ) ; wcout << gsc << endl ; } } - - -> Cockatoo
Next: Comparisons, Previous: Copying Data, Up: gString Text Tool [Contents][Index]
Input : wPtr : pointer to array of wchar_t 'wide' text to be appended OR uPtr : pointer to array of char UTF-8 text to be appended OR wChar : a single, 'wide' character Returns: number of characters in resulting string (incl. NULL terminator) Note: if value returned equals gsMAXCHARS, then some data MAY HAVE BEEN discarded.
Append text to existing gString text data up to a combined length of gsMAXCHARS. Characters in excess of the maximum will not be appended.
gString gs( L"Be kind to your manager." ) ; gs.limitChars( gs.gschars() - 2 ) ; gs.append( L", and other lower forms of life." ) ; wcout << gs << endl ; - - -> Be kind to your manager, and other lower forms of life.
Input : fmt : a format specification string in the style of sprintf(), swprintf() and related formatting C/C++ functions. arg1 : pointer to first value to be converted by 'fmt' ... : optional arguments (between ZERO and gsfMAXARGS - 1) Each optional argument is a POINTER (address of) the value to be formatted. Returns: number of characters in resulting string (incl. NULL terminator) Note: if return equals gsMAXCHARS, then some data MAY HAVE BEEN discarded.
Append formatted text data to existing gString text data up to a combined length of gsMAXCHARS. Characters in excess of the maxmum will not be appended.
Please refer to the ’compose’ method (see Formatted Assignments) for more information on converting data using a format specification string.
short gaddress = 2840 ; wchar_t gdirection = L'E' ; const wchar_t* gstreet = L"Colorado Blvd." ; double gcost = 29.95 ; gString gs( "Gorilla Men's Clothing" ) ; // existing text gs.append( ", %hd %C %S\n Dress shirts on sale, $%.2lf.", &gaddress, &gdirection, gstreet, &gcost ) ; wcout << gs << endl ; - - -> Gorilla Men's Clothing, 2840 E Colorado Blvd. Dress shirts on sale, $29.95.
Input : wPtr : pointer to array of wchar_t 'wide' text to be inserted OR uPtr : pointer to array of char UTF-8 text to be inserted OR wChar : a single wchar_t 'wide' character offset: (optional, ZERO by default) character offset at which to insert specified text into existing text. Note: if specified 'offset' > number of characters in existing text, then acts like 'append' method. Returns: number of characters in resulting string (incl. NULL terminator) Note: if value returned equals gsMAXCHARS, then some data MAY HAVE BEEN discarded.
Insert text into existing gString text data up to a combined length of gsMAXCHARS. Characters in excess of the maximum will be truncated.
gString gs( L"Remember to hurt people!" ) ; gs.insert( L"NOT ", 9 ) ; wcout << gs << endl ; - - -> Remember NOT to hurt people!
Input : charCount : maximum number of characters allowed in formatted data (not including NULL) Range: 1 to gsMAXCHARS-1 Returns: number of characters in the adjusted data (including NULL)
Truncate the data to no more than charCount display characters.
Insert a null terminator after the specified number of characters.
gString gs( "This shirt is available in yellow or red." ) ; gs.limitChars( 34 ) ; gs.append( "only." ) ; wcout << gs << endl ; - - -> This shirt is available in yellow only.
Input : colCount : maximum number of display columns allowed in formatted data Range: 1 to (gsMAXCHARS * 2) Returns: number of columns needed to display the adjusted data Note: If specified column count occurs in mid-character, then the partial character will be removed from the string.
Truncate the data to no more than colCount display columns. Insert a null terminator after the number of characters required to fill the specified number of display columns.
gString gs( "The manual is located at:\n" "http://cdn.funcom.com/aoc/pdf/aoc_manual.pdf" ) ; gs.limitCols( 55 ) ; wcout << gs << endl ; - - -> The manual is located at: http://cdn.funcom.com/aoc/pdf/ Note that there are 25 display columns for the first line, (the newline character requires no column), and 30 columns remain on the second line.
Input : shiftCount: < ZERO: shift data to the left, discarding the specified number of characters from the beginning of the array > ZERO: shift data to the right, padding the vacated positions on the left with 'padChar' ==ZERO: do nothing padChar : (optional, SPACE character, 0x20 by default) when shifting data to the right, use this character to fill the vacated character positions NOTE: Specify a one-column character ONLY as the padding character. (multi-column characters ignored) Returns: number of characters in adjusted array
Shift text data by the specified number of characters.
Note for writers of RTL (right-to-left) languages: In the above descriptions, the terms 'left' and 'right' are used for convenience, but actually 'left' refers to the head of the data and 'right' refers to the tail.
gString gs( "Your balance is: 2,521,697.56 USD" ) ; gs.shiftChars( -17 ) ; wcout << gs << endl ; - - -> 2,521,697.56 USD gs.shiftChars( 5, L'#' ) ; wcout << gs << endl ; - - -> #####2,521,697.56 USD Note: For this example, the optional fill character used for right-shift is L'#'. The default fill character is space (L' ').
Input : shiftCount: < ZERO: shift data to the left, discarding the number of characters equivalent to the specified number of display columns NOTE: May discard one extra column if count falls within a multi-column character. > ZERO: shift data to the right, padding the vacated positions on the left with 'padChar' ==ZERO: do nothing padChar : (optional, SPACE character, U+0020 by default) when shifting data to the right, use this character to fill the vacated column positions NOTE: Specify a one-column character ONLY as the padding character. (multi-column characters ignored) Returns: number of display columns in adjusted array
Shift text data by the specified number of display columns.
Note for writers of RTL (right-to-left) languages: In the above descriptions, the terms 'left' and 'right' are used for convenience, but actually 'left' refers to the head of the data and 'right' refers to the tail.
gString gs( "您的帐户余额是500元" ) ; // "Your account balance is 500 yuan" gs.shiftCols( -14 ) ; wcout << gs << endl ; - - -> 500元 gs.shiftCols( 5, L'.' ) ; wcout << gs << endl ; - - -> .....500元 Note: Most Chinese characters are two display columns wide, therefore we shift 14 columns (7 characters) out on the left. For this example, the optional fill character used for right-shift is L'.' (U+002E, ASCII full stop). The Chinese full-stop (U+3002) MAY NOT be used as a fill character because it is a two-column character.
Input : fieldWidth: number of columns for the adjusted data array padChar : (optional, ASCII space 0x20 by default) character with which to pad the data Note: Specify a one-column character ONLY. Multi-column characters will be ignored. centered : (optional, 'false' by default) if 'false', all padding will be appended at the end of the existing data if 'true', padding will be equally divided between the beginning and end of the existing data Returns: number of display columns in the adjusted array
Append padding to the existing string data to achieve the specified number of display columns.
If the 'centered' flag is set, the padding will be divided equally between the beginning and end of the data to achieve the specified field width. Note that if an odd number of columns is to be added, then the odd column will be placed at the end of the data.
The ‘padCols’ method calculates the number of padding characters needed to fill out the specified field width.
The default padding character is the ASCII space character (20 hex).
Any single-column character may be specified as an alternate padding
character.
Padding will be added until either the specified number of columns is reached, OR until the array contains the maximum number of characters (gsMAXCHARS).
If the fieldWidth specified is <= the current width of the data, then the data will not be modified.
gString gs( "This is a test." ); gs.padCols( 30 ); ==> "This is a test. " gs.padCols( 30, L'#' ); ==> "This is a test.###############" gs.padCols( 30, L'#', true ); ==> "#######This is a test.########" // To create a right-justified field, use 'shiftCols' (see above): gs.shiftCols( (30 - gs.gscols()) ); ==> " This is a test." gs.shiftCols( (30 - gs.gscols()), L'#' ); ==> "###############This is a test."
Input : leading : (optional, 'true' by default) if 'true', strip leading whitespace if 'false', leading whitespace unchanged trailing : (optional, 'true' by default) if 'true', strip trailing whitespace if 'false', trailing whitespace unchanged Returns: number of characters in modified string (incl. NULL terminator)
Strip (remove) leading and/or trailing whitespace from the string data.
Whitespace characters are defined as:
0x0020 single-column ASCII space
0x3000 two-column CJK space
0x0A linefeed character
0x0D carriage-return character
0x09 horizontal-tab character
0x0B vertical-tab character
0x0C formfeed character
“Leading” whitespace is space characters from the beginning of the data to the first non-space character. “Trailing” whitespace is from after the last non-space character through the end of the data.
By default, both leading and trailing whitespace will be removed; however, this action may be modified by resetting the appropriate parameter to ‘false’.
Input : src : source data to be matched, one of the following: -- pointer to a UTF-8 string (max length==gsMAXBYTES) -- pointer to a wchar_t string (max length==gsMAXCHARS) -- a gString object containing the source (by reference) -- a single, wchar_t character offset : (optional, ZERO by default) character index at which to begin search NOTE: This is a character index, NOT a byte offset. casesen: (optional, 'false' by default) if 'false', then scan IS NOT case sensitive if 'true, then scan IS case sensitive The way upper/lowercase are related is locale dependent; Returns: index of first character following the deleted sequence Note: This is the wchar_t character index, NOT a byte index Returns (-1) if: a) no matching substring found b) 'offset' out-of-range c) 'src' is an empty string or a NULL character
Scan the data for a matching substring, and if found, erase (delete) the first occurance of the substring.
Actual comparison is always performed against the ’wide’ character array using wcsncasecmp (or wcsncmp). Null terminator character IS NOT included in the comparison. These comparisons ARE locale dependent.
Input : offset : (optional, ZERO by default) index of first character of sequence to be erased NOTE: This is a character index, NOT a byte offset. length : (optional, gsMAXCHARS by default) if not specified, then erase all characters from 'offset' to end of data if specified, then erase the specified number of characters beginning at 'offset' Returns: index of first character following the deleted sequence Note: This is the wchar_t character index, NOT a byte index Returns (-1) if: a) offset < ZERO b) offset >= number of characters in data c) length <= ZERO (data will not be modified)
Erase (delete) the data sequence specified by ’offset’ and ’length’.
’offset’ is the index of the first character to be deleted, and ’length’ specifies the number of characters to delete.
For the gString object containing the following verbal exchange, erase all occurances of the word 'crapweasel'. gString gs( "Ross : Are you familiar with the word crapweasel?\n" "Paolo: No, I don't know crapweasel.\n" "Ross : You're a huge crapweasel!" ); short index = ZERO ; while ( (index = gs.erase( " crapweasel", index )) >= ZERO ) ; Yields: "Ross : Are you familiar with the word?\n" "Paolo: No, I don't know.\n" "Ross : You're a huge!" Find the substring, "the the" and erase the extra "the". gString gs1( L"There are seven candidates in the the Primary Election." ); gString gs2( L"the " ); short index = gs1.find( "the the" ); gs1.erase( index, (gs2.gschars() - 1) ); Yields: "There are seven candidates in the Primary Election."
Input : src : source data to be matched -- pointer to a UTF-8 string -- pointer to a wchar_t string -- a single, wchar_t character newtxt : data to overwrite existing text -- pointer to a UTF-8 string -- pointer to a wchar_t string -- a single, wchar_t character offset : (optional, ZERO by default) character index at which to begin search NOTE: This is a character index, NOT a byte offset. casesen: (optional, 'false' by default) if 'false', then scan IS NOT case sensitive if 'true, then scan IS case sensitive The way upper/lowercase are related is locale dependent; all : (optional, 'false' by default) if 'false', then replace only the first occurance found if 'true', then replace all occurances of the specified substring Returns: 'true' if successful returns 'false' if error (existing data not modified): a) no matching source substring found b) 'src' is a empty string or a null character c) offset < ZERO or offset is beyond existing data d) modifying the data would cause buffer overflow (>gsMAXCHARS)
Replace the specified source substring, or optionally all matching substrings with the provided substring.
Actual comparison is always performed against the ’wide’ character array using wcsncasecmp (or wcsncmp). Null terminator character IS NOT included in the comparison. These comparisons ARE locale dependent.
Correct the spelling errors in the following data: gString gs( "The land near hare is full of Heres, hoping her and ther." ) ; bool okiday = gs.replace( L"hare", L"here" ) ; Yields: "The land near here is full of Heres, hoping her and ther." okiday = gs.replace( "Here", "Hare", ZERO, true ) ; Yields: "The land near here is full of Hares, hoping her and ther." okiday = gs.replace( L'p', L"pp" ) ; Yields: "The land near here is full of Hares, hopping her and ther." short index = gs.find( "her " ) ; okiday = gs.replace( "her", L"here", index, true, true ) ; Yields: "The land near here is full of Hares, hopping here and there." Then, replace all spaces ' ' with underscores '_'. okiday = gs.replace( L' ', L'_', ZERO, false, true ) ; Yields: "The_land_near_here_is_full_of_Hares,_hopping_here_and_there."
Load the specified number of characters from the source data.
This is useful for extracting data from fixed-width fields when
the contents of the field is unknown.
gs.loadChars( StreetAddress1, 48 );
By default, the new text REPLACES the existing text; however, the ’append’ parameter allows the new text to be appended to the existing text.
The functionality is equivalent to the gString constructor which loads
only the specified number of characters.
See gString Instantiation.
Input : usrc : pointer to a UTF-8 encoded string wsrc : pointer to a wchar_t encoded string charLimit: maximum number of characters (not bytes) from source array to load. Range: 1 through gsMAXCHARS. The count should not include the NULL terminator append : (optional, 'false' by default) if 'false', replace existing text with specified text if 'true', append new text to existing text Returns: number of characters in modified string (incl. NULL terminator)
Replace the existing text with the specified number of characters from the source text. const char* Piggy = // (56 characters) "Spider-pig, Spider-pig does whatever a Spider-pig does." ; gString gs( "Existing text." ) ; gs.loadChars( Piggy, 36 ) ; Yields: "Spider-pig, Spider-pig does whatever" Append specified number of characters from the source text to the existing text. gs.loadChars( " it's told, because it's stupid.", 11, true ) ; Yields: "Spider-pig, Spider-pig does whatever it's told,"
Reverse the order of characters in the text string.
If RTL text data displayed by your application is not formatted as desired, then this method may be used to reverse the character order before writing to the display. This is useful for manipulating both RTL (Right-To-Left) language text and mixed RTL/LTR text.
The ’para’ parameter is useful for outputting columns of numeric data or when the column labels are in an RTL language (see example below).
Although modern web browsers (Firefox, Opera, Chromium, etc.) usually handle RTL text correctly, other applications often do not. This is especially true of terminal emulator software.
See also a discussion of multiple-language support in the NcDialog API.
Input : punct : (optional, 'false' by default) if 'false', invert entire string if 'true' AND if a punctuation mark is seen at either end of the string, invert everything except the punctuation mark(s). typically one of the following: '.' ',' '?' '!' ';' ':' but see note below. para : (optional, 'false' by default) if 'false', invert data as a single character stream if 'true', invert data separately for each logical line (line data are separated by newlines ('\n') rjust : (optional, 'false' by default) if 'false', do not insert right-justification padding if 'true', insert padding for each logical line to right-justify the data (used to right-justify LTR output) Note that right-justification is performed ONLY if the 'para' parameter is true. Otherwise, 'rjust' will be ignored. Returns: number of wchar_t characters in gString object (if return value >= gsMAXCHARS, data may have been truncated)
Note that the const Hebrew strings are written canonically in the source, but are displayed incorrectly in the terminal window by the info reader and by the HTML browser (sorry about that).
// Hebrew: "Are you ready for lunch?" // Sometimes the terminal will inappropriately move the punctuation // to the opposite end of the string. // To prevent this, use the 'punct' option. const wchar_t* const Lunch = L"?םיירהצ תחוראל ןכומ התא םאה" ; gString gs( Lunch ) ; gs.textReverse() ; wcout << gs.gstr() << endl ; OUTPUT (correct except punctuation) : האם אתה מוכן לארוחת צהריים? gs = Lunch ; gs.textReverse( true ) ; wcout << gs.gstr() << endl ; OUTPUT (correct): ?האם אתה מוכן לארוחת צהריים // When the 'punct' flag is set, both leading and trailing punctuation // are identified. // Questions in Spanish use a leading inverted question mark (U+00BF), // and a trailing ASCII question mark (U+003F). // Reverse the internal text but do not reverse the terminal punctuation. gs = "¿ozreumla le arap atsil sátsE?" ; gs.textReverse( true ) ; wcout << gs.gstr() << endl ; OUTPUT : ¿Estás lista para el almuerzo? = = = = = // Reverse multi-line text (paragraph formatting). // Ordinary ASCII text is used for this example // to demonstrate the reversal. // The example outputs to an NcDialog window referenced by NcDialog *dp const char* Vaccine = "Have you received your covid-19 vaccination yet?\n "Protect yourself and others,\n" "get your vaccination today!" ; gs = Vaccine ; // Write unmodified text as LTR data: dp->WriteParagraph ( 1, 1, gs, nc.grR, true, false ) ; OUTPUT: Have you received your covid-19 vaccination yet? Protect yourself and others, get your vaccination today! // Reverse the data, without punctuation processing or // right-justification. (Note: all parameters are optional, // but are shown here for clarity.) gs.textReverse( false, true, false ) ; // Write reversed text as LTR data: dp->WriteParagraph ( 1, 1, gs, nc.grR, true, false ) ; OUTPUT: ?tey noitaniccav 91-divoc ruoy deviecer uoy evaH ,srehto dna flesruoy tcetorP !yadot noitaniccav ruoy teg // Write the same data as RTL (note the X origin of 48): dp->WriteParagraph ( 1, 48, gs, nc.grR, true, true ) ; OUTPUT: ?tey noitaniccav 91-divoc ruoy deviecer uoy evaH ,srehto dna flesruoy tcetorP !yadot noitaniccav ruoy teg // Reload the source data and reverse it without punctuation processing, // but WITH right-justification padding. gs = Vaccine ; gs.textReverse( false, true, true ) ; // Write reversed text as LTR data. // Note that the padding character is ASCII space ' ', // however the '-' character is used here to show the padding position. dp->WriteParagraph ( 1, 1, gs, nc.grR, true, false ) ; OUTPUT: ?tey noitaniccav 91-divoc ruoy deviecer uoy evaH --------------------,srehto dna flesruoy tcetorP ---------------------!yadot noitaniccav ruoy teg // Write the same data as RTL (note the X origin of 48): dp->WriteParagraph ( 1, 48, gs, nc.grR, true, true ) ; OUTPUT: ?tey noitaniccav 91-divoc ruoy deviecer uoy evaH --------------------,srehto dna flesruoy tcetorP ---------------------!yadot noitaniccav ruoy teg // Combine RTL text with numeric (LTR) data. // Create an ASCII numeric time string. // Reverse the numeric string. // Insert a Hebrew label: "The current time is: " const wchar_t *timeLabel = L"השעה הנוכחית היא: " ; //(displayed incorrectly) short hours = 12, minutes = 32, seconds = 45 ; gs.compose( "%02hd:%02hd:%02hd", &hours, &minutes, &seconds ) ; gs.textReverse( false, true, false ) ; gs.insert( timeLabel ) ; // Write the data as RTL (note the X origin of 26): dp->WriteParagraph ( 1, 26, gs, nc.grR, true, true ) ; OUTPUT: 12:32:45 :השעה הנוכחית היא
Determining which characters are and are not punctuation is locale specific
(see the 'ispunct()' C-language function).
Rather than rely on the locale used by the application calling this method,
we test against a list of the most common punctuation characters used in
modern languages. If a punctuation character used by your application is
not recognized as punctuation, please send us a note including the Unicode
codepoint and we will add it to the list.
Next: Extract Formatted Data, Previous: Modifying Existing Data, Up: gString Text Tool [Contents][Index]
Input : uStr : (UTF-8 string) to be compared OR wStr : (wchar_t string) to be compared casesen : (optional, 'true' by default) if 'true' perform case-sensitive comparison if 'false' perform case-insensitive comparison length : (optional, gsMAXCHARS by default. i.e. compare to end) maximum number of characters to compare offset : (optional, ZERO by default) If specified, equals the character offset into the gString character array at which to begin comparison. Returns: return value uses the rules of the 'wcsncmp' (or 'wcsncasecmp') library function (see string.h): ZERO, text data are identical > ZERO, first differing char of gString object is numerically larger. < ZERO, first differing char of gString object is numerically smaller.
Compares the text content of the gString object with the specified text.
The comparison is performed against the gString object’s wchar_t character array. The relationship between upper-case and lower-case characters is locale dependent.
Input : gs : (by reference) object whose text is to be compared casesen : (optional, 'true' by default) if 'true' perform case-sensitive comparison if 'false' perform case-insensitive comparison Returns: return value uses the rules of the 'wcsncmp' (or 'wcsncasecmp') library function (see string.h): ZERO, text data are identical > ZERO, first differing char of gString object is numerically larger. < ZERO, first differing char of gString object is numerically smaller.
Compares the text content of two gString objects.
The comparison is performed against the gString objects’ wchar_t character arrays. The relationship between upper-case and lower-case characters is locale dependent.
Input : gs2 : (by reference) gString object containing string to be compared Returns: 'true' if the strings are identical, else 'false'
Comparison operator: Compares the text content of two gString objects.
The comparison is performed against the wchar_t character arrays of the two objects. The comparison is is case-sensitive.
Input : gs2 : (by reference) gString object containing string to be compared Returns: 'true' if the strings are different, else 'false'
Comparison operator: Compares the text content of two gString objects.
The comparison is performed against the wchar_t character arrays of the two objects. The comparison is is case-sensitive.
Input : src : source data to be matched, one of the following: -- pointer to a UTF-8 string (max length==gsMAXBYTES) -- pointer to a wchar_t string (max length==gsMAXCHARS) -- a gString object containing the source (by reference) -- a single, wchar_t character offset : (optional, ZERO by default) character index at which to begin search -- if out-of-range, then same as if not specified casesen: (optional, 'false' by default) if 'false', then scan IS NOT case sensitive if 'true, then scan IS case sensitive The way upper/lowercase are related is locale dependent; maxcmp : (optional, (-1) by default) -- if not specified, then scan for a match of all characters in 'src' (not including null terminator) -- if specified, then scan for a match of only the first 'maxcmp' characters of 'src' -- if out-of-range, then same as if not specified Returns: index of matching substring or (-1) if no match found Note: This is the wchar_t character index, NOT a byte index
Scan the data for a matching substring and if found, return the index at which the first substring match begins.
Actual comparison is always performed against the ’wide’ character array using wcsncasecmp (or wcsncmp). Null terminator character IS NOT included in the comparison. These comparisons ARE locale dependent.
Input : src : source data to be matched, one of the following: -- pointer to a UTF-8 string (max length==gsMAXBYTES) -- pointer to a wchar_t string (max length==gsMAXCHARS) -- a gString object containing the source (by reference) -- a single, wchar_t character casesen: (optional, 'false' by default) if 'false', then scan IS NOT case sensitive if 'true, then scan IS case sensitive The way upper/lowercase are related is locale dependent; Returns: index of last matching substring or (-1) if no match found Note: This is the wchar_t character index, NOT a byte index
Scan the data for the last occurance of the matching substring and if found, return the index at which the substring match occurs.
Actual comparison is always performed against the ’wide’ character array using wcsncasecmp (or wcsncmp). Null terminator character IS NOT included in the comparison. These comparisons ARE locale dependent.
Input : src : source data to be matched, one of the following: -- pointer to a UTF-8 string (max length==gsMAXBYTES) -- pointer to a wchar_t string (max length==gsMAXCHARS) -- a gString object containing the source (by reference) offset : (optional, ZERO by default) character index at which to begin search -- if out-of-range, then same as if not specified casesen: (optional, 'false' by default) if 'false', then scan IS NOT case sensitive if 'true, then scan IS case sensitive The way upper/lowercase are related is locale dependent; Returns: index of the character which follows the matching substring or (-1) if no match found Note: This is the wchar_t character index, NOT a byte index
This method is very similar to the ’find()’ method above, but instead of returning the index to the beginning of the substring, returns the index of the character which FOLLOWS the substring.
Input : srcChar: (optional, L' ' by default) character to be skipped over offset : (optional, ZERO by default) if specified, equals the character offset into the character array at which to begin the scan. Returns: a) If successful, returns the index of first character which DOES NOT match specified character. b) If the scan finds no character which is different from the specified character, OR if 'offset' is out of range, OR if the specified character is the null character, the return value indexes the null terminator of the array. Note: This is the wchar_t character index, NOT a byte index
Scan the text and locate the first character which DOES NOT match the specified character.
This method is used primarily to scan past the end of a sequence of space (' ') characters (0x0020), but may be used to skip over any sequence of a single, repeated character. Note that the character specified must be a ‘wide’ (wchar_t) character.
See also the ’scan’ method below which scans to the first non-whitespace character.
Input : offset : (optional, ZERO by default) if specified, equals the character offset into the character array at which to begin the scan. Returns: a) If successful, returns the index of first non-whitespace character b) If the scan finds no non-whitespace character OR if 'offset' is out of range, the return value indexes the null terminator of the array. Note: This is the wchar_t character index, NOT a byte index.
Scans the text array and returns the index of the first non-whitespace character found.
Whitespace characters are defined as:
0x0020 single-column ASCII space
0x3000 two-column CJK space
0x0A linefeed character
0x0D carriage-return character
0x09 horizontal-tab character
0x0B vertical-tab character
0x0C formfeed character
gString str1( "Toys for Tots" ) ; gString str2( "The Tin Drum" ) ; // compare with UTF-8 string short result = str1.compare( "Toys for Tots" ) ; // compare with wchar_t string short result = str2.compare( L"The Tin Drum" ) ; // compare gString objects if ( str1 == str2 ) { /* do stuff */ } if ( str1 != str2 ) { /* do stuff */ } gString gs( L"Tiny Tim had a titillating tour of Times Square." ) ; // find first instance of substring "tim" (not case sensitive) short tIndex = gs.find( "tim" ) ; wcout << &gs.gstr()[tIndex] << endl ; - - -> Tim had a titillating tour of Times Square. // find the next instance of "tim" gString gsSub( "tim" ) ; // search string in a gString object tIndex = gs.find( gsSub, tIndex + 1 ) ; wcout << &gs.gstr()[tIndex] << endl ; - - -> Times Square. // find first instance of substring "ti" (case sensitive) tIndex = gs.find( L"ti", 0, true ) ; wcout << &gs.gstr()[tIndex] << endl ; - - -> titillating tour of Times Square. // match the first three characters of the search string tIndex = gs.find( L"squirrel", 0, false, 3 ) ; wcout << &gs.gstr()[tIndex] << endl ; - - -> Square. // find first instance of L'R' (not case sensitive) tIndex = gs.find( L'R' ) ; wcout << &gs.gstr()[tIndex] << endl ; - - -> r of Times Square. // extract the filename from path/filename string gString gs( "/home/sam/SoftwareDesign/NcDialog/Dialog1/gString.hpp" ) ; if ( (tIndex = gs.findlast( L'/' )) >= 0 ) wcout << &gs.gstr()[tIndex + 1] << endl ; - - -> gString.hpp // insert text after first instance of substring gString gs( "I think that a parrot would be an ideal pet." ) ; short pIndex = gs.after( L"would" ) ; gs.insert( " NOT", pIndex ) ; - - -> I think that a parrot would NOT be an ideal pet.
For more examples of using gString-class methods, please refer to
Test #6 of the ’Dialogw’ test application.
Next: Statistical Info, Previous: Comparisons, Up: gString Text Tool [Contents][Index]
Input : fmt : a format specification template in the style of swscanf() or sscanf() and related C/C++ functions Template may be either a const char* OR a const wchar_t* ... : optional arguments Each optional argument is a POINTER to (address of) the variable to receive the formatted data. - Important Note: There must be AT LEAST as many optional arguments as the number of format specifiers defined in the formatting template. Excess arguments will be ignored; however, too few arguments will return an error condition. (see below) Returns: number of items captured and converted returns 0 if: a) number of format specifications in 'fmt' > gsFormMAXARGS b) number of format specifications in 'fmt' > number of optional arguments (pointers to target variables) provided
Scan the text data contained in the gString object and extract data
according to the specified formatting template.
(This is an implementation of the standard C-library ’swscanf’ function.)
The formatting template may be either a 'const wchar_t*' as in a call to 'swscanf', or a 'const char*' as in a call to 'sscanf'.
The formatting template may contain between zero(0) and gsFormMAXARGS format specifiers.
The optional arguments are pointers to the target variables which will receive the formatted data.
As with 'swscanf', the number of optional arguments must be equal
to or greater than the number of format specifiers:
(%d, %63s, %X %lld, %24lls, %[, etc.).
Excess arguments will be ignored; however, unlike the 'swscanf' function,
'gscanf' counts the number of format specifiers and optional arguments,
and if there are too few arguments, the scan will be aborted to avoid an
application crash due to memory-access violation. (You’re welcome :-)
Input : offset: wide-character offset at which to begin the scan Important Note: This IS NOT a byte offset. If offset < 0 || offset > length of data, offset will be silently set to 0. fmt : a format specification template in the style of swscanf() or sscanf() and related C/C++ functions Template may be either a const char* OR a const wchar_t* ... : optional arguments Each optional argument is a POINTER to (address of) the variable to receive the formatted data. - Important Note: There must be AT LEAST as many optional arguments as the number of format specifiers defined in the formatting template. Excess arguments will be ignored; however, too few arguments will return an error condition. (see below) Returns: number of items captured and converted returns 0 if: a) number of format specifications in 'fmt' > gsFormMAXARGS b) number of format specifications in 'fmt' > number of optional arguments (pointers to target variables) provided
This is the same method as described above except that the scan of the data begins at the specified character offset.
short sval1, sval2, sval3, sval4 ; int ival ; long long int llval ; double dval ; char str1[64], str2[16], str3[16], ch1 ; gString gs( "17 % 18 21 22 48A2B 720451 24.325 A country song " "is three chords and the truth. - Willie Nelson" ) ; short cnt = gs.gscanf( L"%hd %% %hd %hd %hd %X %lld %lf %63[^-] %c %16s %16s", &sval1, &sval2, &sval3, &sval4, &ival, &llval, &dval, str1, &ch1, str2, str3 ) ; gString gsOut( "items : %hd\n" "numeric : %hd %hd %hd %hd 0x%04X %lld %4.6lf\n" "text data: \"%s\" %c %s %s\n", &cnt, &sval1, &sval2, &sval3, &sval4, &ival, &llval, &dval, str1, &ch1, str2, str3 ) ; dp->WriteParagraph ( 1, 1, gsOut, dColor ) ; This yields: items : 11 numeric : 17 18 21 22 0x48A2B 720451 24.325000 text data: "A country song is three chords and the truth. " - Willie Nelson A working example may be found in the NcDialog API package, (Dialogw test application, Test #6). - - - - - To begin the scan from a particular offset into the text, the unneeded initial data may either be scanned into a throw-away buffer or the scan offset may be specified directly. For example, to discard the first sixteen(16) characters: wchar_t junk[gsMAXCHARS] ; gs = "Useless garbage: 17 21 34" ; gs.gscanf( L"%16C %hd %hd %hd", junk, &sval1, &svan2, &sval3 ) ; _or_ gs.gscanf ( 16, L"%hd %hd %hd", &sval1, &svan2, &sval3 ) ;
Next: gString Miscellaneous, Previous: Extract Formatted Data, Up: gString Text Tool [Contents][Index]
Input : none Returns: number of characters in the string
Returns the number of characters in the string including the null terminator.
Input : none Returns: number of bytes in UTF-8 string
Returns the number of bytes in the UTF-8-encoded string including the null terminator.
Input : none Returns: number of columns needed to display the data
Returns the number of columns required to display the string.
Input : charCount : (by reference, initial value ignored) on return, contains number of characters in the string including the null terminator. Returns: pointer to number of columns needed for display of each character
Returns a pointer to an array of column counts, one for each character of the text data. Note that number of array elements equals number of characters (plus meta-characters, if any).
This example is from the FileMangler utility. It trims the head of the provided path/filename string to fit within a dialog window. void FmConfig::ecoPathFit ( gString& gsPath, short colsAvail ) { if ( (gsPath.gscols()) > colsAvail ) { gString gst = gsPath ; short width = gst.gscols(), offset = ZERO, charCount ; const short* colArray = gst.gscols( charCount ) ; while ( width > (colsAvail - 3) ) width -= colArray[offset++] ; gsPath.compose( L"...%S", &gst.gstr()[offset] ) ; } } //* End ecoPathFit() *
Input : none Returns: 'true' if data are pure, 7-bit ASCII, else 'false'
Scan the data to determine whether it is pure, 7-bit ASCII.
Next: gString Examples, Previous: Statistical Info, Up: gString Text Tool [Contents][Index]
Input : none Returns: nothing
Reset contents to an empty string i.e. "". The data will consist of a single, NULLCHAR character. The character and byte counts are set to 1 (one), and the column count is zero.
Input : none Returns: pointer to version string
Return a pointer to gString class version number string.
Input : gsmsg : (caller's object, by reference) receives most recent debug message Returns: nothing
FOR DEBUGGING ONLY! Application can retrieve most recent debug message.
Note: This method is visible only if the ENABLE_GS_DEBUG flag is set
in gString.hpp.
Previous: gString Miscellaneous, Up: gString Text Tool [Contents][Index]
The NcDialog API test application ’Dialogw’ contains extensive
examples of gString usage, including working copies of the examples
used in this chapter.
The other NcDialog API test applications also use gString in various ways.
Here, we show just a sample of some basic uses for the gString class.
const char* some_UTF-8_data = "I want to buy an hamburger." ; wchar_t some_wide_data[gsMAXCHARS] ; gString gs( some_UTF-8_data ) ; gs.copy( some_wide_data, gsMAXCHARS ) ;
const wchar_t* some_wide_data = L"I want to buy an hamburger." ; char some_UTF-8_data[gsMAXBYTES] ; gString gs( some_wide_data ) ; gs.copy( some_UTF-8_data, gsMAXBYTES ) ;
const char* Head = "Where" ; const wchar_t* Tail = L"is Carmen Sandiego?" ; gString gs( L" in the world " ) ; gs.insert( Head, ZERO ) ; gs.append( Tail ) ; wcout << gs << endl ; - - -> Where in the world is Carmen Sandiego?
const char* utf8String = "We present" ; const wchar_t* wideString = L"for your enjoyment:" ; const char utf8Char = 'W' ; const wchar_t wideChar = L'C' ; short int ways = 100 ; double dish = 17.57 ; gString gs ; gs.compose( "%s %S %hd %cays to %Cook %Chicken,\n" "and %.2lf side dishes and beverages!", utf8String, wideString, &ways, &utf8Char, &wideChar, &wideChar, &dish ) ; wcout << gs << endl ; - - -> We present for your enjoyment: 100 Ways to Cook Chicken, and 17.57 side dishes and beverages!
Important Note: All parameters are pointers to the data: For strings (and pointers), the address is the name of the variable. For all other data types, including single characters, use the address-of ('&') operator.
This is a formatting method taken from the ’Dialogx’ test application. It breaks a text stream into lines which fit within the dianostic window. It’s not speedy (or particularly smart), but it demonstrates the use of ’gString’ to calculate the space needed to display text data and then formatting the data to fit the space.
//* FormatOutput * //* Input : gsOut : semi-formatted source data //* wpos : start position for display //* lineCount : maximum display lines before truncation //* Returns: nothing void dXClip::FormatOutput ( const gString& gsOut, winPos& wpos, short lineCount ) { short tWidth = (ddCOLS - 2), // inside width of target window maxWidth = tWidth * lineCount,// max columns for message tLines = ZERO ; // loop counter gString gsw( gsOut.gstr() ), gso ; if ( gsw.gscols() > maxWidth ) { // truncate the string if necessary gsw.limitCols ( maxWidth - 3 ) ; gsw.append( L"..." ) ; } do { // break the source into convenient widths gso = gsw ; gso.limitCols( tWidth ) ; gso.append( L'\n' ) ; gsw.shiftCols( -tWidth ) ; this->dpd->ClearLine ( wpos.ypos ) ; // clear target display line wpos = this->dpd->WriteParagraph ( wpos, gso, dxPtr->dColor, true ) ; } while ( ++tLines <= lineCount && gsw.gschars() > 1 ) ; } //* End FormatOutput() *
The example above is just a simple one. To see it in action, please refer to the ’Dialogw’ NcDialog API Test Application, test seven (7). For a more sophisticated example, see the ’DialogTextbox::mlFmtDisplay’ automatic word-wrapping method in the NcDialog API source code.
Next: Copyright Notice, Previous: gString Text Tool, Up: AnsiCmd Class Link Library [Contents][Index]
Console applications have always been the most efficient and easily-implemented of computer programs. What they lacked was a friendly and visually-pleasing user interface.
With the NcDialog API, console applications can now be used and understood by experts and novice users alike.
FileMangler performs all basic file management tasks, as well as performing scheduled and ad-hoc file backup and synchronization activities.
FileMangler runs in a console window, and thus provides access to many system tools not available to a GUI application. FileMangler also provides full support for accessing the local Trashcan.
FileMangler is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.
The HTML version of this document was formatted using ‘idpp’ and is displayed using the ‘infodoc-styles.css‘ definition file. Many more examples are available on the author’s website.
The gString class is lightweight, consisting of one C++ source
module and one header file. The gString class may be directly
integrated into an application, or may be built as a link library.
The gString class is also embedded within the NcDialog API library
(see above).
Conceptually, Taggit is an audio-file tag editor (metadata editor), and is album oriented rather than file oriented so that all audio files in an album may be edited simultaneously.
Taggit is not intended as a full-featured tag editor; for instance, Taggit does not access online databases of audio tag information. Taggit fully supports tag editing for audio formats: MP3, M4A, OGG/Vorbis and WMA.
The OGG/Vorbis I specification is supported for all text tags in '.ogg' and '.oga' audio files.
For MP3 audio files, all tag frames of the ID3v2.3 standard are supported, along with some features of ID3v2.4, such as support for UTF-8 text encoding which enables writing text tags in any language.
Taggit is implemented in four(4) user interface languages: Español (Spanish), Zhōngwén (中文) (Chinese, simplified), Tiếng Việt (Vietnamese) and English (U.S.). Additional user interface languages (both LTR and RTL) may be added with minimum effort.
‘srcprof’ can be used to profile source code for high-level languages such as C, C++ and Java, as well as various assembly languages and scripting languages such as Python, Perl and Ruby. For a complete list of currently-supported source languages, please see the Source Profiler documentation.
’srcprof’ can be used both as a productivity-measurement tool and as a tool for testing source code quality based on an evaluation of its ‘maintainability’.
Source Profiler is a console-based utility, which runs as either a pure, command-line utility, OR as a dialog application based on the NcDialog API.
WaylandCB is a simple C++ class definition which provides console applications with seemless access to the system clipboard.
The application is specifically designed to be a student exercise in creating applications which incorporate a multi-language user interface. Exercalc is implemented in four(4) user interface languages: Español (Spanish), Zhōngwén (中文) (Chinese, simplified), Tiếng Việt (Vietnamese) and English (U.S.). Additional user interface languages (both LTR and RTL) may be added with minimum effort.
‘dvdrep’ can be used to rescue data from any non-encrypted DVD video source disc that is formatted using the Universal Disc Format (UDF) filesystem (as all commercially produced DVD movies are).
‘dvdrep’ takes a layered approach to the analysis of the source disc. A detailed log file is maintained for each step of the process in case manual intervention is needed at a later step.
DVD Repair is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.
Next: Index, Previous: Technical Support, Up: AnsiCmd Class Link Library [Contents][Index]
Next: GNU Free Documentation License, Up: Copyright Notice [Contents][Index]
The GNU General Public License is a free, copyleft license for software and other kinds of works.
The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program—to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.
“This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based on the Program.
To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.
All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.
You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.
A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.
You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see https://www.gnu.org/licenses/.
The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read https://www.gnu.org/licenses/why-not-lgpl.html.
Previous: GNU General Public License, Up: Copyright Notice [Contents][Index]
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Previous: Copyright Notice, Up: AnsiCmd Class Link Library [Contents][Index]
Jump to: | 0
A B C D E F G H I L M N O P R S T V W |
---|
Jump to: | 0
A B C D E F G H I L M N O P R S T V W |
---|