1cdk_matrix(3) Library Functions Manual cdk_matrix(3)
2
3
4
6 cdk_matrix - curses matrix widget.
7
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
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
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 [4m(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 [4m(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
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 ┌───────────────────────────────────────────────────────────┐
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
516
517
518 cdk_matrix(3)