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

NAME

6       cdk_mentry - curses multiple line entry widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       char *activateCDKMentry (
14                      CDKMENTRY *mentry,
15                      chtype *actions);
16
17       void cleanCDKMentry (
18                      CDKMENTRY *mentry);
19
20       void destroyCDKMentry (
21                      CDKMENTRY *mentry);
22
23       void drawCDKMentry (
24                      CDKMENTRY *mentry,
25                      boolean box);
26
27       void drawCDKMentryField (
28                      CDKMENTRY *mentry);
29
30       void eraseCDKMentry (
31                      CDKMENTRY *mentry);
32
33       boolean getCDKMentryBox (
34                      CDKMENTRY *mentry);
35
36       chtype getCDKMentryFillerChar (
37                      CDKMENTRY *mentry);
38
39       chtype getCDKMentryHiddenChar (
40                      CDKMENTRY *mentry);
41
42       int getCDKMentryMin (
43                      CDKMENTRY *mentry);
44
45       char *getCDKMentryValue (
46                      CDKMENTRY *mentry);
47
48       char *injectCDKMentry (
49                      CDKMENTRY *mentry,
50                      chtype input);
51
52       void moveCDKMentry (
53                      CDKMENTRY *mentry,
54                      int xpos,
55                      int ypos,
56                      boolean relative,
57                      boolean refresh);
58
59       CDKMENTRY *newCDKMentry (
60                      CDKSCREEN *cdkscreen,
61                      int xpos,
62                      int ypos,
63                      const char *title,
64                      const char *label,
65                      chtype fieldAttribute,
66                      chtype fillerCharacter,
67                      EDisplayType displayType,
68                      int fieldWidth,
69                      int fieldRows,
70                      int logicalRows,
71                      int minimumLength,
72                      boolean box,
73                      boolean shadow);
74
75       void positionCDKMentry (
76                      CDKMENTRY *mentry);
77
78       void setCDKMentry (
79                      CDKMENTRY *mentry,
80                      const char *value,
81                      int minimumLength,
82                      boolean box);
83
84       void setCDKMentryBackgroundAttrib (
85                      CDKMENTRY *mentry,
86                      chtype attribute);
87
88       void setCDKMentryBackgroundColor (
89                      CDKMENTRY *mentry,
90                      const char * color);
91
92       void setCDKMentryBox (
93                      CDKMENTRY *mentry,
94                      boolean boxWidget);
95
96       void setCDKMentryBoxAttribute (
97                      CDKMENTRY *mentry,
98                      chtype character);
99
100       void setCDKMentryCB (
101                      CDKMENTRY *mentry,
102                      MENTRYCB callBackFunction);
103
104       void setCDKMentryFillerChar (
105                      CDKMENTRY *mentry,
106                      chtype filler);
107
108       void setCDKMentryHiddenChar (
109                      CDKMENTRY *mentry,
110                      chtype character);
111
112       void setCDKMentryHorizontalChar (
113                      CDKMENTRY *mentry,
114                      chtype character);
115
116       void setCDKMentryLLChar (
117                      CDKMENTRY *mentry,
118                      chtype character);
119
120       void setCDKMentryLRChar (
121                      CDKMENTRY *mentry,
122                      chtype character);
123
124       void setCDKMentryMin (
125                      CDKMENTRY *mentry,
126                      int maximum);
127
128       void setCDKMentryPostProcess (
129                      CDKMENTRY *mentry,
130                      PROCESSFN callback,
131                      void * data);
132
133       void setCDKMentryPreProcess (
134                      CDKMENTRY *mentry,
135                      PROCESSFN callback,
136                      void * data);
137
138       void setCDKMentryULChar (
139                      CDKMENTRY *mentry,
140                      chtype character);
141
142       void setCDKMentryURChar (
143                      CDKMENTRY *mentry,
144                      chtype character);
145
146       void setCDKMentryValue (
147                      CDKMENTRY *mentry,
148                      const char *value);
149
150       void setCDKMentryVerticalChar (
151                      CDKMENTRY *mentry,
152                      chtype character);
153

DESCRIPTION

155       The  Cdk  mentry  widget creates a multiple line entry box with a label
156       and an entry field.  The following are functions which create or manip‐
157       ulate the Cdk mentry box widget.
158

AVAILABLE FUNCTIONS

160       activateCDKMentry
161            activates  the  mentry  widget and lets the user interact with the
162            widget.
163
164            ·   The parameter mentry is a pointer to a non-NULL mentry widget.
165
166            ·   If the actions parameter is passed with a non-NULL value,  the
167                characters in the array will be injected into the widget.
168
169                To  activate  the  widget interactively pass in a NULL pointer
170                for actions.
171
172            If the character entered into this widget is RETURN  or  TAB  then
173            this  function  will  return a char * representing the information
174            typed into the widget and the widget data exitType will be set  to
175            vNORMAL.
176
177            If  the character entered was ESCAPE then the function will return
178            NULL pointer and the widget data exitType is set to vESCAPE_HIT.
179
180       cleanCDKMentry
181            clears the information from the field.
182
183       destroyCDKMentry
184            removes the widget from the screen and  frees  memory  the  object
185            used.
186
187       drawCDKMentry
188            draws the widget on the screen.  If the box parameter is true, the
189            widget is drawn with a box.
190
191       drawCDKMentryField
192            redraws the multiple line entry field.
193
194       eraseCDKMentry
195            removes the widget from the screen.  This  does  NOT  destroy  the
196            widget.
197
198       getCDKMentryBox
199            returns true if the widget will be drawn with a box around it.
200
201       getCDKMentryFillerChar
202            returns  the character being used to draw unused space in the wid‐
203            get.
204
205       getCDKMentryHiddenChar
206            returns the character being used to draw hidden characters in  the
207            widget (obsolete).
208
209       getCDKMentryMin
210            returns the minimum length of a string the widget will allow.
211
212       getCDKMentryValue
213            returns the current value of the widget.
214
215       injectCDKMentry
216            injects a single character into the widget.
217
218            ·   The parameter mentry is a pointer to a non-NULL mentry.
219
220            ·   The  parameter  character  is the character to inject into the
221                widget.
222
223                The return value and  side-effect  (setting  the  widget  data
224                exitType) depend upon the injected character:
225
226                RETURN or TAB
227                       the function returns a char * representing the informa‐
228                       tion typed into the widget.  The widget  data  exitType
229                       is set to vNORMAL.
230
231                ESCAPE the  function  returns a NULL pointer.  The widget data
232                       exitType is set to vESCAPE_HIT.
233
234                Otherwise
235                       unless modified by preprocessing, postprocessing or key
236                       bindings, the function returns a NULL pointer.
237
238            ·   The widget data exitType is set to vEARLY_EXIT.
239
240       moveCDKMentry
241            moves the given widget to the given position.
242
243            ·   The  parameters xpos and ypos are the new position of the wid‐
244                get.
245
246                The parameter xpos may be an integer or one of the pre-defined
247                values TOP, BOTTOM, and CENTER.
248
249                The parameter ypos may be an integer or one of the pre-defined
250                values LEFT, RIGHT, and CENTER.
251
252            ·   The parameter relative states whether the xpos/ypos pair is  a
253                relative move or an absolute move.
254
255                For  example,  if  xpos  = 1 and ypos = 2 and relative = TRUE,
256                then the widget would move one row down and two columns right.
257
258                If the value of relative was FALSE, then the widget would move
259                to the position (1,2).
260
261                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
262                relative = TRUE.  (weird things may happen).
263
264            ·   The final parameter refresh is a boolean  value  which  states
265                whether the widget will get refreshed after the move.
266
267       newCDKMentry
268            creates a mentry widget and returns a pointer to it.  Parameters:
269
270            screen
271                 is the screen you wish this widget to be placed in.
272
273            xpos controls  the  placement  of  the object along the horizontal
274                 axis.  It may be an integer or one of the pre-defined  values
275                 LEFT, RIGHT, and CENTER.
276
277            ypos controls the placement of the object along the vertical axis.
278                 It may be an integer or one of the  pre-defined  values  TOP,
279                 BOTTOM, and CENTER.
280
281            title
282                 is  the string which will be displayed at the top of the wid‐
283                 get.  The title can be more than one  line;  just  provide  a
284                 carriage return character at the line break.
285
286            label
287                 is  the  string  which  will be displayed in the label of the
288                 mentry field.
289
290            fieldAttribute
291                 is the attribute of the characters to be displayed when  they
292                 are typed in.
293
294            filler
295                 is the character which is to display in an empty space in the
296                 mentry field.
297
298            displayType
299                 tells how the mentry field will behave when  a  character  is
300                 entered  into  the field.  The following table outlines valid
301                 values for this field and what they mean:
302
303                    Display_Type   Meaning
304                    ───────────────────────────────────────────────────
305                    vCHAR          Only accepts alphabetic characters.
306                    vLCHAR         Only accepts alphabetic characters.
307                                   Maps  the  character  to lower case
308                                   when a character has been accepted.
309                    vUCHAR         Only accepts alphabetic characters.
310                                   Maps  the  character  to upper case
311                                   when a character has been accepted.
312                    vHCHAR         Only accepts alphabetic characters.
313                                   Displays  a  . when a character has
314                                   been accepted.
315                    vUHCHAR        Only accepts alphabetic characters.
316                                   Displays a . and maps the character
317                                   to upper case when a character  has
318                                   been accepted.
319                    vLHCHAR        Only accepts alphabetic characters.
320                                   Displays a . and maps the character
321                                   to  lower case when a character has
322                                   been accepted.
323                    vINT           Only accepts numeric characters.
324                    vHINT          Only  accepts  numeric  characters.
325                                   Displays  a  . when a character has
326                                   been accepted.
327                    vMIXED         Accepts any character types.
328                    vLMIXED        Accepts any character types.   Maps
329                                   the character to lower case when an
330                                   alphabetic   character   has   been
331                                   accepted.
332                    vUMIXED        Accepts  any character types.  Maps
333                                   the character to upper case when an
334                                   alphabetic   character   has   been
335                                   accepted.
336
337
338
339                    vHMIXED        Accepts any character types.   Dis‐
340                                   plays a . when a character has been
341                                   accepted.
342                    vLHMIXED       Accepts any character types.   Dis‐
343                                   plays a . and maps the character to
344                                   lower case  when  a  character  has
345                                   been accepted.
346                    vUHMIXED       Accepts  any character types.  Dis‐
347                                   plays a . and maps the character to
348                                   upper  case  when  a  character has
349                                   been accepted.
350                    vVIEWONLY      Uneditable field.
351                    ───────────────────────────────────────────────────
352
353            fieldRows and
354
355            fieldWidth
356                 control the height and width of the field of the widget.   If
357                 you  provide  a  value  of zero for either of the values, the
358                 field in the widget will be made as large as it can  both  in
359                 width  and  in  height.  If you provide a negative value, the
360                 field will be created the full  height  or  width  minus  the
361                 value provided.
362
363            logicalRows
364                 is the number of rows for the mentry field.
365
366            minimumLength
367                 is  the number of characters which must be entered before the
368                 use can exit the mentry field.
369
370            callBackFunction
371                 allows the user to override the key processing element of the
372                 widget.
373
374            box  is true if widget should be drawn with a box around it.
375
376            shadow
377                 turns the shadow on or off around this widget.
378
379            If  the  widget  could  not  be  created  then  a  NULL pointer is
380            returned.
381
382       positionCDKMentry
383            allows the user to move the widget around the screen via the  cur‐
384            sor/keypad keys.  See cdk_position (3) for key bindings.
385
386       setCDKMentry
387            lets  the  programmer modify certain elements of an existing entry
388            widget.  The parameter names  correspond  to  the  same  parameter
389            names listed in the newCDKMentry function.
390
391       setCDKMentryBackgroundAttrib
392            sets  the  background  attribute  of  the  widget.   The parameter
393            attribute is a curses attribute, e.g., A_BOLD.
394
395       setCDKMentryBackgroundColor
396            sets the background color of the widget.  The parameter  color  is
397            in the format of the Cdk format strings.  See cdk_display (3).
398
399       setCDKMentryBox
400            sets whether the widget will be drawn with a box around it.
401
402       setCDKMentryBoxAttribute
403            function sets the attribute of the box.
404
405       setCDKMentryCB
406            function  allows  the  programmer  to set a different widget input
407            handler.  The parameter callbackFunction is of type MENTRYCB.  The
408            default function is CDKMentryCallBack.
409
410       setCDKMentryFillerChar
411            sets the character to use when drawing unused space in the field.
412
413       setCDKMentryHiddenChar
414            sets  the  character  to  use when a hidden character type is used
415            (obsolete).
416
417       setCDKMentryHorizontalChar
418            function sets the horizontal drawing character for the box to  the
419            given character.
420
421       setCDKMentryLLChar
422            function  sets  the  lower left hand corner of the widget's box to
423            the given character.
424
425       setCDKMentryLRChar
426            function sets the lower right hand corner of the widget's  box  to
427            the given character.
428
429       setCDKMentryMin
430            sets the minimum length of the string that the widget will allow.
431
432       setCDKMentryPostProcess
433            allows  the  user to have the widget call a function after the key
434            has been applied to the widget.
435
436            ·   The parameter function is the callback function.
437
438            ·   The parameter data points to data passed to the callback func‐
439                tion.
440
441            To learn more about post-processing see cdk_process (3).
442
443       setCDKMentryPreProcess
444            allows  the user to have the widget call a function after a key is
445            hit and before the key is applied to the widget.
446
447            ·   The parameter function is the callback function.
448
449            ·   The parameter data points to data passed to the callback func‐
450                tion.
451
452            To learn more about pre-processing see cdk_process (3).
453
454       setCDKMentryULChar
455            sets  the  upper left hand corner of the widget's box to the given
456            character.
457
458       setCDKMentryURChar
459            sets the upper right hand corner of the widget's box to the  given
460            character.
461
462       setCDKMentryValue
463            sets the current value of the widget.
464
465       setCDKMentryVerticalChar
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 the cursor to the left.                           │
479       │CTRL-B        Moves the cursor to the left.                           │
480       │Right Arrow   Moves the cursor to the right.                          │
481       │CTRL-F        Moves the cursor to the right.                          │
482       │Up Arrow      Moves the cursor one row down.                          │
483       │Down Arrow    Moves the cursor one row up.                            │
484       │Delete        Deletes the character at the cursor.                    │
485       │Backspace     Deletes the character before cursor, moves cursor left. │
486       │CTRL-V        Pastes  whatever  is in the paste buffer, into the wid‐ │
487       │              get.                                                    │
488       │CTRL-X        Cuts the contents from the widget and saves a  copy  in │
489       │              the paste buffer.                                       │
490       │CTRL-Y        Copies  the  contents of the widget into the paste buf‐ │
491       │              fer.                                                    │
492       │CTRL-U        Erases the contents of the widget.                      │
493       │CTRL-A        Moves the cursor to the beginning of the entry field.   │
494       │CTRL-E        Moves the cursor to the end of the entry field.         │
495       │CTRL-T        Transposes the character  under  the  cursor  with  the │
496       │              character to the right.                                 │
497       │Return        Exits  the widget and returns a char * representing the │
498       │              information which was typed into the  field.   It  also │
499       │              sets  the widget data exitType in the widget pointer to │
500vNORMAL.                                                │
501       │Tab           Exits the widget and returns a char * representing  the │
502       │              information  which  was  typed into the field.  It also │
503       │              sets the widget data exitType in the widget pointer  to │
504vNORMAL.                                                │
505       │Escape        Exits  the  widget and returns a NULL pointer.  It also │
506       │              sets the widget data exitType to vESCAPE_HIT.           │
507       │Ctrl-L        Refreshes the screen.                                   │
508       └──────────────────────────────────────────────────────────────────────┘

SEE ALSO

510       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
511
512
513
514                                                                 cdk_mentry(3)
Impressum