1cdk_matrix(3)              Library Functions Manual              cdk_matrix(3)
2
3
4

NAME

6       cdk_matrix - curses matrix widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKMatrix (
14                      CDKMATRIX *matrix,
15                      chtype * actions);
16
17       void cleanCDKMatrix (
18                      CDKMATRIX *matrix);
19
20       void cleanCDKMatrixCell (
21                      CDKMATRIX *matrix,
22                      int row,
23                      int col);
24
25       void destroyCDKMatrix (
26                      CDKMATRIX *matrix);
27
28       void drawCDKMatrix (
29                      CDKMATRIX *matrix,
30                      boolean box);
31
32       void eraseCDKMatrix (
33                      CDKMATRIX *matrix);
34
35       boolean getCDKMatrixBox (
36                      CDKMENTRY *matrix);
37
38       char * getCDKMatrixCell (
39                      CDKMATRIX *matrix,
40                      int row,
41                      int col);
42
43       int getCDKMatrixCol (
44                      CDKMENTRY *matrix);
45
46       int getCDKMatrixRow (
47                      CDKMENTRY *matrix);
48
49       int injectCDKMatrix (
50                      CDKMATRIX *matrix,
51                      chtype input);
52
53       int jumpToCell (
54                      CDKMATRIX *matrix,
55                      int row,
56                      int col);
57
58       void moveCDKMatrix (
59                      CDKMATRIX *matrix,
60                      int xpos,
61                      int ypos,
62                      boolean relative,
63                      boolean refresh);
64
65       int moveToCDKMatrixCell (
66                      CDKMATRIX *matrix,
67                      int row,
68                      int col);
69
70       CDKMATRIX *newCDKMatrix (
71                      CDKSCREEN *cdkscreen,
72                      int xpos,
73                      int ypos,
74                      int screenRows,
75                      int screenCols,
76                      int actualRows,
77                      int actualCols,
78                      const char *title,
79                      CDK_CONST char **rowTitles,
80                      CDK_CONST char **colTitles,
81                      int *columnWidths,
82                      int *columnTypes,
83                      int rowSpace,
84                      int colSpace,
85                      chtype filler,
86                      int dominantAttribute,
87                      boolean boxMatrix,
88                      boolean boxCell,
89                      boolean shadow);
90
91       void positionCDKMatrix (
92                      CDKMATRIX *matrix);
93
94       void setCDKMatrix (
95                      CDKMATRIX *matrix,
96                      char *info[MAX_MATRIX_ROWS][MAX_MATRIX_COLS],
97                      int rows,
98                      int *columnLengths);
99
100       void setCDKMatrixBackgroundAttrib (
101                      CDKMATRIX *matrix,
102                      chtype attribute);
103
104       void setCDKMatrixBackgroundColor (
105                      CDKMATRIX *matrix,
106                      const char * color);
107
108       void setCDKMatrixBox (
109                      CDKMENTRY *matrix,
110                      boolean boxWidget);
111
112       void setCDKMatrixBoxAttribute (
113                      CDKMATRIX *matrix,
114                      chtype character);
115
116       void setCDKMatrixCB (
117                      CDKMATRIX *matrix,
118                      MATRIXCB callbackFunction);
119
120       int setCDKMatrixCell (
121                      CDKMATRIX *matrix,
122                      int row,
123                      int col,
124                      const char *value);
125                      void setCDKMatrixCells (
126                      CDKMATRIX *matrix,
127                      CDK_CONST char **info,
128                      int rows,
129                      int cols,
130                      int *columnLengths);
131
132       void setCDKMatrixHorizontalChar (
133                      CDKMATRIX *matrix,
134                      chtype character);
135
136       void setCDKMatrixLLChar (
137                      CDKMATRIX *matrix,
138                      chtype character);
139
140       void setCDKMatrixLRChar (
141                      CDKMATRIX *matrix,
142                      chtype character);
143
144       void setCDKMatrixPostProcess (
145                      CDKMATRIX *matrix,
146                      PROCESSFN callback,
147                      void * data);
148
149       void setCDKMatrixPreProcess (
150                      CDKMATRIX *matrix,
151                      PROCESSFN callback,
152                      void * data);
153
154       void setCDKMatrixULChar (
155                      CDKMATRIX *matrix,
156                      chtype character);
157
158       void setCDKMatrixURChar (
159                      CDKMATRIX *matrix,
160                      chtype character);
161
162       void setCDKMatrixVerticalChar (
163                      CDKMATRIX *matrix,
164                      chtype character);
165

DESCRIPTION

167       The Cdk matrix widget creates a matrix widget.  The following are func‐
168       tions which create or manipulate the Cdk matrix box widget.
169

AVAILABLE FUNCTIONS

171       activateCDKMatrix
172            activates the matrix widget and lets the user  interact  with  the
173            widget.   The  parameter  matrix is a pointer to a non-NULL matrix
174            widget.  If the actions parameter is passed with a non-NULL value,
175            the  characters in the array will be injected into the widget.  To
176            activate the widget interactively  pass  in  a  NULL  pointer  for
177            actions.  If the character entered into this widget is RETURN then
178            this function will return 1.  It will also  set  the  widget  data
179            exitType  to  vNORMAL.   If the character entered into this widget
180            was ESCAPE then the widget will return a value of -1 and the  wid‐
181            get  data  exitType  will  be set to vESCAPE_HIT.  The matrix cell
182            contents can be retrieved by using the info array  of  the  matrix
183            widget.
184
185       cleanCDKMatrix
186            clears the information from all cells of the matrix.
187
188       cleanCDKMatrixCell
189            clears the information from the specified cell of the matrix.
190
191       destroyCDKMatrix
192            removes  the  widget  from  the screen and frees memory the object
193            used.
194
195       drawCDKMatrix
196            draws the matrix widget on the screen.  If the  box  parameter  is
197            true, the widget is drawn with a box.
198
199       eraseCDKMatrix
200            removes  the  widget  from  the screen.  This does NOT destroy the
201            widget.
202
203       getCDKMatrixBox
204            returns true if the widget will be drawn with a box around it.
205
206       getCDKMatrixCell
207            returns the contents of the cell located by the row and col pair.
208
209       getCDKMatrixCol
210            returns the current column index.
211
212       getCDKMatrixRow
213            returns the current row index.
214
215       injectCDKMatrix
216            injects a single character into the widget.  The parameter  matrix
217            is a pointer to a non-NULL matrix widget.  The parameter character
218            is the character to inject into the widget.  The return value  and
219            side-effect  (setting  the  widget  data exitType) depend upon the
220            injected character:
221
222            RETURN or TAB
223                   the function returns 1.  The widget data exitType is set to
224                   vNORMAL.
225
226            ESCAPE the  function  returns -1.  The widget data exitType is set
227                   to vESCAPE_HIT.
228
229            Otherwise
230                   unless modified by  preprocessing,  postprocessing  or  key
231                   bindings,  the  function returns -1.  The widget data exit‐
232                   Type is set to vEARLY_EXIT.
233
234            The matrix cell contents can be retrieved by using the info  array
235            of the matrix widget.
236
237       jumpToCell
238            provides  an interactive method of moving to a cell.  It pops up a
239            scale widget and asks which cell the user wants to go to.  Then it
240            performs the jump.
241
242       moveCDKMatrix
243            moves the given widget to the given position.  The parameters xpos
244            and ypos are the new position of the widget.  The  parameter  xpos
245            may  be  an  integer or one of the pre-defined values TOP, BOTTOM,
246            and CENTER.  The parameter ypos may be an integer or  one  of  the
247            pre-defined  values  LEFT, RIGHT, and CENTER.  The parameter rela‐
248            tive states whether the xpos/ypos pair is a relative  move  or  an
249            absolute move.  For example, if xpos = 1 and ypos = 2 and relative
250            = TRUE, then the widget would move one row down  and  two  columns
251            right.   If  the value of relative was FALSE then the widget would
252            move to the position (1,2).  Do not use the  values  TOP,  BOTTOM,
253            LEFT,  RIGHT,  or  CENTER when relative = TRUE.  (weird things may
254            happen).  The final parameter refresh is  a  boolean  value  which
255            states whether the widget will get refreshed after the move.
256
257       moveToCDKMatrixCell
258            jumps  to  the given cells dictated by the parameters row and col.
259            It returns a value of TRUE or FALSE depending if the move was suc‐
260            cessful.
261
262       newCDKMatrix
263            creates a matrix widget and returns a pointer to it.  Parameters:
264
265            screen
266                 is the screen you wish this widget to be placed in.
267
268            xpos controls  the  placement  of  the object along the horizontal
269                 axis.  It may be an integer or one of the pre-defined  values
270                 LEFT, RIGHT, and CENTER.
271
272            ypos controls the placement of the object along the vertical axis.
273                 It may be an integer or one of the  pre-defined  values  TOP,
274                 BOTTOM, and CENTER.
275
276            screenRows and
277
278            screenCols
279                 are  the  number  of  rows and columns to be displayed on the
280                 screen respectively.
281
282            actualRows and
283
284            actualCols
285                 are the number of actual rows and columns the matrix has.
286
287            title
288                 is the string which will be displayed at the top of the  wid‐
289                 get.   The  title  can  be more than one line; just provide a
290                 carriage return character at the line break.
291
292            rowTitles and
293
294            colTitles
295                 are the titles along the row and columns respectively.
296
297            columnWidths
298                 is an array of integers stating how wide the individual  col‐
299                 umns are to be.
300
301            columnTypes
302                 is  an  array  of integers which correspond to the individual
303                 column display types.  The values  of  the  array  should  be
304                 assigned  a  value of type EDisplayType.  See cdk_display (3)
305                 for legal values of EDisplayType.
306
307            rowSpace and
308
309            colSpace
310                 dictate how much white space is to be between rows  and  col‐
311                 umns respectively.
312
313            filler
314                 is the character to use in empty space within a cell.
315
316            dominantAttribute
317                 states which (the rows or the columns) will have the dominant
318                 character attributes.  This is stated when a cell has both  a
319                 row  attribute  and  a column attribute.  If the value of the
320                 parameter dominantAttribute is set to ROW then the  attribute
321                 of  the  row will be displayed.  If it is set to COL then the
322                 column's attributes will be displayed instead.
323
324            boxMatrix
325                 is true if the widget should be drawn with a box around it.
326
327            boxCell
328                 is true if the  individual  cells  should  have  boxes  drawn
329                 around them.
330
331            shadow
332                 turns the shadow on or off around this widget.
333
334            If  the  widget  could  not  be  created  then  a  NULL pointer is
335            returned.
336
337       positionCDKMatrix
338            allows the user to move the widget around the screen via the  cur‐
339            sor/keypad keys.  See cdk_position (3) for key bindings.
340
341       setCDKMatrix
342            lets  the programmer modify certain elements of an existing matrix
343            widget.  The parameter info is an array of char *  which  contains
344            the  cell  information.  The parameter rows has the number of rows
345            the parameter info contains, while columnLengths has  the  lengths
346            of the individual columns in info.
347
348            Do  not use this function.  It is obsolete, provided only for com‐
349            patibility with older versions of CDK.  Use setCDKMatrixCells.
350
351       setCDKMatrixBackgroundAttrib
352            sets the  background  attribute  of  the  widget.   The  parameter
353            attribute is a curses attribute, e.g., A_BOLD.
354
355       setCDKMatrixBackgroundColor
356            sets  the  background color of the widget.  The parameter color is
357            in the format of the Cdk format strings.  See cdk_display (3).
358
359       setCDKMatrixBox
360            sets whether the widget will be drawn with a box around it.
361
362       setCDKMatrixBoxAttribute
363            sets the attribute of the box.
364
365       setCDKMatrixCB
366            allows the programmer to set a  different  widget  input  handler.
367            The  parameter  callbackFunction is of type MATRIXCB.  The default
368            function is CDKMatrixCallBack.
369
370       setCDKMatrixCell
371            sets the contents of the cell located by the  row  and  col  pair.
372            The value of the cell will be set to value.
373
374       setCDKMatrixCells,
375            lets the programmer initialize elements of an existing matrix wid‐
376            get.  The parameter info is an array of char * which contains  the
377            cell  information.   The parameter rows has the number of rows The
378            parameter cols has the number of columns the parameter  info  con‐
379            tains,  while columnLengths has the lengths of the individual col‐
380            umns in info.
381
382       setCDKMatrixHorizontalChar
383            sets the horizontal drawing character for the  box  to  the  given
384            character.
385
386       setCDKMatrixLLChar
387            sets  the  lower left hand corner of the widget's box to the given
388            character.
389
390       setCDKMatrixLRChar
391            sets the lower right hand corner of the widget's box to the  given
392            character.
393
394       setCDKMatrixPostProcess
395            allows  the  user to have the widget call a function after the key
396            has been applied to the widget.  The  parameter  function  is  the
397            callback  function.   The  parameter data points to data passed to
398            the callback function.  To learn more  about  post-processing  see
399            cdk_process (3).
400
401       setCDKMatrixPreProcess
402            allows  the user to have the widget call a function after a key is
403            hit and before the key is applied to the  widget.   The  parameter
404            function  is  the callback function.  The parameter data points to
405            data passed to the callback function.  To learn  more  about  pre-
406            processing see cdk_process (3).
407
408       setCDKMatrixULChar
409            sets  the  upper left hand corner of the widget's box to the given
410            character.
411
412       setCDKMatrixURChar
413            sets the upper right hand corner of the widget's box to the  given
414            character.
415
416       setCDKMatrixVerticalChar
417            sets the vertical drawing character for the box to the given char‐
418            acter.
419

KEY BINDINGS

421       When the widget is activated there are  several  default  key  bindings
422       which  will  help the user enter or manipulate the information quickly.
423       The following table outlines the keys and their actions for  this  wid‐
424       get.
425
426            ┌───────────────────────────────────────────────────────────┐
427Key               Action                                   
428            ├───────────────────────────────────────────────────────────┤
429            │Left Arrow        Moves one cell to the left.              │
430            │Right Arrow       Moves the cell to the right.             │
431            │Tab               Moves the cell to the right.             │
432            │Up Arrow          Moves one cell up.                       │
433            │Down Arrow        Moves one cell down.                     │
434            │Next Page         Moves one page forward.                  │
435            │Ctrl-F            Moves one page forward.                  │
436            │Prev Page         Moves one page backward.                 │
437            │Ctrl-B            Moves one page backward.                 │
438            │Ctrl-G            Calls   the   function   jumpToCell  and │
439            │                  requests which cell the user  wishes  to │
440            │                  jump to.                                 │
441            │Ctrl-P            Pastes  whatever is in the paste buffer, │
442            │                  into the current cell.                   │
443            │Ctrl-K            Cuts the contents from the current  cell │
444            │                  and saves a copy in the paste buffer.    │
445            │Ctrl-T            Copies  the contents of the current cell │
446            │                  into the paste buffer.                   │
447            │Ctrl-E            Erases the contents of the current cell. │
448            │Delete            Deletes the character before the cursor, │
449            │                  moves cursor left.  There is no function │
450            │                  to delete the character  at  the  cursor │
451            │                  since  there are no functions for moving │
452            │                  the cursor within the edited text.       │
453            │Backspace         Deletes  the  character  before  cursor, │
454            │                  moves cursor left.                       │
455            │Ctrl-H            Deletes the character before the cursor. │
456            │Return            Exits  the  widget  and returns 1.  This │
457            │                  also sets the widget  data  exitType  to │
458vNORMAL.                                 │
459            │Escape            Exits  the  widget and returns -1.  This │
460            │                  also sets the widget  data  exitType  to │
461vESCAPE_HIT.                             │
462            │Ctrl-L            Refreshes the screen.                    │
463            └───────────────────────────────────────────────────────────┘

SEE ALSO

465       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
466
467
468
469                                                                 cdk_matrix(3)
Impressum