Calendar Development Library 1.0 for Windows Copyright (c) Delta Computing http://www.salrom.com/delta delta.computing@usa.net All rights reserved *** User Manual *** 1. Setting up the development environment 2. Developing your programs 3. The CALENDAR structure 4. Function reference 5. The example program 6. Distributing your programs 7. 3D controls 8. The Notice window 1. Setting up the development environment ----------------------------------------- Before starting to develop your programs, you must set up the environment. To do so, follow these three steps: a) Install the appropriate link library (.lib file) to: - a directory included in your PATH environment variable, or - your local compiler's LIB directory. Be sure to copy the appropriate .lib file, or you will get an error while linking your programs: - CALEND16.LIB for Windows 3.1 - CALEND32.LIB for Windows 95 / NT and Microsoft C compilers - CALEN32B.LIB for Windows 95 / NT and Borland C compilers b) Install the include file CALENDAR.H to - a directory included in your PATH environment variable, or - your local compiler's INCLUDE directory, or - the directory containing your source files. c) To run your programs you must allow the system find the DLL file corresponding to the LIB you linked: - CALEND16.DLL or - CALEND32.DLL or - CALEN32B.DLL You may copy the proper DLL file to: - the same directory as the executable program, or - a directory included in your PATH environment variable, or - your Windows directory. 2. Developing your programs --------------------------- To write a Windows program that uses the Calendar, you must simply - include the CALENDAR.H in your source file, - put the correct function calls into your source code, - put the appropriate .lib file in your link statement. It's as simple as that. The example program (see section 5.) shows you the correct sequence of calls to the Calendar functions, and it can be compiled in Windows 3.1, 95 and NT environments. By pressing the Help button in the Calendar window, you get a help window. The source code for this help file is also distributed with this package, so that you can change it as you prefer. If you are not familiar with the Rich Text Format (rtf) syntax, don't modify this file, or use an RTF editor. To compile the RTF file, use a help complier (hc or hcrtf). 3. The CALENDAR structure ------------------------- This structure is used to read and set the parameters that affect the appearance of the calendar: see calGetParams() and calSetParams(). Here follows a description of each member. typedef struct { int xPos; int yPos; int xSize; int ySize; COLORREF DayColor; COLORREF SelectedDayColor; COLORREF SelectedBkgColor; BOOL Days3D; BOOL ClickToSelect; short FirstDayOfWeek; char FontName[LF_FACESIZE]; } CALENDAR; Members: xPos Horizontal coordinate of the top-left corner of the calendar window. This can be any valid value within the range 0 - screen width. If this value is changed from the default, also the yPos parameter must be changed. yPos Vertical coordinate of the top-left corner of the calendar window. This can be any valid value within the range 0 - screen height. If this value is changed from the default, also the xPos parameter must be changed. xSize Horizontal size of the calendar window. If this value is changed from the default, also the ySize parameter must be changed. ySize Vertical size of the calendar window. If this value is changed from the default, also the xSize parameter must be changed. DayColor Text color of all unselected days. SelectedDayColor Text color of currently selected day. SelectedBkgColor Background color of currently selected day. This parameter is ignored if the Days3D parameter is TRUE. Days3D Specifies whether days should be displayed as buttons (TRUE) or not (FALSE). If this parameter is set to TRUE, the SelectedBkgColor parameter in this structure is ignored. ClickToSelect If set to TRUE, it will be necessary a click of the left mouse button to select a date, otherwise the currently selected date will follow the mouse pointer without clicking. Note: if set to FALSE, in not all cases it will be possible to click the OK button to confirm a date and close the calendar. In this case the date can be selected with a double click. FirstDayOfWeek By default Sunday is the first day of week and appears as the first in the calendar. If you prefer another day as the first, alter this parameter. Valid values are: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. FontName Use this array to specify the name of a font for the text of the numbers 1 to 31 in the current month. This array is 32 bytes long, so do not exceed this length, including the string terminator, to avoid a memory fault. If the font does not exist, Calendar uses the system font. 4. Function reference --------------------- -------------------------------------------------------------------------------- Function: Calendar Displays a monthly calendar #include "calendar.h" char *DLLENTRY Calendar(HWND hWnd, char *SelectedDate, char *StartingDate) Parameters hWnd Handle of the window that owns the calendar. This must be a valid window handle SelectedDate The date that was selected by the user. This string will contain a date in the form "yyyymmdd" StartingDate The date that Calendar should display as starting selected date. If this parameter is NULL or if it doesn't contain a valid date, the first selected date will be the current day. Return Value Upon successful termination, the function returns a pointer to the SelectedDate parameter, which will contain the date selected by the user. Remarks This function creates a modal dialog box that will remain on screen until a date is selected (double click or OK button), or the operation is canceled (Cancel button). The calendar is shown using the current settings, which can be altered with calls to the calGetParams() and calSetParams() functions. If the Days3D parameter was left unchanged or set to TRUE (see section 3.), the SelectedBkgColor parameter is ignored. This function does not allocate memory for the SelectedDate parameter, so it must receive a valid pointer, or it will fail. The function fails if the calInit() wasn't previously called. If this product was not purchased yet, a Notice window will display on top of the calendar. This window will NOT display when the product is purchased. The notice window can be minimized or closed. -------------------------------------------------------------------------------- Function: calGetParams Reads the current Calendar settings #include "calendar.h" LPCALENDAR DLLENTRY calGetParams(LPCALENDAR Params) Parameters Params Points to a CALENDAR structure that is to receive the current settings. Return Value If the function succeeds, the return value is a pointer to the Params structure. If the function fails, the return value is a NULL pointer. Remarks Upon successful termination, the Params structure is filled with the current settings and a pointer to the sructure itself is returned. The function does not allocate memory for the structure, so it must receive a valid pointer, or it will fail. The function fails if the calInit() wasn't previously called. This function is useful when you want to change one or more default settings: you should call this function, alter the parameters you prefer and then submit the changes with a call to the calSetParams(). Starting from this moment, the calendar will display using the new settings. Note: Calendar can manage only one set of parameters at a time. -------------------------------------------------------------------------------- Function: calInit Initializes the Calendar DLL #include "calendar.h" void DLLENTRY calInit(char *InitString) Parameters InitString Initialization string. This must be exactly the keycode received upon registration, or the uppercase string "EVALUATE". Return Value This function does not return a value. If the InitString parameter is incorrect, the calendar will not display. Remarks This function should only be used once, as it does some one-time operations. It can be called from anywhere in the program, provided it's the first function in the Calendar library to be called. The InitString parameter is case sensitive. If the function is called with the "EVALUATE" parameter, a notice window will display on top of the calendar. This window will NOT display when the product is purchased. The notice window can be minimized or closed. -------------------------------------------------------------------------------- Function: calSetDefaults Restores the default settings #include "calendar.h" void DLLENTRY calSetDefaults(void) Parameters This function has no parameters. Return Value This function does not return a value. Remarks Use this function to restore all the built-in parameters for the calendar. The function fails if the calInit() wasn't previously called. After a call to this function, the Calendar will display using the following default settings: initial x position of window : -1 (decided by Windows) initial y position of window : -1 ( " " " ) initial x size of window : -1 (226 pixels) initial y size of window : -1 (153 pixels) color of unselected days : RGB(0,0,0) (black) color of selected days : RGB(255,0,0) (red) backgnd color of selected days (no 3D) : RGB(0,0,255) (blue) 3D appearance of days : TRUE (button-like) mouse click necessary to select day : TRUE first day of week : SUNDAY name of font for numbers of days : "" (system font) -------------------------------------------------------------------------------- Function: calSetParams Write new settings into Calendar #include "calendar.h" BOOL DLLENTRY calSetParams(LPCALENDAR Params) Parameters Params Points to a CALENDAR structure that contains the new settings. Return Value If the function succeeds, the return value TRUE. If the function fails, the return value is a FALSE. Remarks Upon successful termination, the current settings are modified using those contained in the Params structure. All of the parameters are used. If the function fails, the current settings remain unchanged. The function fails if it received an invalid pointer or if the calInit() wasn't previously called. This function is useful when you want to change one or more default settings: you may issue a call to the calGetParams(), alter the parameters you prefer and then submit the changes with a call to this function. Starting from this moment, the calendar will display using the new settings. To change the default window position, both the xPos and yPos parameters must be set. To change the default window size, both the xSize and ySize parameters must be set. Note: Calendar can manage only one set of parameters at a time. -------------------------------------------------------------------------------- 5. The example program ---------------------- The example is an easy and quick way to get started with Calendar. This program contains a call to every function of the library and there is an example on how to change the default settings. The program can be compiled on both 16 and 32 bit systems (Windows 3.1, 95, NT). This package contains the makefile for the same environment as the Calendar library. Use exampl16.mak in Windows 3.1 and exampl32.mak in Windows 95 and NT. These makefiles can be used as they are when compiling in a DOS shell, or they can be imported in the compiler's visual environment. To compile in a DOS shell use the following commands: - Windows 3.1: nmake exampl16.mak - Windows 95/NT: nmake exampl32.mak The makefile generates by default a debuggable program, but if you want an optimized version, edit the makefile and change the line DEBUG = 1 to: DEBUG = 0 This example is an extremely simple program, and its purpose is just to show a possible way to use the Calendar functions and where to put them. Please don't judge it for what it's not intended to be! 6. Distributing your programs ----------------------------- After creating your program with a Calendar in it, remember to distribute the following files to the end users: Windows 3.1 | Windows 95 / NT -----------------+------------------ CALEND16.DLL | CALEND32.DLL CALENDAR.HLP | CALENDAR.HLP In order to work properly, Calendar requires the following system libraries be present on the destination machine: Windows 3.1 | Windows 95 / NT -----------------+------------------ OLE2NLS.DLL | COMCTL32.DLL Each of these files are installed by default and should be present on the destination machine. OLE2NLS.DLL contains, on Windows 3.1 systems, informations about the local area, and particularly contains the names of months and days in the local language. In Windows 95 the file COMCTL32.DLL contains additional dialog controls, such as spins, that are used by Calendar. Calendar library is directly linked to these libraries. If you want to create a perfect installation program, ensure that the file exist on the destination machine, but remember NOT to install these files when they already exist! 7. 3D Controls -------------- In Windows 95 you have a 3D look for controls: entry fields, check and radio buttons etc. In Windows 3.1, you have just a "flat" appearance for all controls except for push buttons. On this system, however, it is possible to give a 3D appearance to controls by using the ctl3d or ctl3dv2 system libraries. Calendar does NOT require the presence of these libraries, but if any of them exist on the destination machine, it's loaded and used by Calendar. If one of these libraries is already loaded by your program, Calendar uses it without loading it again. The ctl3d.dll file comes with the Calendar package, and you are free to decide whether to distribute it with your software packages or not. The ctl3dv2.dll file should be present on Windows 3.1 system, but it shouldn't be present on Windows 95/NT systems, so if you are about to create a 16-bit program, consider that if the end user runs your program on a 32-bit system, he/she won't get the 3D look. In this case you need to distribute the ctl3d.dll with your software package. You don't need to distribute it if you create a 32-bit program. The following table is a summary of all the cases when the ctl3d library can be used. \ sys | | | \tem| Win | Win | program\ | 3.1 | 95 / NT | ---------+-------+---------+ 16 bit | Yes | Yes | ---------+-------+---------+ 32 bit |Doesn't| No | | run | | ---------+-------+---------+ If you don't know much about ctl3d and you want to put it into your programs, send an e-mail message asking for more informations. 8. The Notice window -------------------- This is a very bothering window, and I hope it reaches its purpose! It should encourage you to register. If your intention is to use Calendar for your program, why waiting when you may register today and avoid being bothered whenever you execute your program for testing? Calendar is absolutely NOT EXPENSIVE and especially is ROYALTY FREE. Please help supporting the shareware concept. Remember that if you distribute an unregistered version of Calendar, this notice window shall appear to the end user.