The Cdk matrix widget creates a matrix widget. The following are functions which
create or manipulate the Cdk matrix box widget.
.SHAVAILABLEFUNCTIONS
CDKMATRIX *newCDKMatrix (CDKSCREEN *\f2screen\f1, int \f2xpos\f1, int \f2ypos\f1, int \f2screenRows\f1, int \f2screenCols\f1, int \f2actualRows\f1, int \f2actualCols\f1, char *\f2title\f1, char **\f2rowTitles\f1, char **\f2colTitles\f1, int *\f2colWidths\f1, int *\f2colTypes\f1, int \f2rowSpace\f1, int \f2colSpace\f1, chtype \f2filler\f1, int \f2dominantAttribute\f2, boolean \f2boxMatrix\f1, boolean \f2boxCell\f1, boolean \f2shadow\f1);
.RS3
This function creates a pointer to a matrix widget. The \f2screen\f1 parameter
is the screen you wish this widget to be placed in. The parameter \f2xpos\f1
controls the placement of the object along the horizontal axis. This parameter
can accept an integer value or one of the pre-defined values of \f4LEFT\f1,
\f4RIGHT\f1, and \f4CENTER\f1. The parameter \f2ypos\f1 controls the placement
of the object along the vertical axis. This parameter can accept an integer
value or one of the pre-defined values of \f4TOP\f1, \f4BOTTOM\f1, and \f4CENTER\f1.
The parameters \f2screenRows\f1 and \f2screenCols\f1 are the number of rows and
columns to be displayed on the screen respectively; where \f2actualRows\f1 and
\f2actualCols\f1 are the number of actual rows and columns the matrix has.
The \f2title\f1 parameter is the string which will be displayed at the top of
the widget. The title can be more than one line; just provide a carriage return
character at the line break. The two parameters \f2rowTitles\f1 and \f2colTitles\f1
are the titles along the row and columns respectively. The parameter
\f2columnWidths\f1 is an array of integers stating how wide the individual
columns are to be. The parameter \f2columnTypes\f1 is an array of \f4int\f1
which correspond to the individual column display types. The values of the
array should be assigned a value of type \f4EDisplayType\f1. (it is only
declared an \f4int\f1 out of convenience) The following table outlines valid
values for this field and what the result is.
.RS3
.nf
\f2Display_Type Result\f1
vCHAR Only accepts alphabetic characters.
vLCHAR Only accepts alphabetic characters.
Maps the character to lower case
when a character has been accepted.
vUCHAR Only accepts alphabetic characters.
Maps the character to upper case
when a character has been accepted.
vHCHAR Only accepts alphabetic characters.
Displays a \f4.\f1 when a character
has been accepted.
vUHCHAR Only accepts alphabetic characters.
Displays a \f4.\f1 and maps the
character to upper case when a
character has been accepted.
vLHCHAR Only accepts alphabetic characters.
Displays a \f4.\f1 and maps the
character to lower case when a
character has been accepted.
vINT Only accepts numeric characters.
vHINT Only accepts numeric characters.
Displays a \f4.\f1 when a character
has been accepted.
vMIXED Accepts any character types.
vLMIXED Accepts any character types.
Maps the character to lower case
when an alphabetic character has
been accepted.
vUMIXED Accepts any character types.
Maps the character to upper case
when an alphabetic character has
been accepted.
vHMIXED Accepts any character types.
Displays a \f4.\f1 when a character
has been accepted.
vLHMIXED Accepts any character types.
Displays a \f4.\f1 and maps the
charac}er to lower case when a
character has been accepted.
vUHMIXED Accepts any character types.
Displays a \f4.\f1 and maps the
character to upper case when a
character has been accepted.
vVIEWONLY Uneditable field.
.fi
.RE
The parameters \f2rowSpace\f1 and \f2colSpace\f1 dictate how much white space
is to be between rows and columns respectively. The \f2filler\f1 option is the
character to use in empty space within a cell. The parameter
\f2dominantAttribute\f1 states which between the two, the rows or the columns,
will have the dominant character attributes. This is stated when a cell has
both a row attribute and a column attribute. If the value of the parameter
\f2dominantAttribute\f1 is set to \f2ROW\f1 then the attribute of the row
will be displayed. If it is set to \f2COL\f1 then the column's attributes
will be displayed instead. The \f2boxMatrix\f1 parameter states whether
the widget will be drawn with a box around it or not. The \f2boxCell\f1
parameter states whether or not the individual cells will have boxes drawn
around them. The \f2shadow\f1 parameter accepts a boolean value to turn
the shadow on or off around this widget. If the widget could not be created
then a \f4NULL\f1 pointer is returned.
.RE
int activateCDKMatrix (CDKMATRIX *\f2matrix\f1, chtype *\f2actions\f1);
.RS3
This function activates the matrix widget and lets the user interact with the
widget. The parameter \f2matrix\f1 is a pointer to a non-NULL matrix widget.
If the \f2actions\f1 parameter is passed with a non-NULL value, the characters
in the array will be injected into the widget. To activate the widget
interactively pass in a \f4NULL\f1 pointer for \f2actions\f1. If the character
entered into this widget is \f4RETURN\f1 then this function will return 1.
It will also set the structure member \f4exitType\f1 to \f4vNORMAL\f1.
If the character entered into this widget was \f4ESCAPE\f1 then the widget
will return a value of -1 and the structure member \f4exitType\f1 will be
set to \f4vESCAPE_HIT\f1. The matrix cell contents can be retrieved by using
the \f2info\f1 array of the matrix widget.
.RE
int injectCDKMatrix (CDKMATRIX *\f2matrix\f1, chtype \f2character\f1);
.RS3
This function injects a single character into the widget. The parameter
\f2matrix\f1 is a pointer to a non-NULL matrix widget. The parameter
\f2character\f1 is the character to inject into the widget. If the character
injected into this widget was \f4RETURN\f1 then this function will return 1.
It will also set the structure member \f4exitType\f1 to \f4vNORMAL\f1. If
the character entered into this widget was \f4ESCAPE\f1 then the widget
will return a value of -1 and the structure member \f4exitType\f1 will be
set to \f4vESCAPE_HIT\f1. Any other character injected into the widget
will set the structure member \f4exitType\f1 to \f4vEARLY_EXIT\f1 and the
function will return -1. The matrix cell contents can be retrieved by
using the \f2info\f1 array of the matrix widget.
.RE
void setCDKMatrix (CDKMATRIX *\f2matrix\f1, char **\f2info\f1, int \f2rows\f1, int *\f2columnLengths\f1);
.RS3
This function lets the programmer modify certain elements of an already defined
matrix widget. The parameter \f2info\f1 is an array of \f4char *\f1 which
contains the cell information. The parameter \f2rows\f1 has the number of rows
the parameter \f2info\f1 contains, while \f2columnLengths\f1 has the lengths of
the individual columns in \f2info\f1.
.RE
void setCDKMatrixCell (CDKMATRIX *\f2matrix\f1, int \f2row\f1, int \f2col\f1, char *\f2value\f1);
.RS3
This sets the contents of the cell located by the \f2row\f1 and \f2col\f1 pair. The
value of the cell will be set to \f2value\f1.
.RE
char *getCDKMatrixCell (CDKMATRIX *\f2matrix\f1, int \f2row\f1, int \f2col\f1);
.RS3
This returns the contents of the cell located by the \f2row\f1 and \f2col\f1 pair.
