manual.txt

实现日历的动态链接库

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.