1cdk_matrix(3) Library Functions Manual cdk_matrix(3)
2
6 cdk_matrix - curses matrix widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKMatrix (
14 CDKMATRIX *matrix,
15 chtype * actions);
16 void cleanCDKMatrix (
18 CDKMATRIX *matrix);
19 void cleanCDKMatrixCell (
21 CDKMATRIX *matrix,
22 int row,
23 int col);
24 void destroyCDKMatrix (
26 CDKMATRIX *matrix);
27 void drawCDKMatrix (
29 CDKMATRIX *matrix,
30 boolean box);
31 void eraseCDKMatrix (
33 CDKMATRIX *matrix);
34 boolean getCDKMatrixBox (
36 CDKMENTRY *matrix);
37 char * getCDKMatrixCell (
39 CDKMATRIX *matrix,
40 int row,
41 int col);
42 int getCDKMatrixCol (
44 CDKMENTRY *matrix);
45 int getCDKMatrixRow (
47 CDKMENTRY *matrix);
48 int injectCDKMatrix (
50 CDKMATRIX *matrix,
51 chtype input);
52 int jumpToCell (
54 CDKMATRIX *matrix,
55 int row,
56 int col);
57 void moveCDKMatrix (
59 CDKMATRIX *matrix,
60 int xpos,
61 int ypos,
62 boolean relative,
63 boolean refresh);
64 int moveToCDKMatrixCell (
66 CDKMATRIX *matrix,
67 int row,
68 int col);
69 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 void positionCDKMatrix (
92 CDKMATRIX *matrix);
93 void setCDKMatrix (
95 CDKMATRIX *matrix,
96 char *info[MAX_MATRIX_ROWS][MAX_MATRIX_COLS],
97 int rows,
98 int *columnLengths);
99 void setCDKMatrixBackgroundAttrib (
101 CDKMATRIX *matrix,
102 chtype attribute);
103 void setCDKMatrixBackgroundColor (
105 CDKMATRIX *matrix,
106 const char * color);
107 void setCDKMatrixBox (
109 CDKMENTRY *matrix,
110 boolean boxWidget);
111 void setCDKMatrixBoxAttribute (
113 CDKMATRIX *matrix,
114 chtype character);
115 void setCDKMatrixCB (
117 CDKMATRIX *matrix,
118 MATRIXCB callbackFunction);
119 int setCDKMatrixCell (
121 CDKMATRIX *matrix,
122 int row,
123 int col,
124 const char *value);
125 void setCDKMatrixCells (
127 CDKMATRIX *matrix,
128 CDK_CONST char **info,
129 int rows,
130 int cols,
131 int *columnLengths);
132 void setCDKMatrixHorizontalChar (
134 CDKMATRIX *matrix,
135 chtype character);
136 void setCDKMatrixLLChar (
138 CDKMATRIX *matrix,
139 chtype character);
140 void setCDKMatrixLRChar (
142 CDKMATRIX *matrix,
143 chtype character);
144 void setCDKMatrixPostProcess (
146 CDKMATRIX *matrix,
147 PROCESSFN callback,
148 void * data);
149 void setCDKMatrixPreProcess (
151 CDKMATRIX *matrix,
152 PROCESSFN callback,
153 void * data);
154 void setCDKMatrixULChar (
156 CDKMATRIX *matrix,
157 chtype character);
158 void setCDKMatrixURChar (
160 CDKMATRIX *matrix,
161 chtype character);
162 void setCDKMatrixVerticalChar (
164 CDKMATRIX *matrix,
165 chtype character);
166
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
172 activateCDKMatrix
173 activates the matrix widget and lets the user interact with the
174 widget.
175 · The parameter matrix is a pointer to a non-NULL matrix widget.
177 · If the actions parameter is passed with a non-NULL value, the
179 characters in the array will be injected into the widget.
180 To activate the widget interactively pass in a NULL pointer
182 for actions.
183 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 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 · The matrix cell contents can be retrieved by using the info
193 array of the matrix widget.
194 cleanCDKMatrix
196 clears the information from all cells of the matrix.
197 cleanCDKMatrixCell
199 clears the information from the specified cell of the matrix.
200 destroyCDKMatrix
202 removes the widget from the screen and frees memory the object
203 used.
204 drawCDKMatrix
206 draws the matrix widget on the screen. If the box parameter is
207 true, the widget is drawn with a box.
208 eraseCDKMatrix
210 removes the widget from the screen. This does NOT destroy the
211 widget.
212 getCDKMatrixBox
214 returns true if the widget will be drawn with a box around it.
215 getCDKMatrixCell
217 returns the contents of the cell located by the row and col pair.
218 getCDKMatrixCol
220 returns the current column index.
221 getCDKMatrixRow
223 returns the current row index.
224 injectCDKMatrix
226 injects a single character into the widget.
227 · The parameter matrix is a pointer to a non-NULL matrix widget.
229 · The parameter character is the character to inject into the
231 widget.
232 The return value and side-effect (setting the widget data
234 exitType) depend upon the injected character:
235 RETURN or TAB
237 the function returns 1. The widget data exitType is
238 set to vNORMAL.
239 ESCAPE the function returns -1. The widget data exitType is
241 set to vESCAPE_HIT.
242 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 · The matrix cell contents can be retrieved by using the info
249 array of the matrix widget.
250 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 moveCDKMatrix
257 moves the given widget to the given position.
258 · The parameters xpos and ypos are the new position of the wid‐
260 get.
261 The parameter xpos may be an integer or one of the pre-defined
263 values TOP, BOTTOM, and CENTER.
264 The parameter ypos may be an integer or one of the pre-defined
266 values LEFT, RIGHT, and CENTER.
267 · The parameter relative states whether the xpos/ypos pair is a
269 relative move or an absolute move.
270 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 If the value of relative was FALSE, then the widget would move
275 to the position (1,2).
276 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
278 relative = TRUE. (weird things may happen).
279 · The final parameter refresh is a boolean value which states
281 whether the widget will get refreshed after the move.
282 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 newCDKMatrix
289 creates a matrix widget and returns a pointer to it. Parameters:
290 screen
292 is the screen you wish this widget to be placed in.
293 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 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 screenRows and
303 screenCols
305 are the number of rows and columns to be displayed on the
306 screen respectively.
307 actualRows and
309 actualCols
311 are the number of actual rows and columns the matrix has.
312 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 rowTitles and
319 colTitles
321 are the titles along the row and columns respectively.
322 columnWidths
324 is an array of integers stating how wide the individual col‐
325 umns are to be.
326 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 rowSpace and
334 colSpace
336 dictate how much white space is to be between rows and col‐
337 umns respectively.
338 filler
340 is the character to use in empty space within a cell.
341 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 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 boxMatrix
353 is true if the widget should be drawn with a box around it.
354 boxCell
356 is true if the individual cells should have boxes drawn
357 around them.
358 shadow
360 turns the shadow on or off around this widget.
361 If the widget could not be created then a NULL pointer is
363 returned.
364 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 setCDKMatrix
370 lets the programmer modify certain elements of an existing matrix
371 widget.
372 · The parameter info is an array of char * which contains the
374 cell information.
375 · The parameter rows has the number of rows
377 · the parameter info contains,
379 · columnLengths has the lengths of the individual columns in
381 info.
382 Do not use this function. It is obsolete, provided only for com‐
384 patibility with older versions of CDK. Use setCDKMatrixCells.
385 setCDKMatrixBackgroundAttrib
387 sets the background attribute of the widget. The parameter
388 attribute is a curses attribute, e.g., A_BOLD.
389 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 setCDKMatrixBox
395 sets whether the widget will be drawn with a box around it.
396 setCDKMatrixBoxAttribute
398 sets the attribute of the box.
399 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 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 setCDKMatrixCells,
410 lets the programmer initialize elements of an existing matrix wid‐
411 get.
412 · The parameter info is an array of char * which contains the cell
414 information.
415 · The parameter rows has the number of rows
417 · The parameter cols has the number of columns
419 · The parameter info contains, while columnLengths has the
421 lengths of the individual columns in info.
422 setCDKMatrixHorizontalChar
424 sets the horizontal drawing character for the box to the given
425 character.
426 setCDKMatrixLLChar
428 sets the lower left hand corner of the widget's box to the given
429 character.
430 setCDKMatrixLRChar
432 sets the lower right hand corner of the widget's box to the given
433 character.
434 setCDKMatrixPostProcess
436 allows the user to have the widget call a function after the key
437 has been applied to the widget.
438 · The parameter function is the callback function.
440 · The parameter data points to data passed to the callback func‐
442 tion.
443 To learn more about post-processing see cdk_process [4m(3).
445 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 · The parameter function is the callback function.
451 · The parameter data points to data passed to the callback func‐
453 tion.
454 To learn more about pre-processing see cdk_process [4m(3).
456 setCDKMatrixULChar
458 sets the upper left hand corner of the widget's box to the given
459 character.
460 setCDKMatrixURChar
462 sets the upper right hand corner of the widget's box to the given
463 character.
464 setCDKMatrixVerticalChar
466 sets the vertical drawing character for the box to the given char‐
467 acter.
468
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 ┌───────────────────────────────────────────────────────────┐
476 │Key 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 │
507 │ vNORMAL. │
508 │Escape Exits the widget and returns -1. This │
509 │ also sets the widget data exitType to │
510 │ vESCAPE_HIT. │
511 │Ctrl-L Refreshes the screen. │
512 └───────────────────────────────────────────────────────────┘
514 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
515 cdk_matrix(3)