manual.txt

实现日历的动态链接库

                  Calendar Development Library 1.0 for Windows
                          Copyright (c) Delta Computing
                           http://www.salrom.com/delta
                             [e-mail]
                               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.