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
126       void setCDKMatrixCells (
127                      CDKMATRIX *matrix,
128                      CDK_CONST char **info,
129                      int rows,
130                      int cols,
131                      int *columnLengths);
132
133       void setCDKMatrixHorizontalChar (
134                      CDKMATRIX *matrix,
135                      chtype character);
136
137       void setCDKMatrixLLChar (
138                      CDKMATRIX *matrix,
139                      chtype character);
140
141       void setCDKMatrixLRChar (
142                      CDKMATRIX *matrix,
143                      chtype character);
144
145       void setCDKMatrixPostProcess (
146                      CDKMATRIX *matrix,
147                      PROCESSFN callback,
148                      void * data);
149
150       void setCDKMatrixPreProcess (
151                      CDKMATRIX *matrix,
152                      PROCESSFN callback,
153                      void * data);
154
155       void setCDKMatrixULChar (
156                      CDKMATRIX *matrix,
157                      chtype character);
158
159       void setCDKMatrixURChar (
160                      CDKMATRIX *matrix,
161                      chtype character);
162
163       void setCDKMatrixVerticalChar (
164                      CDKMATRIX *matrix,
165                      chtype character);
166

DESCRIPTION

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

AVAILABLE FUNCTIONS

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

KEY BINDINGS

470       When the widget is activated there are  several  default  key  bindings
471       which  will  help the user enter or manipulate the information quickly.
472       The following table outlines the keys and their actions for  this  wid‐
473       get.
474
475            ┌───────────────────────────────────────────────────────────┐
476Key               Action                                   
477            ├───────────────────────────────────────────────────────────┤
478            │Left Arrow        Moves one cell to the left.              │
479            │Right Arrow       Moves the cell to the right.             │
480            │Tab               Moves the cell to the right.             │
481            │Up Arrow          Moves one cell up.                       │
482            │Down Arrow        Moves one cell down.                     │
483            │Next Page         Moves one page forward.                  │
484            │Ctrl-F            Moves one page forward.                  │
485            │Prev Page         Moves one page backward.                 │
486            │Ctrl-B            Moves one page backward.                 │
487            │Ctrl-G            Calls   the   function   jumpToCell  and │
488            │                  requests which cell the user  wishes  to │
489            │                  jump to.                                 │
490            │Ctrl-P            Pastes  whatever is in the paste buffer, │
491            │                  into the current cell.                   │
492            │Ctrl-K            Cuts the contents from the current  cell │
493            │                  and saves a copy in the paste buffer.    │
494            │Ctrl-T            Copies  the contents of the current cell │
495            │                  into the paste buffer.                   │
496            │Ctrl-E            Erases the contents of the current cell. │
497            │Delete            Deletes the character before the cursor, │
498            │                  moves cursor left.  There is no function │
499            │                  to delete the character  at  the  cursor │
500            │                  since  there are no functions for moving │
501            │                  the cursor within the edited text.       │
502            │Backspace         Deletes  the  character  before  cursor, │
503            │                  moves cursor left.                       │
504            │Ctrl-H            Deletes the character before the cursor. │
505            │Return            Exits  the  widget  and returns 1.  This │
506            │                  also sets the widget  data  exitType  to │
507vNORMAL.                                 │
508            │Escape            Exits  the  widget and returns -1.  This │
509            │                  also sets the widget  data  exitType  to │
510vESCAPE_HIT.                             │
511            │Ctrl-L            Refreshes the screen.                    │
512            └───────────────────────────────────────────────────────────┘

SEE ALSO

514       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
515
516
517
518                                                                 cdk_matrix(3)
Impressum