Man Linux: Main Page and Category List

NAME

       cdk_matrix - curses matrix widget.

SYNOPSIS

       cc [ flag ... ] file ...  -lcdk [ library ... ]

       #include <cdk/cdk.h>

       int activateCDKMatrix (
                      CDKMATRIX *matrix,
                      chtype * actions);

       void cleanCDKMatrix (
                      CDKMATRIX *matrix);

       void cleanCDKMatrixCell (
                      CDKMATRIX *matrix,
                      int row,
                      int col);

       void destroyCDKMatrix (
                      CDKMATRIX *matrix);

       void drawCDKMatrix (
                      CDKMATRIX *matrix,
                      boolean box);

       void eraseCDKMatrix (
                      CDKMATRIX *matrix);

       boolean getCDKMatrixBox (
                      CDKMENTRY *matrix);

       char * getCDKMatrixCell (
                      CDKMATRIX *matrix,
                      int row,
                      int col);

       int getCDKMatrixCol (
                      CDKMENTRY *matrix);

       int getCDKMatrixRow (
                      CDKMENTRY *matrix);

       int injectCDKMatrix (
                      CDKMATRIX *matrix,
                      chtype input);

       int jumpToCell (
                      CDKMATRIX *matrix,
                      int row,
                      int col);

       void moveCDKMatrix (
                      CDKMATRIX *matrix,
                      int xpos,
                      int ypos,
                      boolean relative,
                      boolean refresh);

       int moveToCDKMatrixCell (
                      CDKMATRIX *matrix,
                      int row,
                      int col);

       CDKMATRIX *newCDKMatrix (
                      CDKSCREEN *cdkscreen,
                      int xpos,
                      int ypos,
                      int screenRows,
                      int screenCols,
                      int actualRows,
                      int actualCols,
                      char *title,
                      char **rowTitles,
                      char **colTitles,
                      int *columnWidths,
                      int *columnTypes,
                      int rowSpace,
                      int colSpace,
                      chtype filler,
                      int dominantAttribute,
                      boolean boxMatrix,
                      boolean boxCell,
                      boolean shadow);

       void positionCDKMatrix (
                      CDKMATRIX *matrix);

       void setCDKMatrix (
                      CDKMATRIX *matrix,
                      char *info[MAX_MATRIX_ROWS][MAX_MATRIX_COLS],
                      int rows,
                      int *columnLengths);

       void setCDKMatrixBackgroundAttrib (
                      CDKMATRIX *matrix,
                      chtype attribute);

       void setCDKMatrixBackgroundColor (
                      CDKMATRIX *matrix,
                      char * color);

       void setCDKMatrixBox (
                      CDKMENTRY *matrix,
                      boolean boxWidget);

       void setCDKMatrixBoxAttribute (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixCB (
                      CDKMATRIX *matrix,
                      MATRIXCB callbackFunction);

       int setCDKMatrixCell (
                      CDKMATRIX *matrix,
                      int row,
                      int col,
                      char *value);
                      void setCDKMatrixCells (
                      CDKMATRIX *matrix,
                      char **info,
                      int rows,
                      int cols,
                      int *columnLengths);

       void setCDKMatrixHorizontalChar (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixLLChar (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixLRChar (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixPostProcess (
                      CDKMATRIX *matrix,
                      PROCESSFN callback,
                      void * data);

       void setCDKMatrixPreProcess (
                      CDKMATRIX *matrix,
                      PROCESSFN callback,
                      void * data);

       void setCDKMatrixULChar (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixURChar (
                      CDKMATRIX *matrix,
                      chtype character);

       void setCDKMatrixVerticalChar (
                      CDKMATRIX *matrix,
                      chtype character);

DESCRIPTION

       The  Cdk  matrix  widget  creates  a  matrix widget.  The following are
       functions which create or manipulate the Cdk matrix box widget.

AVAILABLE FUNCTIONS

       activateCDKMatrix
            activates the matrix widget and lets the user  interact  with  the
            widget.   The  parameter  matrix is a pointer to a non-NULL matrix
            widget.  If the actions 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  NULL  pointer  for
            actions.  If the character entered into this widget is RETURN then
            this function will return 1.  It will also  set  the  widget  data
            exitType  to  vNORMAL.   If the character entered into this widget
            was ESCAPE then the widget will return  a  value  of  -1  and  the
            widget  data exitType will be set to vESCAPE_HIT.  The matrix cell
            contents can be retrieved by using the info array  of  the  matrix
            widget.

       cleanCDKMatrix
            clears the information from all cells of the matrix.

       cleanCDKMatrixCell
            clears the information from the specified cell of the matrix.

       destroyCDKMatrix
            removes  the  widget  from  the screen and frees memory the object
            used.

       drawCDKMatrix
            draws the matrix widget on the screen.  If the  box  parameter  is
            true, the widget is drawn with a box.

       eraseCDKMatrix
            removes  the  widget  from  the screen.  This does NOT destroy the
            widget.

       getCDKMatrixBox
            returns true if the widget will be drawn with a box around it.

       getCDKMatrixCell
            returns the contents of the cell located by the row and col  pair.

       getCDKMatrixCol
            returns the current column index.

       getCDKMatrixRow
            returns the current row index.

       injectCDKMatrix
            injects  a single character into the widget.  The parameter matrix
            is a pointer to a non-NULL matrix widget.  The parameter character
            is  the character to inject into the widget.  The return value and
            side-effect (setting the widget data  exitType)  depend  upon  the
            injected character:

            RETURN or TAB
                   the function returns 1.  The widget data exitType is set to
                   vNORMAL.

            ESCAPE the function returns -1.  The widget data exitType  is  set
                   to vESCAPE_HIT.

            Otherwise
                   unless  modified  by  preprocessing,  postprocessing or key
                   bindings,  the  function  returns  -1.   The  widget   data
                   exitType is set to vEARLY_EXIT.

            The  matrix cell contents can be retrieved by using the info array
            of the matrix widget.

       jumpToCell
            provides an interactive method of moving to a cell.  It pops up  a
            scale widget and asks which cell the user wants to go to.  Then it
            performs the jump.

       moveCDKMatrix
            moves the given widget to the given position.  The parameters xpos
            and  ypos  are the new position of the widget.  The parameter xpos
            may be an integer or one of the pre-defined  values  TOP,  BOTTOM,
            and  CENTER.   The  parameter ypos may be an integer or one of the
            pre-defined  values  LEFT,  RIGHT,  and  CENTER.   The   parameter
            relative  states  whether the xpos/ypos pair is a relative move or
            an absolute move.  For example, if xpos =  1  and  ypos  =  2  and
            relative  =  TRUE, then the widget would move one row down and two
            columns right.  If the value of relative was FALSE then the widget
            would  move  to  the  position  (1,2).  Do not use the values TOP,
            BOTTOM, LEFT, RIGHT, or  CENTER  when  relative  =  TRUE.   (weird
            things  may  happen).   The  final  parameter refresh is a boolean
            value which states whether the widget will get refreshed after the
            move.

       moveToCDKMatrixCell
            jumps  to  the given cells dictated by the parameters row and col.
            It returns a value of TRUE or FALSE  depending  if  the  move  was
            successful.

       newCDKMatrix
            creates a matrix widget and returns a pointer to it.  Parameters:

            screen
                 is the screen you wish this widget to be placed in.

            xpos controls  the  placement  of  the object along the horizontal
                 axis.  It may be an integer or one of the pre-defined  values
                 LEFT, RIGHT, and CENTER.

            ypos controls the placement of the object along the vertical axis.
                 It may be an integer or one of the  pre-defined  values  TOP,
                 BOTTOM, and CENTER.

            screenRows and

            screenCols
                 are  the  number  of  rows and columns to be displayed on the
                 screen respectively.

            actualRows and

            actualCols
                 are the number of actual rows and columns the matrix has.

            title
                 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.

            rowTitles and

            colTitles
                 are the titles along the row and columns respectively.

            columnWidths
                 is an array of  integers  stating  how  wide  the  individual
                 columns are to be.

            columnTypes
                 is  an  array  of integers which correspond to the individual
                 column display types.  The values  of  the  array  should  be
                 assigned  a  value of type EDisplayType.  See cdk_display (3)
                 for legal values of EDisplayType.

            rowSpace and

            colSpace
                 dictate how much white  space  is  to  be  between  rows  and
                 columns respectively.

            filler
                 is the character to use in empty space within a cell.

            dominantAttribute
                 states which (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 dominantAttribute is set to ROW then the  attribute
                 of  the  row will be displayed.  If it is set to COL then the
                 column’s attributes will be displayed instead.

            boxMatrix
                 is true if the widget should be drawn with a box around it.

            boxCell
                 is true if the  individual  cells  should  have  boxes  drawn
                 around them.

            shadow
                 turns the shadow on or off around this widget.

            If  the  widget  could  not  be  created  then  a  NULL pointer is
            returned.

       positionCDKMatrix
            allows the user to move the  widget  around  the  screen  via  the
            cursor/keypad keys.  See cdk_position (3) for key bindings.

       setCDKMatrix
            lets  the programmer modify certain elements of an existing matrix
            widget.  The parameter info is an array of char *  which  contains
            the  cell  information.  The parameter rows has the number of rows
            the parameter info contains, while columnLengths has  the  lengths
            of the individual columns in info.

            Do  not  use  this  function.   It  is obsolete, provided only for
            compatibility with older versions of CDK.  Use  setCDKMatrixCells.

       setCDKMatrixBackgroundAttrib
            sets  the  background  attribute  of  the  widget.   The parameter
            attribute is a curses attribute, e.g., A_BOLD.

       setCDKMatrixBackgroundColor
            sets the background color of the widget.  The parameter  color  is
            in the format of the Cdk format strings.  See cdk_display (3).

       setCDKMatrixBox
            sets whether the widget will be drawn with a box around it.

       setCDKMatrixBoxAttribute
            sets the attribute of the box.

       setCDKMatrixCB
            allows  the  programmer  to  set a different widget input handler.
            The parameter callbackFunction is of type MATRIXCB.   The  default
            function is CDKMatrixCallBack.

       setCDKMatrixCell
            sets  the  contents  of  the cell located by the row and col pair.
            The value of the cell will be set to value.

       setCDKMatrixCells,
            lets the programmer initialize  elements  of  an  existing  matrix
            widget.   The  parameter info is an array of char * which contains
            the cell information.  The parameter rows has the number  of  rows
            The  parameter  cols  has the number of columns the parameter info
            contains, while columnLengths has the lengths  of  the  individual
            columns in info.

       setCDKMatrixHorizontalChar
            sets  the  horizontal  drawing  character for the box to the given
            character.

       setCDKMatrixLLChar
            sets the lower left hand corner of the widget’s box to  the  given
            character.

       setCDKMatrixLRChar
            sets  the lower right hand corner of the widget’s box to the given
            character.

       setCDKMatrixPostProcess
            allows the user to have the widget call a function after  the  key
            has  been  applied  to  the widget.  The parameter function is the
            callback function.  The parameter data points to  data  passed  to
            the  callback  function.   To learn more about post-processing see
            cdk_process (3).

       setCDKMatrixPreProcess
            allows the user to have the widget call a function after a key  is
            hit  and  before  the key is applied to the widget.  The parameter
            function is the callback function.  The parameter data  points  to
            data  passed  to  the callback function.  To learn more about pre-
            processing see cdk_process (3).

       setCDKMatrixULChar
            sets the upper left hand corner of the widget’s box to  the  given
            character.

       setCDKMatrixURChar
            sets  the upper right hand corner of the widget’s box to the given
            character.

       setCDKMatrixVerticalChar
            sets the vertical drawing character  for  the  box  to  the  given
            character.

KEY BINDINGS

       When  the  widget  is  activated there are several default key bindings
       which will help the user enter or manipulate the  information  quickly.
       The  following  table  outlines  the  keys  and  their actions for this
       widget.

              +-------------------------------------------------------+
              |Key           Action                                   |
              +-------------------------------------------------------+
              |Left Arrow    Moves one cell to the left.              |
              |Right Arrow   Moves the cell to the right.             |
              |Tab           Moves the cell to the right.             |
              |Up Arrow      Moves one cell up.                       |
              |Down Arrow    Moves one cell down.                     |
              |Next Page     Moves one page forward.                  |
              |Ctrl-F        Moves one page forward.                  |
              |Prev Page     Moves one page backward.                 |
              |Ctrl-B        Moves one page backward.                 |
              |Ctrl-G        Calls  the   function   jumpToCell   and |
              |              requests  which  cell the user wishes to |
              |              jump to.                                 |
              |Ctrl-P        Pastes whatever is in the paste  buffer, |
              |              into the current cell.                   |
              |Ctrl-K        Cuts  the contents from the current cell |
              |              and saves a copy in the paste buffer.    |
              |Ctrl-T        Copies the contents of the current  cell |
              |              into the paste buffer.                   |
              |Ctrl-E        Erases the contents of the current cell. |
              |Delete        Deletes the character before the cursor, |
              |              moves cursor left.  There is no function |
              |              to  delete  the  character at the cursor |
              |              since there are no functions for  moving |
              |              the cursor within the edited text.       |
              |Backspace     Deletes  the  character  before  cursor, |
              |              moves cursor left.                       |
              |Ctrl-H        Deletes the character before the cursor. |
              |Return        Exits the widget and  returns  1.   This |
              |              also  sets  the  widget data exitType to |
              |              vNORMAL.                                 |
              |Escape        Exits the widget and returns  -1.   This |
              |              also  sets  the  widget data exitType to |
              |              vESCAPE_HIT.                             |
              |Ctrl-L        Refreshes the screen.                    |
              +-------------------------------------------------------+

SEE ALSO

       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)

                                                                 cdk_matrix(3)