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 char *title,
79 char **rowTitles,
80 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 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 char *value);
125 void setCDKMatrixCells (
126 CDKMATRIX *matrix,
127 char **info,
128 int rows,
129 int cols,
130 int *columnLengths);
131 void setCDKMatrixHorizontalChar (
133 CDKMATRIX *matrix,
134 chtype character);
135 void setCDKMatrixLLChar (
137 CDKMATRIX *matrix,
138 chtype character);
139 void setCDKMatrixLRChar (
141 CDKMATRIX *matrix,
142 chtype character);
143 void setCDKMatrixPostProcess (
145 CDKMATRIX *matrix,
146 PROCESSFN callback,
147 void * data);
148 void setCDKMatrixPreProcess (
150 CDKMATRIX *matrix,
151 PROCESSFN callback,
152 void * data);
153 void setCDKMatrixULChar (
155 CDKMATRIX *matrix,
156 chtype character);
157 void setCDKMatrixURChar (
159 CDKMATRIX *matrix,
160 chtype character);
161 void setCDKMatrixVerticalChar (
163 CDKMATRIX *matrix,
164 chtype character);
165
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
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 cleanCDKMatrix
186 clears the information from all cells of the matrix.
187 cleanCDKMatrixCell
189 clears the information from the specified cell of the matrix.
190 destroyCDKMatrix
192 removes the widget from the screen and frees memory the object
193 used.
194 drawCDKMatrix
196 draws the matrix widget on the screen. If the box parameter is
197 true, the widget is drawn with a box.
198 eraseCDKMatrix
200 removes the widget from the screen. This does NOT destroy the
201 widget.
202 getCDKMatrixBox
204 returns true if the widget will be drawn with a box around it.
205 getCDKMatrixCell
207 returns the contents of the cell located by the row and col pair.
208 getCDKMatrixCol
210 returns the current column index.
211 getCDKMatrixRow
213 returns the current row index.
214 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 RETURN or TAB
223 the function returns 1. The widget data exitType is set to
224 vNORMAL.
225 ESCAPE the function returns -1. The widget data exitType is set
227 to vESCAPE_HIT.
228 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 The matrix cell contents can be retrieved by using the info array
235 of the matrix widget.
236 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 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 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 newCDKMatrix
263 creates a matrix widget and returns a pointer to it. Parameters:
264 screen
266 is the screen you wish this widget to be placed in.
267 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 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 screenRows and
277 screenCols
279 are the number of rows and columns to be displayed on the
280 screen respectively.
281 actualRows and
283 actualCols
285 are the number of actual rows and columns the matrix has.
286 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 rowTitles and
293 colTitles
295 are the titles along the row and columns respectively.
296 columnWidths
298 is an array of integers stating how wide the individual col‐
299 umns are to be.
300 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 rowSpace and
308 colSpace
310 dictate how much white space is to be between rows and col‐
311 umns respectively.
312 filler
314 is the character to use in empty space within a cell.
315 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 boxMatrix
325 is true if the widget should be drawn with a box around it.
326 boxCell
328 is true if the individual cells should have boxes drawn
329 around them.
330 shadow
332 turns the shadow on or off around this widget.
333 If the widget could not be created then a NULL pointer is
335 returned.
336 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 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 Do not use this function. It is obsolete, provided only for com‐
349 patibility with older versions of CDK. Use setCDKMatrixCells.
350 setCDKMatrixBackgroundAttrib
352 sets the background attribute of the widget. The parameter
353 attribute is a curses attribute, e.g., A_BOLD.
354 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 setCDKMatrixBox
360 sets whether the widget will be drawn with a box around it.
361 setCDKMatrixBoxAttribute
363 sets the attribute of the box.
364 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 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 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 setCDKMatrixHorizontalChar
383 sets the horizontal drawing character for the box to the given
384 character.
385 setCDKMatrixLLChar
387 sets the lower left hand corner of the widget's box to the given
388 character.
389 setCDKMatrixLRChar
391 sets the lower right hand corner of the widget's box to the given
392 character.
393 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 [4m(3).
400 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 [4m(3).
407 setCDKMatrixULChar
409 sets the upper left hand corner of the widget's box to the given
410 character.
411 setCDKMatrixURChar
413 sets the upper right hand corner of the widget's box to the given
414 character.
415 setCDKMatrixVerticalChar
417 sets the vertical drawing character for the box to the given char‐
418 acter.
419
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 ┌───────────────────────────────────────────────────────────┐
427 │Key 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 │
458 │ vNORMAL. │
459 │Escape Exits the widget and returns -1. This │
460 │ also sets the widget data exitType to │
461 │ vESCAPE_HIT. │
462 │Ctrl-L Refreshes the screen. │
463 └───────────────────────────────────────────────────────────┘
465 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
466 cdk_matrix(3)