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

KEY BINDINGS

435       When the widget is activated there are  several  default  key  bindings
436       which  will  help the user enter or manipulate the information quickly.
437       The following table outlines the keys and their actions for  this  wid‐
438       get.
439
440       ┌──────────────────────────────────────────────────────────────────────┐
441Key           Action                                                  
442       ├──────────────────────────────────────────────────────────────────────┤
443       │Left Arrow    Moves the cursor to the left.                           │
444       │CTRL-B        Moves the cursor to the left.                           │
445       │Right Arrow   Moves the cursor to the right.                          │
446       │CTRL-F        Moves the cursor to the right.                          │
447       │Up Arrow      Moves the cursor one row down.                          │
448       │Down Arrow    Moves the cursor one row up.                            │
449       │Delete        Deletes the character at the cursor.                    │
450       │Backspace     Deletes the character before cursor, moves cursor left. │
451       │CTRL-V        Pastes  whatever  is in the paste buffer, into the wid‐ │
452       │              get.                                                    │
453       │CTRL-X        Cuts the contents from the widget and saves a  copy  in │
454       │              the paste buffer.                                       │
455       │CTRL-Y        Copies  the  contents of the widget into the paste buf‐ │
456       │              fer.                                                    │
457       │CTRL-U        Erases the contents of the widget.                      │
458       │CTRL-A        Moves the cursor to the beginning of the entry field.   │
459       │CTRL-E        Moves the cursor to the end of the entry field.         │
460       │CTRL-T        Transposes the character  under  the  cursor  with  the │
461       │              character to the right.                                 │
462       │Return        Exits  the widget and returns a char * representing the │
463       │              information which was typed into the  field.   It  also │
464       │              sets  the widget data exitType in the widget pointer to │
465vNORMAL.                                                │
466       │Tab           Exits the widget and returns a char * representing  the │
467       │              information  which  was  typed into the field.  It also │
468       │              sets the widget data exitType in the widget pointer  to │
469vNORMAL.                                                │
470       │Escape        Exits  the  widget and returns a NULL pointer.  It also │
471       │              sets the widget data exitType to vESCAPE_HIT.           │
472       │Ctrl-L        Refreshes the screen.                                   │
473       └──────────────────────────────────────────────────────────────────────┘

SEE ALSO

475       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
476
477
478
479                                                                 cdk_mentry(3)
Impressum