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

NAME

6       cdk_calendar - curses calendar widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       time_t activateCDKCalendar (CDKCALENDAR * calendar ,
14                      chtype *actions);
15
16       void destroyCDKCalendar (
17                      CDKCALENDAR *calendar);
18
19       void drawCDKCalendar (CDKCALENDAR * calendar ,
20                      boolean box);
21
22       void eraseCDKCalendar (
23                      CDKCALENDAR *calendar);
24
25       boolean getCDKCalendarBox (
26                      CDKCALENDAR *calendar);
27
28       void getCDKCalendarDate (CDKCALENDAR * calendar ,
29                      int *day,
30                      int *month,
31                      int *year);
32
33       chtype getCDKCalendarDayAttribute (
34                      CDKCALENDAR *calendar);
35
36       chtype getCDKCalendarHighlight (
37                      CDKCALENDAR *calendar);
38
39       chtype getCDKCalendarMarker (
40                      CDKCALENDAR *calendar,
41                      int day,
42                      int month,
43                      int year);
44
45       chtype getCDKCalendarMonthAttribute (
46                      CDKCALENDAR *calendar);
47
48       chtype getCDKCalendarYearAttribute (
49                      CDKCALENDAR *calendar);
50
51       time_t injectCDKCalendar (
52                      CDKCALENDAR *calendar,
53                      chtype input);
54
55       void moveCDKCalendar (
56                      CDKCALENDAR *calendar,
57                      int xpos,
58                      int ypos,
59                      boolean relative,
60                      boolean refresh);
61
62       CDKCALENDAR *newCDKCalendar (CDKSCREEN * cdkscreen ,
63                      int xpos,
64                      int ypos,
65                      const char *title,
66                      int day,
67                      int month,
68                      int year,
69                      chtype dayAttrib,
70                      chtype monthAttrib,
71                      chtype yearAttrib,
72                      chtype highlight,
73                      boolean box,
74                      boolean shadow);
75
76       void positionCDKCalendar (
77                      CDKCALENDAR *calendar);
78
79       void removeCDKCalendarMarker (
80                      CDKCALENDAR *calendar,
81                      int day,
82                      int month,
83                      int year);
84
85       void setCDKCalendar (
86                      CDKCALENDAR *calendar,
87                      int day,
88                      int month,
89                      int year,
90                      chtype dayAttrib,
91                      chtype monthAttrib,
92                      chtype yearAttrib,
93                      chtype highlight,
94                      boolean box);
95
96       void setCDKCalendarBackgroundAttrib (
97                      CDKCALENDAR *calendar,
98                      chtype attribute);
99
100       void setCDKCalendarBackgroundColor (
101                      CDKCALENDAR *calendar,
102                      const char * color);
103
104       void setCDKCalendarBox (
105                      CDKCALENDAR *calendar,
106                      boolean box);
107
108       setCDKCalendarBoxAttribute ("
109                      CDKCALENDAR *calendar,
110                      chtype ch);
111
112       void setCDKCalendarDate (
113                      CDKCALENDAR *calendar,
114                      int day,
115                      int month,
116                      int year);
117
118       void setCDKCalendarDayAttribute (
119                      CDKCALENDAR *calendar,
120                      chtype attribute);
121
122       void setCDKCalendarDaysNames (
123                      CDKCALENDAR *calendar,
124                      const char *days);
125
126       void setCDKCalendarHighlight (
127                      CDKCALENDAR *calendar,
128                      chtype attribute);
129
130       void setCDKCalendarHorizontalChar (
131                      CDKCALENDAR *calendar,
132                      chtype ch);
133
134       void setCDKCalendarLLChar (
135                      CDKCALENDAR *calendar,
136                      chtype ch);
137
138       void setCDKCalendarLRChar (
139                      CDKCALENDAR *calendar,
140                      chtype ch);
141
142       void setCDKCalendarMarker (
143                      CDKCALENDAR *calendar,
144                      int day,
145                      int month,
146                      int year,
147                      chtype marker);
148
149       void setCDKCalendarMonthAttribute (
150                      CDKCALENDAR *calendar,
151                      chtype attribute);
152
153       void setCDKCalendarMonthsNames (
154                      CDKCALENDAR *calendar,
155                      CDK_CONST char **months);
156
157       void setCDKCalendarPostProcess (
158                      CDKCALENDAR *calendar,
159                      PROCESSFN callback,
160                      void * data);
161
162       void setCDKCalendarPreProcess (
163                      CDKCALENDAR *calendar,
164                      PROCESSFN callback,
165                      void * data);
166
167       setCDKCalendarULChar ("
168                      CDKCALENDAR *calendar,
169                      chtype ch);
170
171       setCDKCalendarURChar ("
172                      CDKCALENDAR *calendar,
173                      chtype ch);
174
175       setCDKCalendarVerticalChar ("
176                      CDKCALENDAR *calendar,
177                      chtype ch);
178
179       void setCDKCalendarYearAttribute (
180                      CDKCALENDAR *calendar,
181                      chtype attribute);
182

DESCRIPTION

184       The Cdk calendar widget creates a pop-up calendar.  The calendar widget
185       allows the user to traverse through months/years using the cursor keys.
186

AVAILABLE FUNCTIONS

188       activateCDKCalendar
189            activates the calendar widget and lets the user interact with  the
190            widget.   The  calendar widget is a pointer to a non-NULL calendar
191            widget.  If the actions parameter is passed with a non-NULL value,
192            the  characters in the array will be injected into the widget.  To
193            activate the widget interactively  pass  in  a  NULL  pointer  for
194            actions.  If the character entered into this widget is RETURN then
195            this function will return a type of time_t.  The  time_t  type  is
196            used  in  the  functions  defined in the time.h header file.  (see
197            localtime or  ctime  for  more  information).   If  the  character
198            entered into this widget was ESCAPE or TAB then this function will
199            return a value of (time_t)-1 and the widget data exitType will  be
200            set to vESCAPE_HIT.
201
202       destroyCDKCalendar
203            removes  the  widget  from  the screen and frees memory the object
204            used.
205
206       drawCDKCalendar
207            draws the label widget on the screen.  If  the  box  parameter  is
208            true, the widget is drawn with a box.
209
210       eraseCDKCalendar
211            removes  the  widget  from  the screen.  This does NOT destroy the
212            widget.
213
214       getCDKCalendarBox
215            returns whether the widget will be drawn with a box around it.
216
217       getCDKCalendarDate
218            returns the current date the calendar is displaying.
219
220       getCDKCalendarDayAttribute
221            returns the attribute of the day attribute of the calendar.
222
223       getCDKCalendarHighlight
224            returns the attribute of the highlight bar of the  scrolling  list
225            portion of the widget.
226
227       getCDKCalendarMarker
228            returns the marker set on the calendar by setCDKCalendarMarker.
229
230       getCDKCalendarMonthAttribute
231            returns the attribute of the month attribute of the calendar.
232
233       getCDKCalendarYearAttribute
234            returns the attribute of the year attribute of the calendar.
235
236       injectCDKCalendar
237            injects  a single character into the widget.  The parameter calen‐
238            dar is a pointer to a non-NULL  calendar  widget.   The  parameter
239            character  is the character to inject into the widget.  The return
240            value and side-effect (setting the widget  data  exitType)  depend
241            upon the injected character:
242
243            RETURN or TAB
244                   the  function returns a value of type time_t (see localtime
245                   or ctime for more information).  The widget  data  exitType
246                   is set to vNORMAL.
247
248            ESCAPE the  function returns (time_t)-1.  The widget data exitType
249                   is set to vESCAPE_HIT.
250
251            Otherwise
252                   unless modified by  preprocessing,  postprocessing  or  key
253                   bindings, the function returns (time_t)-1.  The widget data
254                   exitType is set to vEARLY_EXIT.
255
256       moveCDKCalendar
257            moves the given widget to the given position.  The parameters xpos
258            and  ypos  are the new position of the widget.  The parameter xpos
259            may be an integer or one of the pre-defined  values  TOP,  BOTTOM,
260            and  CENTER.   The  parameter ypos may be an integer or one of the
261            pre-defined values LEFT, RIGHT, and CENTER.  The  parameter  rela‐
262            tive  states  whether  the xpos/ypos pair is a relative move or an
263            absolute move.  For example, if xpos = 1 and ypos = 2 and relative
264            =  TRUE,  then  the widget would move one row down and two columns
265            right.  If the value of relative was FALSE then the  widget  would
266            move  to  the  position (1,2).  Do not use the values TOP, BOTTOM,
267            LEFT, RIGHT, or CENTER when relative = TRUE.   (weird  things  may
268            happen).   The  final  parameter  refresh is a boolean value which
269            states whether the widget will get refreshed after the move.
270
271       newCDKCalendar
272            creates a calendar widget and returns a pointer  to  it.   Parame‐
273            ters:
274
275            screen
276                 is the screen you wish this widget to be placed in.
277
278            xpos controls  the  placement  of  the object along the horizontal
279                 axis.  It may be an integer or one of the pre-defined  values
280                 LEFT, RIGHT, and CENTER.
281
282            ypos controls the placement of the object along the vertical axis.
283                 It may be an integer or one of the  pre-defined  values  TOP,
284                 BOTTOM, and CENTER.
285
286            title
287                 is  the string which will be displayed at the top of the wid‐
288                 get.  The title can be more than one  line;  just  provide  a
289                 carriage return character at the line break.
290
291            year,
292
293            month and
294
295            day
296                 set the initial date of the calendar.
297
298            yearAttrib,
299
300            monthAttrib and
301
302            dayAttrib
303                 represent  the attributes of the year, month, and day respec‐
304                 tively.
305
306            highlight
307                 sets the highlight of the currently selected day.
308
309            box  is true if the widget should be drawn with a box around it.
310
311            shadow
312                 turns the shadow on or off around this widget.
313
314            If the widget  could  not  be  created  then  a  NULL  pointer  is
315            returned.
316
317       positionCDKCalendar
318            allows  the user to move the widget around the screen via the cur‐
319            sor/keypad keys.  See cdk_position (3) for key bindings.
320
321       removeCDKCalendarMarker
322            removes a marker from the calendar.
323
324       setCDKCalendar
325            lets the programmer modify certain elements of an existing  calen‐
326            dar  widget.  The calendar parameter represents an existing calen‐
327            dar pointer.  The other parameter names  correspond  to  the  same
328            parameter names listed in the newCDKCalendar function.
329
330       setCDKCalendarBackgroundAttrib
331            sets  the  background  attribute  of  the  widget.   The parameter
332            attribute is a curses attribute, e.g., A_BOLD.
333
334       setCDKCalendarBackgroundColor
335            sets the background color of the widget.  The parameter  color  is
336            in the format of the Cdk format strings.  See cdk_display (3).
337
338       setCDKCalendarBox
339            sets whether the widget will be drawn with a box around it.
340
341       setCDKCalendarBoxAttribute
342            sets the attribute of the box.
343
344       setCDKCalendarDate
345            sets  the  calendar  to  the given date.  If the value of the day,
346            month, or year parameters is -1 then the current  day,  month,  or
347            year is used to set the date.
348
349       setCDKCalendarDayAttribute
350            sets the attribute of the day in the calendar.
351
352       setCDKCalendarDaysNames
353            sets the names of the days of the week.  The parameter is a string
354            listing the 2-character abbreviations for the days.   The  default
355            value is
356            "Su Mo Tu We Th Fr Sa"
357
358            "Su"  (Sunday)  is  numbered zero internally, making it by default
359            the first day of the week.  Set the weekBase member of the  widget
360            to  select a different day.  For example, Monday would be 1, Tues‐
361            day 2, etc.
362
363       setCDKCalendarHighlight
364            sets the attribute of the highlight bar of the scrolling list por‐
365            tion of the widget.
366
367       setCDKCalendarHorizontalChar
368            sets  the  horizontal  drawing  character for the box to the given
369            character.
370
371       setCDKCalendarLLChar
372            sets the lower left hand corner of the widget's box to  the  given
373            character.
374
375       setCDKCalendarLRChar
376            sets  the lower right hand corner of the widget's box to the given
377            character.
378
379       setCDKCalendarMarker
380            allows the user to set a marker which will be displayed  when  the
381            month is drawn.  The marker parameter is the attribute to use when
382            drawing the marker.  If more than one marker is set  on  a  single
383            day, then the day will blink with the original marker attribute.
384
385       setCDKCalendarMonthAttribute
386            sets the attribute of the month in the calendar.
387
388       setCDKCalendarMonthsNames
389            sets  the  names  of  the  months of the year.  The parameter is a
390            13-element array (since indexing starts with 1).  The default val‐
391            ues are the English month names, e.g., "January".
392
393       setCDKCalendarPostProcess
394            allows  the  user to have the widget call a function after the key
395            has been applied to the widget.  The  parameter  function  is  the
396            callback  function.   The  parameter data points to data passed to
397            the callback function.  To learn more  about  post-processing  see
398            cdk_process (3).
399
400       setCDKCalendarPreProcess
401            allows  the user to have the widget call a function after a key is
402            hit and before the key is applied to the  widget.   The  parameter
403            function  is  the callback function.  The parameter data points to
404            data passed to the callback function.  To learn  more  about  pre-
405            processing see cdk_process (3).
406
407       setCDKCalendarULChar
408            sets  the  upper left hand corner of the widget's box to the given
409            character.
410
411       setCDKCalendarURChar
412            sets the upper right hand corner of the widget's box to the  given
413            character.
414
415       setCDKCalendarVerticalChar
416            sets the vertical drawing character for the box to the given char‐
417            acter.
418
419       setCDKCalendarYearAttribute
420            sets the attribute of the year in the calendar.
421

KEY BINDINGS

423       When the widget is activated there are  several  default  key  bindings
424       which  will  help the user enter or manipulate the information quickly.
425       The following table outlines the keys and their actions for  this  wid‐
426       get.
427
428             ┌────────────────┬─────────────────────────────────────────┐
429Key             Action                                  
430             ├────────────────┼─────────────────────────────────────────┤
431             ├────────────────┼─────────────────────────────────────────┤
432             │Left Arrow      │ Moves the cursor to the previous day.   │
433             ├────────────────┼─────────────────────────────────────────┤
434             │Right Arrow     │ Moves the cursor to the next day.       │
435             ├────────────────┼─────────────────────────────────────────┤
436             │Up Arrow        │ Moves the cursor to the next week.      │
437             ├────────────────┼─────────────────────────────────────────┤
438             │Down Arrow      │ Moves the cursor to the previous week.  │
439             ├────────────────┼─────────────────────────────────────────┤
440             │t               │ Sets the calendar to the current date.  │
441             ├────────────────┼─────────────────────────────────────────┤
442             │T               │ Sets the calendar to the current date.  │
443             ├────────────────┼─────────────────────────────────────────┤
444             │n               │ Advances the calendar one month ahead.  │
445             ├────────────────┼─────────────────────────────────────────┤
446             │N               │ Advances the calendar six months ahead. │
447             ├────────────────┼─────────────────────────────────────────┤
448             │p               │ Advances the calendar one month back.   │
449             ├────────────────┼─────────────────────────────────────────┤
450             │P               │ Advances the calendar six months back.  │
451             ├────────────────┼─────────────────────────────────────────┤
452             │-               │ Advances the calendar one year ahead.   │
453             ├────────────────┼─────────────────────────────────────────┤
454             │+               │ Advances the calendar one year back.    │
455             ├────────────────┼─────────────────────────────────────────┤
456             │Return          │ Exits the widget and returns a value of │
457             │                │ time_t   which   represents   the   day │
458             │                │ selected  at  1  second after midnight. │
459             │                │ This also sets the widget data exitType
460             │                │ to vNORMAL.                             │
461             ├────────────────┼─────────────────────────────────────────┤
462             │Tab             │ Exits the widget and returns a value of │
463             │                │ time_t   which   represents   the   day │
464             │                │ selected  at  1  second after midnight. │
465             │                │ This also sets the widget data exitType
466             │                │ to vNORMAL.                             │
467             ├────────────────┼─────────────────────────────────────────┤
468             │Escape          │ Exits the widget and returns (time_)-1. │
469             │                │ This also sets the widget data exitType
470             │                │ to vESCAPE_HIT.                         │
471             ├────────────────┼─────────────────────────────────────────┤
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_calendar(3)
Impressum