home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 2 / 2302 / Calendar.doc next >
Encoding:
Text File  |  1990-12-28  |  13.9 KB  |  421 lines
  1. .NH 1
  2. Calendar Widget
  3. .XS
  4.     Calendar Widget
  5. .XE
  6. .Ds 0
  7. .TA 2.0i
  8. .ta 2.0i
  9. .sp
  10. Application Header file    "Calendar.h"
  11. Class Header file    "CalendarP.h"
  12. Class        CalendarWidgetClass
  13. Class Name    Calendar
  14. Superclass    Core
  15. .sp
  16. .De
  17. .LP
  18. The Calendar Widget is a widget that displays a one month calendar for a
  19. specified date.  It is designed to be used in applications that need to be
  20. driven by calendar input, as well as applications that simply want to display
  21. calendars.
  22. .NH 2
  23. Resources
  24. .LP
  25. When creating a Calendar widget instance, the following resources are
  26. retrieved from the argument list or from the resource database:
  27. .LP
  28. .ps 9
  29. .nr PS 9
  30. .vs 11
  31. .nr VS 11
  32. .TS H
  33. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  34. _
  35. .sp 3p
  36. .TB
  37. Name    Class    Type    Notes    Default Value
  38. .sp 3p
  39. _
  40. .TH
  41. .R
  42. .sp 3p
  43. background    Background    Pixel        XtDefaultBackground
  44. backgroundPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  45. borderWidth    BorderWidth    Dimension        1
  46. callback    CallbackList    XtCallbackList        NULL
  47. digitFont    CalendarFont    XFontStruct        fixed
  48. digitGravity    DigitGravity    Gravity        Center
  49. digitNames    DigitNames    StringTable        XtDefaultDigitNames
  50. foreground    Foreground    Pixel        XtDefaultForegrond
  51. height    Height    Dimension        Minimum height needed
  52. highlight    Highlight    Boolean        True
  53. lineWidth    LineWidth    int        1
  54. mappedWhenManaged    MappedWhenManaged    Boolean        True
  55. monthNames    MonthNames    StringTable        XtDefaultMonthNames
  56. showYear    ShowYear    Boolean        True
  57. startingWeekday    StartingWeekday    DayName        Sunday
  58. titleFont    CalendarFont    XFontStruct        fixed
  59. translations    Translations    TranslationTable        See below
  60. weekdayFont    CalendarFont    XFontStruct        fixed
  61. weekdayNames    WeekdayNames    StringTable        XtDefaultWeekdayNames
  62. width    Width    Dimension        Minimum width needed
  63. x    X    Position        0
  64. y    Y    Position        0
  65. .sp 3p
  66. _
  67. .TE
  68. .ps 11
  69. .nr PS 11
  70. .vs 13
  71. .nr VS 13
  72. .Bg
  73. .Gp
  74. .Bw
  75. .Cb
  76. .IP \fBdigitFont\fP 1.5i
  77. The font to be used for drawing the digit text in the calendar.
  78. .IP \fBdigitGravity\fP 1.5i
  79. Specifies the gravity used to determine where the digits that are drawn in
  80. the calendar cells will be located within the cells.  
  81. .Rs "NorthWest, North, NorthEast, West, Center, East, SouthWest, South, \
  82. \fPand\fP SouthEast".
  83. .IP \fBdigitNames\fP 1.5i
  84. The text to be used for the digits in the calendar cells, specified as a
  85. StringTable.
  86. .Fg
  87. .Hw
  88. .IP \fBhighlight\fP 1.5i
  89. If this is \fBFalse\fP then the calendar will never highlight any dates.
  90. .IP \fBlineWidth\fP 1.5i
  91. Determines the number of pixels wide the lines composing the grid in the
  92. calendar should be.  Acceptable values are 1 through 10 inclusive.
  93. .Mm
  94. .IP \fBmonthNames\fP 1.5i
  95. The text to be used for the month names that appear in the title above the
  96. calendar, specified as a StringTable.
  97. .IP \fBshowYear\fP 1.5i
  98. If this is \fBFalse\fP then the year number will not appear in the title of
  99. the calendar.
  100. .IP \fBstartingWeekday\fP 1.5i
  101. The day of the week that will correspond to the days in the left-most column
  102. of the calendar.
  103. .Rs "Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, \fPand\fP Saturday".
  104. .IP \fBtitleFont\fP 1.5i
  105. The font to be used for drawing the month and year text above the calendar
  106. grid.
  107. .IP \fBweekdayFont\fP 1.5i
  108. The font to be used for drawing the weekday names above each column of
  109. calendar cells in the calendar grid.
  110. .IP \fBweekdayNames\fP 1.5i
  111. The text to be used for the weekday names, specified as a StringTable.
  112. .Tr
  113. .Xy
  114. .NH 2
  115. Resource Defaults
  116. .LP
  117. Following are the default string tables used by the calendar widget when
  118. drawing all of its text:
  119. .IP \fBXtDefaultDayNames\fP  0.5i
  120. "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
  121. .IP \fBXtDefaultMonthNames\fP 0.5i
  122. "January", "February", "March", "April", "May", "June"
  123. "July", "August", "September", "October", "November",
  124. "December"
  125. .IP \fBXtDefaultDigitNames\fP 0.5i
  126. "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", 
  127. "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", 
  128. "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"
  129. .NH 2
  130. Defined Types and Converters
  131. .IP \fBDate\fP 1.0i
  132. Typedef of a structure with a numeric month, day, and year field.  The
  133. \fBDateConverter\fP public function is included with this widget.  This is not
  134. a normal resource converter and is described below under Convenience Routines.
  135. .IP \fBGravity\fP 1.0i
  136. Typedef of an enumerated type.  This may have one of the following values:
  137. \fBNorthWest, North, NorthEast, West, Center, East, SouthWest, South, \fPand
  138. \fBSouthEast\fP.  The \fBGravityConverter\fP resource converter is
  139. automatically included with this widget:
  140. .FD 0
  141. void GravityConverter(\fIargs\fP, \fInum_args\fP, \fIfromVal\fP, \fItoVal\fP)
  142. .br
  143.       XrmValuePtr \fIargs\fP;
  144.       Cardinal * \fInum_args\fP;
  145.       XrmValuePtr \fIfromVal\fP;
  146.       XrmValuePtr \fItoVal\fP;
  147. .FN
  148. .IP \fIargs\fP 1i
  149. This argument is ignored, but should be specified as NULL.
  150. .IP \fInum_args\fP 1i
  151. This argument is ignored, but should be specified as NULL.
  152. .IP \fIfromVal\fP 1i
  153. A pointer to the XrmValue structure that has been filled with a pointer to
  154. the string to be converted.
  155. .IP \fItoVal\fP 1i
  156. A pointer to the XrmValue structure that will be filled with a pointer to
  157. the corresponding Gravity.
  158. .LP
  159. .IP \fBStringTable\fP 1.0i
  160. A NULL terminated array of string pointers.  \fBThe StringTableConverter\fP
  161. resource converter is automatically included with this widget:
  162. .FD 0
  163. void StringTableConverter(\fIargs\fP, \fInum_args\fP, \fIfromVal\fP, \fItoVal\fP)
  164. .br
  165.       XrmValuePtr \fIargs\fP;
  166.       Cardinal * \fInum_args\fP;
  167.       XrmValuePtr \fIfromVal\fP;
  168.       XrmValuePtr \fItoVal\fP;
  169. .FN
  170. .IP \fIargs\fP 1i
  171. This argument is ignored, but should be specified as NULL.
  172. .IP \fInum_args\fP 1i
  173. This argument is ignored, but should be specified as NULL.
  174. .IP \fIfromVal\fP 1i
  175. A pointer to the XrmValue structure that has been filled with a pointer to
  176. the string to be converted.
  177. .IP \fItoVal\fP 1i
  178. A pointer to the XrmValue structure that will be filled with a pointer to
  179. the resulting StringTable.
  180. .LP
  181. The string to be converted must be specified as a comma separated list of 
  182. double quoted sub-strings.
  183. .LP
  184. .IP \fBDayName\fP 1i
  185. Typedef of an enumerated type.  This may have one of the following values:
  186. \fBSunday, Monday, Tuesday, Wednesday, Thursday, Friday, \fPand
  187. \fBSaturday\fP.  The \fBDayNameConverter\fP resource converter is
  188. automatically included with this widget:
  189. .FD 0
  190. void DayNameConverter (\fIargs\fP, \fInum_args\fP, \fIfromVal\fP, \fItoVal\fP)
  191. .br
  192.       XrmValuePtr \fIargs\fP;
  193.       Cardinal * \fInum_args\fP;
  194.       XrmValuePtr \fIfromVal\fP;
  195.       XrmValuePtr \fItoVal\fP;
  196. .FN
  197. .IP \fIargs\fP 1i
  198. This argument is ignored, but should be specified as NULL.
  199. .IP \fInum_args\fP 1i
  200. This argument is ignored, but should be specified as NULL.
  201. .IP \fIfromVal\fP 1i
  202. A pointer to the XrmValue structure that has been filled with a pointer to
  203. the string to be converted.
  204. .IP \fItoVal\fP 1i
  205. A pointer to the XrmValue structure that will be filled with a pointer to
  206. the corresponding DayName.
  207. .NH 2
  208. Calendar Actions
  209. .LP
  210. The Calendar widget supports the following actions:
  211. .IP \(bu 5
  212. Unhighlight the previously highlighted calendar cell and highlight the
  213. calendar cell currently beneath the pointer with \fBselect\fP.
  214. .IP \(bu 5
  215. Process calendar selection callbacks with \fBnotify\fP.
  216. .sp
  217. .LP
  218. The following are the default translation bindings used by the Calendar
  219. widget:
  220. .LP
  221. .sp
  222. .Ds 0
  223. .TA .5i 2.25i
  224. .ta .5i 2.25i
  225.     <Btn1Down>:    select()
  226.     <Btn1Motion>:    select()
  227.     <Btn1Up>:    notify()
  228. .De
  229. .sp
  230. .LP
  231. .NH 2
  232. Convenience Routines
  233. .LP
  234. For convenience and speed reasons, all of the date related resources of the
  235. calendar widget are only accesible via public functions.
  236. .LP
  237. In order to use the convenience routines effectively, it is important to
  238. understand that a calendar widget has two \fIunrelated\fP resources of type
  239. \fBDate\fP:
  240. .IP \fBmonth\fP 1i
  241. The date specified for this resource determines what month the calendar widget
  242. is to display.  A month and year are required to specify a unique \fBmonth\fP.
  243. .IP \fBdate\fP 1i
  244. The date specified for this resource determines what specific day the calendar
  245. widget is to highlight.  A month, day, and year are required to specify a
  246. unique \fBdate\fP.
  247. .NH 3
  248. Setting the Calendar Widget's month
  249. .LP
  250. The \fBmonth\fP for the calendar widget to display can be set by calling:
  251. .FD 0
  252. void CalendarShowMonth(\fIwidget\fP, \fIdate\fP)
  253. .br
  254.       CalendarWidget \fIwidget\fP;
  255.       Date \fIdigit\fP;
  256. .FN
  257. .IP \fIwidget\fP 1i
  258. Specifies the calendar widget.
  259. .IP \fIdate\fP 1i
  260. Specifies the new date whose month and year fields will determine the new
  261. \fBmonth\fP for the calendar to display.
  262. .LP
  263. Calling this function will change the \fBmonth\fP that is currently being
  264. displayed on the specified calendar widget, if it differs from the \fBmonth\fP
  265. that the calendar widget is currently displaying.  The day field is ignored
  266. and may be zero.  If the specified \fBmonth\fP corresponds to the \fBdate\fP
  267. specified by the last call to \fBCalendarSetDate\fP, and the \fBhighlight\fP
  268. resource is \fBTrue\fP, then that specified \fBdate\fP will appear
  269. highlighted.
  270. .NH 3
  271. Setting the Calendar Widget's date
  272. .LP
  273. To set the \fBdate\fP for the calendar widget to highlight use the following
  274. function:
  275. .FD 0
  276. void CalendarSetDate(\fIwidget\fP, \fIdate\fP)
  277. .br
  278.       CalendarWidget \fIwidget\fP;
  279.       Date \fIdate\fP;
  280. .FN
  281. .IP \fIwidget\fP 1i
  282. Specifies the calendar widget.
  283. .IP \fIdate\fP 1i
  284. Specifies the new date for the calendar to highlight.
  285. .LP
  286. The specified \fBdate\fP will appear highlighted on the specified calendar
  287. widget whenever the widget has been told to display the corresponding
  288. \fBmonth\fP, if the \fBhighlight\fP resource is \fBTrue\fP.
  289. .NH 3
  290. Getting the Calendar Widget's Current date
  291. .LP
  292. To get the current \fBdate\fP of a calendar widget use the following function:
  293. .FD 0
  294. void CalendarGetDate(\fIwidget\fP, \fIdate_ptr\fP)
  295. .br
  296.       CalendarWidget \fIwidget\fP;
  297.       Date * \fIdate_ptr\fP;
  298. .FN
  299. .IP \fIwidget\fP 1i
  300. Specifies the calendar widget.
  301. .IP \fIdate_ptr\fP 1i
  302. Specifies a pointer to the date structure to be filled in with the specified
  303. calendar widget's current \fBdate\fP.
  304. .NH 3
  305. Other Ways to Change the Calendar Widget's date
  306. .LP
  307. To increment or decrement the \fBdate\fP for the calendar widget to highlight
  308. by one day use the following functions:
  309. .FD 0
  310. void CalendarIncDay(\fIwidget\fP, \fIshow\fP)
  311. void CalendarDecDay(\fIwidget\fP, \fIshow\fP)
  312. .br
  313.       CalendarWidget \fIwidget\fP;
  314.       Boolean \fIshow\fP;
  315. .FN
  316. .IP \fIwidget\fP 1i
  317. Specifies the Calendar widget.
  318. .IP \fIshow\fP 1i
  319. Flag to control behavior on month rollover.
  320. .LP
  321. If \fIshow\fP is \fBTrue\fP, then these routines will automatically call
  322. \fBCalendarShowMonth\fP with the resultant \fBmonth\fP.  Thus, the calendar
  323. widget will always display the resultant \fBdate\fP, and if the
  324. \fBhighlight\fP resource is \fBTrue\fP, it will be highlighted.
  325. .LP
  326. If \fIshow\fP is \fBFalse\fP, the \fBmonth\fP the calendar is currently
  327. displaying will be unaffected.  However, because the \fBdate\fP has changed,
  328. the highlighted day could visibly move, disappear into another month, or
  329. appear in the current month, depending on what \fBmonth\fP the calendar widget
  330. is currently displaying.
  331. .NH 3
  332. Other Ways to Change the Calendar Widget's Month
  333. .LP
  334. To increment or decrement the \fBmonth\fP of a calendar widget by a month or a
  335. year use the following functions:
  336. .FD 0
  337. void CalendarIncMonth(\fIwidget\fP)
  338. void CalendarDecMonth(\fIwidget\fP)
  339. void CalendarIncYear(\fIwidget\fP)
  340. void CalendarDecYear(\fIwidget\fP)
  341. .br
  342.       CalendarWidget \fIwidget\fP;
  343. .FN
  344. .IP \fIwidget\fP 1i
  345. Specifies the calendar widget.
  346. .LP
  347. The calendar widget's \fBdate\fP is unaffected by these functions.
  348. .NH 3
  349. Getting Today's Date
  350. .LP
  351. .FD 0
  352. Date GetTodaysDate()
  353. .br
  354. .FN
  355. Most applications are going to need this, so it has been provided.
  356. .NH 3
  357. Getting the Calendar Widget's date in a Pretty Format
  358. .LP
  359. .FD 0
  360. char * CalendarPrettyDate(\fIwidget\fP)
  361. .br
  362.       CalendarWidget \fIwidget\fP;
  363. .FN
  364. .IP \fIwidget\fP 1i
  365. Specifies the calendar widget.
  366. .LP
  367. This function returns a string like "Sat September 17, 1966" based on the
  368. current \fBdate\fP of the specified calendar widget.  The weekday and month
  369. text will be gotten from the string tables specified for the
  370. \fBweekdayNames\fP and \fBmonthNames\fP resources.
  371. .LP
  372. .NH 3
  373. To convert a string to a Date structure
  374. .FD 0
  375. Date DateConverter(\fIwidget\fP, \fIstring\fP)
  376. .br
  377.       CalendarWidget \fIwidget\fP;
  378.       char * \fIstring\fP;
  379. .FN
  380. .IP \fIwidget\fP 1i
  381. Specifies the calendar widget whose \fBmonthNames\fP resource will be used to
  382. convert any month name in the specified \fIstring\fP into an integer in the
  383. month field of the returned Date structure.
  384. .IP \fIstring\fP 1i
  385. Specifies the string to be converted.
  386. .LP
  387. Several date formats are accepted.  If the \fIstring\fP specified does not
  388. correspond to a valid date, then the Date structure returned will have zero
  389. for the month, day, and year fields.  Remember that only a month and a year
  390. are required to specify a unique month.  As an extension, if only a year is
  391. specified, a Date will be returned corresponding to January of that year.
  392. .NH 2
  393. Copyright
  394. .LP
  395. Copyright 1990 Harris Corporation
  396. .LP
  397. Permission to use, copy, modify, and distribute, this software and its
  398. documentation for any purpose is hereby granted without fee, provided that
  399. the above copyright notice appear in all copies and that both that
  400. copyright notice and this permission notice appear in supporting
  401. documentation, and that the name of the copyright holder be used in
  402. advertising or publicity pertaining to distribution of the software with
  403. specific, written prior permission, and that no fee is charged for further
  404. distribution of this software, or any modifications thereof.  The copyright
  405. holder makes no representations about the suitability of this software for
  406. any purpose.  It is provided "as is" without express or implied warranty.
  407. .LP
  408. THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  409. INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, AND IN NO
  410. EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  411. CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM ITS USE,
  412. LOSS OF DATA, PROFITS, QPA OR GPA, WHETHER IN AN ACTION OF CONTRACT,
  413. NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH
  414. THE USE OR PERFORMANCE OF THIS SOFTWARE.
  415. .NH 2
  416. Author
  417. .LP
  418. .nf
  419. Jason Baietto
  420. jason@ssd.csd.harris.com
  421.