home *** CD-ROM | disk | FTP | other *** search
/ Hot Shareware 35 / hot35.iso / ficheros / 9TOOL / CALEN32A.ZIP / MANUAL.TXT < prev    next >
Text File  |  1998-03-23  |  17KB  |  419 lines
  1.                   Calendar Development Library 1.0 for Windows
  2.                           Copyright (c) Delta Computing
  3.                            http://www.salrom.com/delta
  4.                              delta.computing@usa.net
  5.                                All rights reserved
  6.  
  7.  
  8.  
  9.                                *** User Manual ***
  10.  
  11.  
  12.  
  13.  
  14.  
  15.     1. Setting up the development environment
  16.     2. Developing your programs
  17.     3. The CALENDAR structure
  18.     4. Function reference
  19.     5. The example program
  20.     6. Distributing your programs
  21.     7. 3D controls
  22.     8. The Notice window
  23.  
  24.  
  25.  
  26.  
  27. 1. Setting up the development environment
  28. -----------------------------------------
  29.  
  30. Before starting to develop your programs, you must set up the environment. To do
  31. so, follow these three steps:
  32.  
  33. a)  Install the appropriate link library (.lib file) to:
  34.     - a directory included in your PATH environment variable, or
  35.     - your local compiler's LIB directory.
  36.     Be sure to copy the appropriate .lib file, or you will get an error while
  37.     linking your programs:
  38.     - CALEND16.LIB      for Windows 3.1
  39.     - CALEND32.LIB      for Windows 95 / NT and Microsoft C compilers
  40.     - CALEN32B.LIB      for Windows 95 / NT and Borland C compilers
  41.  
  42. b)  Install the include file CALENDAR.H to
  43.     - a directory included in your PATH environment variable, or
  44.     - your local compiler's INCLUDE directory, or
  45.     - the directory containing your source files.
  46.  
  47. c)  To run your programs you must allow the system find the DLL file
  48.     corresponding to the LIB you linked:
  49.     - CALEND16.DLL      or
  50.     - CALEND32.DLL      or
  51.     - CALEN32B.DLL
  52.     You may copy the proper DLL file to:
  53.     - the same directory as the executable program, or
  54.     - a directory included in your PATH environment variable, or
  55.     - your Windows directory.
  56.  
  57.  
  58.  
  59. 2. Developing your programs
  60. ---------------------------
  61.  
  62. To write a Windows program that uses the Calendar, you must simply
  63. - include the CALENDAR.H in your source file,
  64. - put the correct function calls into your source code,
  65. - put the appropriate .lib file in your link statement.
  66. It's as simple as that. The example program (see section 5.) shows you the
  67. correct sequence of calls to the Calendar functions, and it can be compiled in
  68. Windows 3.1, 95 and NT environments.
  69.  
  70. By pressing the Help button in the Calendar window, you get a help window. The
  71. source code for this help file is also distributed with this package, so that
  72. you can change it as you prefer. If you are not familiar with the Rich Text
  73. Format (rtf) syntax, don't modify this file, or use an RTF editor. To compile
  74. the RTF file, use a help complier (hc or hcrtf).
  75.  
  76.  
  77.  
  78. 3. The CALENDAR structure
  79. -------------------------
  80.  
  81. This structure is used to read and set the parameters that affect the appearance
  82. of the calendar: see calGetParams() and calSetParams(). Here follows a
  83. description of each member.
  84.  
  85. typedef struct
  86. {
  87.     int         xPos;
  88.     int         yPos;
  89.     int         xSize;
  90.     int         ySize;
  91.     COLORREF    DayColor;
  92.     COLORREF    SelectedDayColor;
  93.     COLORREF    SelectedBkgColor;
  94.     BOOL        Days3D;
  95.     BOOL        ClickToSelect;
  96.     short        FirstDayOfWeek;
  97.     char        FontName[LF_FACESIZE];
  98. } CALENDAR;
  99.  
  100. Members:
  101.     xPos                Horizontal coordinate of the top-left corner of the
  102.                         calendar window. This can be any valid value within the
  103.                         range 0 - screen width. If this value is changed from
  104.                         the default, also the yPos parameter must be changed.
  105.  
  106.     yPos                Vertical coordinate of the top-left corner of the
  107.                         calendar window. This can be any valid value within the
  108.                         range 0 - screen height. If this value is changed from
  109.                         the default, also the xPos parameter must be changed.
  110.  
  111.     xSize               Horizontal size of the calendar window. If this value
  112.                         is changed from the default, also the ySize parameter
  113.                         must be changed.
  114.  
  115.     ySize               Vertical size of the calendar window. If this value
  116.                         is changed from the default, also the xSize parameter
  117.                         must be changed.
  118.  
  119.     DayColor            Text color of all unselected days.
  120.  
  121.     SelectedDayColor    Text color of currently selected day.
  122.  
  123.     SelectedBkgColor    Background color of currently selected day. This
  124.                         parameter is ignored if the Days3D parameter is TRUE.
  125.  
  126.     Days3D              Specifies whether days should be displayed as buttons
  127.                         (TRUE) or not (FALSE). If this parameter is set to TRUE,
  128.                         the SelectedBkgColor parameter in this structure is
  129.                         ignored.
  130.  
  131.     ClickToSelect        If set to TRUE, it will be necessary a click of the left
  132.                         mouse button to select a date, otherwise the currently
  133.                         selected date will follow the mouse pointer without
  134.                         clicking.
  135.                         Note: if set to FALSE, in not all cases it will be
  136.                         possible to click the OK button to confirm a date and
  137.                         close the calendar. In this case the date can be
  138.                         selected with a double click.
  139.  
  140.     FirstDayOfWeek        By default Sunday is the first day of week and appears
  141.                         as the first in the calendar. If you prefer another day
  142.                         as the first, alter this parameter. Valid values are:
  143.                         SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY,
  144.                         SATURDAY.
  145.  
  146.     FontName            Use this array to specify the name of a font for the
  147.                         text of the numbers 1 to 31 in the current month. This
  148.                         array is 32 bytes long, so do not exceed this length,
  149.                         including the string terminator, to avoid a memory
  150.                         fault. If the font does not exist, Calendar uses the
  151.                         system font.
  152.  
  153.  
  154.  
  155. 4. Function reference
  156. ---------------------
  157.  
  158. --------------------------------------------------------------------------------
  159. Function: Calendar
  160.     Displays a monthly calendar
  161.  
  162.     #include "calendar.h"
  163.     char *DLLENTRY Calendar(HWND hWnd, char *SelectedDate, char *StartingDate)
  164.  
  165. Parameters
  166.     hWnd                Handle of the window that owns the calendar. This
  167.                         must be a valid window handle
  168.  
  169.     SelectedDate        The date that was selected by the user. This string will
  170.                         contain a date in the form "yyyymmdd"
  171.  
  172.     StartingDate        The date that Calendar should display as starting
  173.                         selected date. If this parameter is NULL or if it
  174.                         doesn't contain a valid date, the first selected date
  175.                         will be the current day.
  176.  
  177. Return Value
  178.     Upon successful termination, the function returns a pointer to the
  179.     SelectedDate parameter, which will contain the date selected by the user.
  180.  
  181. Remarks
  182.     This function creates a modal dialog box that will remain on screen until
  183.     a date is selected (double click or OK button), or the operation is canceled
  184.     (Cancel button). The calendar is shown using the current settings, which can
  185.     be altered with calls to the calGetParams() and calSetParams() functions.
  186.     If the Days3D parameter was left unchanged or set to TRUE (see section 3.),
  187.     the SelectedBkgColor parameter is ignored.
  188.  
  189.     This function does not allocate memory for the SelectedDate parameter, so it
  190.     must receive a valid pointer, or it will fail.
  191.     The function fails if the calInit() wasn't previously called.
  192.     If this product was not purchased yet, a Notice window will display on top
  193.     of the calendar. This window will NOT display when the product is
  194.     purchased. The notice window can be minimized or closed.
  195.  
  196. --------------------------------------------------------------------------------
  197. Function: calGetParams
  198.     Reads the current Calendar settings
  199.  
  200.     #include "calendar.h"
  201.     LPCALENDAR DLLENTRY calGetParams(LPCALENDAR Params)
  202.  
  203. Parameters
  204.     Params                Points to a CALENDAR structure that is to receive the
  205.                         current settings.
  206.  
  207. Return Value
  208.     If the function succeeds, the return value is a pointer to the Params
  209.     structure.
  210.     If the function fails, the return value is a NULL pointer.
  211.  
  212. Remarks
  213.     Upon successful termination, the Params structure is filled with the current
  214.     settings and a pointer to the sructure itself is returned. The function does
  215.     not allocate memory for the structure, so it must receive a valid pointer,
  216.     or it will fail. The function fails if the calInit() wasn't previously
  217.     called. This function is useful when you want to change one or more default
  218.     settings: you should call this function, alter the parameters you prefer and
  219.     then submit the changes with a call to the calSetParams(). Starting from
  220.     this moment, the calendar will display using the new settings.
  221.     Note: Calendar can manage only one set of parameters at a time.
  222.  
  223. --------------------------------------------------------------------------------
  224. Function: calInit
  225.     Initializes the Calendar DLL
  226.  
  227.     #include "calendar.h"
  228.     void DLLENTRY calInit(char *InitString)
  229.  
  230. Parameters
  231.     InitString          Initialization string. This must be exactly the keycode
  232.                         received upon registration, or the uppercase string
  233.                         "EVALUATE".
  234.  
  235. Return Value
  236.     This function does not return a value. If the InitString parameter is
  237.     incorrect, the calendar will not display.
  238.  
  239. Remarks
  240.     This function should only be used once, as it does some one-time operations.
  241.     It can be called from anywhere in the program, provided it's the first
  242.     function in the Calendar library to be called.
  243.     The InitString parameter is case sensitive.
  244.     If the function is called with the "EVALUATE" parameter, a notice window
  245.     will display on top of the calendar. This window will NOT display when the
  246.     product is purchased. The notice window can be minimized or closed.
  247.  
  248. --------------------------------------------------------------------------------
  249. Function: calSetDefaults
  250.     Restores the default settings
  251.  
  252.     #include "calendar.h"
  253.     void DLLENTRY calSetDefaults(void)
  254.  
  255. Parameters
  256.     This function has no parameters.
  257.  
  258. Return Value
  259.     This function does not return a value.
  260.  
  261. Remarks
  262.     Use this function to restore all the built-in parameters for the calendar.
  263.     The function fails if the calInit() wasn't previously called. After a call
  264.     to this function, the Calendar will display using the following default
  265.     settings:
  266.  
  267.     initial x position of window           : -1             (decided by Windows)
  268.     initial y position of window           : -1             (   "    "     "   )
  269.     initial x size of window               : -1             (226 pixels)
  270.     initial y size of window               : -1             (153 pixels)
  271.     color of unselected days               : RGB(0,0,0)     (black)
  272.     color of selected days                 : RGB(255,0,0)   (red)
  273.     backgnd color of selected days (no 3D) : RGB(0,0,255)   (blue)
  274.     3D appearance of days                  : TRUE           (button-like)
  275.     mouse click necessary to select day    : TRUE
  276.     first day of week                      : SUNDAY
  277.     name of font for numbers of days       : ""             (system font)
  278.  
  279. --------------------------------------------------------------------------------
  280. Function: calSetParams
  281.     Write new settings into Calendar
  282.  
  283.     #include "calendar.h"
  284.     BOOL DLLENTRY calSetParams(LPCALENDAR Params)
  285.  
  286. Parameters
  287.     Params              Points to a CALENDAR structure that contains the new
  288.                         settings.
  289.  
  290. Return Value
  291.     If the function succeeds, the return value TRUE.
  292.     If the function fails, the return value is a FALSE.
  293.  
  294. Remarks
  295.     Upon successful termination, the current settings are modified using those
  296.     contained in the Params structure. All of the parameters are used. If the
  297.     function fails, the current settings remain unchanged. The function fails if
  298.     it received an invalid pointer or if the calInit() wasn't previously called.
  299.     This function is useful when you want to change one or more default
  300.     settings: you may issue a call to the calGetParams(), alter the parameters
  301.     you prefer and then submit the changes with a call to this function.
  302.     Starting from this moment, the calendar will display using the new settings.
  303.     To change the default window position, both the xPos and yPos parameters
  304.     must be set. To change the default window size, both the xSize and ySize
  305.     parameters must be set.
  306.     Note: Calendar can manage only one set of parameters at a time.
  307.  
  308. --------------------------------------------------------------------------------
  309.  
  310.  
  311. 5. The example program
  312. ----------------------
  313.  
  314. The example is an easy and quick way to get started with Calendar. This program
  315. contains a call to every function of the library and there is an example on
  316. how to change the default settings.
  317. The program can be compiled on both 16 and 32 bit systems (Windows 3.1, 95, NT).
  318. This package contains the makefile for the same environment as the Calendar
  319. library. Use exampl16.mak in Windows 3.1 and exampl32.mak in Windows 95 and
  320. NT. These makefiles can be used as they are when compiling in a DOS shell, or
  321. they can be imported in the compiler's visual environment.
  322.  
  323. To compile in a DOS shell use the following commands:
  324. - Windows 3.1:    nmake exampl16.mak
  325. - Windows 95/NT:  nmake exampl32.mak
  326.  
  327. The makefile generates by default a debuggable program, but if you want an
  328. optimized version, edit the makefile and change the line
  329. DEBUG   = 1
  330. to:
  331. DEBUG   = 0
  332.  
  333. This example is an extremely simple program, and its purpose is just to show
  334. a possible way to use the Calendar functions and where to put them. Please
  335. don't judge it for what it's not intended to be!
  336.  
  337.  
  338.  
  339. 6. Distributing your programs
  340. -----------------------------
  341.  
  342. After creating your program with a Calendar in it, remember to distribute
  343. the following files to the end users:
  344.  
  345.   Windows 3.1    |   Windows 95 / NT
  346. -----------------+------------------
  347.   CALEND16.DLL   |   CALEND32.DLL
  348.   CALENDAR.HLP   |   CALENDAR.HLP
  349.  
  350. In order to work properly, Calendar requires the following system libraries be
  351. present on the destination machine:
  352.  
  353.   Windows 3.1    |   Windows 95 / NT
  354. -----------------+------------------
  355.   OLE2NLS.DLL    |   COMCTL32.DLL
  356.  
  357. Each of these files are installed by default and should be present on the
  358. destination machine. OLE2NLS.DLL contains, on Windows 3.1 systems, informations
  359. about the local area, and particularly contains the names of months and days
  360. in the local language. In Windows 95 the file COMCTL32.DLL contains additional
  361. dialog controls, such as spins, that are used by Calendar.
  362. Calendar library is directly linked to these libraries.
  363.  
  364. If you want to create a perfect installation program, ensure that the file exist
  365. on the destination machine, but remember NOT to install these files when they
  366. already exist!
  367.  
  368.  
  369.  
  370. 7. 3D Controls
  371. --------------
  372.  
  373. In Windows 95 you have a 3D look for controls: entry fields, check and radio
  374. buttons etc. In Windows 3.1, you have just a "flat" appearance for all controls
  375. except for push buttons. On this system, however, it is possible to give a 3D
  376. appearance to controls by using the ctl3d or ctl3dv2 system libraries.
  377. Calendar does NOT require the presence of these libraries, but if any of them
  378. exist on the destination machine, it's loaded and used by Calendar.
  379. If one of these libraries is already loaded by your program, Calendar uses it
  380. without loading it again.
  381. The ctl3d.dll file comes with the Calendar package, and you are free to decide
  382. whether to distribute it with your software packages or not. The ctl3dv2.dll
  383. file should be present on Windows 3.1 system, but it shouldn't be present on
  384. Windows 95/NT systems, so if you are about to create a 16-bit program, consider
  385. that if the end user runs your program on a 32-bit system, he/she won't get the
  386. 3D look. In this case you need to distribute the ctl3d.dll with your software
  387. package. You don't need to distribute it if you create a 32-bit program.
  388.  
  389. The following table is a summary of all the cases when the ctl3d library can
  390. be used.
  391.  
  392.    \ sys |       |         |
  393.      \tem|  Win  |   Win   |
  394. program\ |  3.1  | 95 / NT |
  395. ---------+-------+---------+
  396.  16 bit  |  Yes  |   Yes   |
  397. ---------+-------+---------+
  398.  32 bit  |Doesn't|   No    |
  399.          |  run  |         |
  400. ---------+-------+---------+
  401.  
  402. If you don't know much about ctl3d and you want to put it into your programs,
  403. send an e-mail message asking for more informations.
  404.  
  405.  
  406.  
  407. 8. The Notice window
  408. --------------------
  409.  
  410. This is a very bothering window, and I hope it reaches its purpose! It should
  411. encourage you to register. If your intention is to use Calendar for your
  412. program, why waiting when you may register today and avoid being bothered
  413. whenever you execute your program for testing?
  414. Calendar is absolutely NOT EXPENSIVE and especially is ROYALTY FREE. Please
  415. help supporting the shareware concept.
  416.  
  417. Remember that if you distribute an unregistered version of Calendar, this
  418. notice window shall appear to the end user.
  419.