=========================================
DL Components Version 5.00 - Read Me
=========================================



Contents
========
 - Overview
 - Installation
    - Important - Before you Begin
    - Installing the Components in Delphi 2
    - Installing the Components in Delphi 4, 5 and 6
    - Installing Help
 - Trouble Shooting
    - File not found: 'dsgnintf.dcu'
    - File not found: 'dlde.dcu' (or 'dlled.dcu')
    - Context Help is not available
 - Using the Components
    - TDLDateEdit & TDLDBDateEdit Properties
    - TDLDBDateText Properties
    - TDLCalendar Properties
    - TDLLED Properties
    - TDLDateEdit, TDLDBDateEdit and TDLCalendar Methods
    - TDLDateEdit and TDLDBDateEdit Events
    - TDLCalendar Events
    - Alternative LEDs
 - Compiling the Demos
 - File List
 - Source Code
 - Getting Help
    - Mail
    - Email
    - Web Site
    - Source Code
    - Bugs & Typos 



Overview
========

The DL Components is a small, FREE set of Delphi components, consisting of the 
five following new objects:

* TDLDateEdit     a TEdit replacement that is specifically designed to
                  handle date entry. It applies validation and enforces
                  4-digit year display. It converts 2-digit year values
                  into 4 digits. It is also an alternative to the 
                  TDateTimePicker control.

* TDLDBDateEdit   a data-aware version of TDLDBDateEdit (a replacement for
                  the TDBEdit component).

* TDLDBDateText   a date data-aware version of the TDBText control.

* TDLCalendar     a calendar control that you can use independantly of
                  the TDLDateEdit control.

* TDLLED          an LED-like control that is useful to indicate change
                  in status, data, or to indicate the activity of special
                  functions.

The two Date editing controls feature:

* Built in pop-up calendar (similar to Lotus Notes and MS Money)
* Either keyboard entry or calendar entry can be disabled
* Calendar can be opened programmatically when necessary
* Calendar supports mouse and keyboard support
* Validation of dates
* Complete control over invalid date error messages
* Year 2000 readiness (ensures 4-digit year entry, and 2 methods 
  of interpreting 2-digit year values: cusp year, and century default)
* User selectable date format
* Customisable calendar (select which day the week starts on, the
  colour of dates occurring on weekends, whether the calendar is 
  filled or only includes the current month)
* Easily customisable to different languages and date formats
* Customisable calendar button
* Offers three events for the developer to trap

One special advantage offered is that, unlike the TDateTimePicker, one of the
date edit controls is data aware!

Both the TDLDateEdit and TDLDBDateEdit components are virtually identical
in appearance, giving a consistency to your applications. The TDLDateEdit
controls you use in dialogue boxes will act just like the TDLDBDateEdit
components attached to your date fields.

Versions of the DLComponents collection for Delphi 2, 4, 5 and 6 are available 
in this realease. You will also need the "Developer"/"Professional" or 
"Client-Server"/"Enterprise" editions of Delphi. The "Standandard"/"Personal" editions
do not contain the database components that the DL Components rely on.

[Side note: a Delphi 1 version would require considerable more work in developing
an testing, and there have been very few requests for this. I'll produce a Delphi 3 
version as soon as someone donates a copy of Delphi 3 to me! ;-) ] 



Installation
============

Presumably, you have already unzipped the components into a temporary folder
on your hard disk. Make sure that you extracted the files preserving their
folders. If you haven't done either of these, do so now.


Important - Before You Begin
----------------------------

These components are provided with specific versions for Delphi 2, 4, 5 and 6.
Choose the version that suits the version of Delphi you are working with, and
follow the instructions for the appropriate version. 

It is recommended that you establish a particular folder on your hard disk for 
storing your third-party VCL components such as the DL Components. For example, 
you could use c:\dc for all components (a short path and folder name makes add-in 
components easier to manage).


For Delphi 4, 5 and 6, you will need to include this path in Library Path variable,
because the installation process doesn't do this for you. To do this:

 1. From the Tools menu in Delphi, select "Environment Options..."

 2. Select the "Library" tab

 3. At the very end of the Library Path field is a button; click this button
    to display the list of Library paths.

 4. In the field immediately below the list of paths, type in the full path
    to your components (eg c:\dc).

 5. Click Add and then Ok to close the Directories dialog.

 6. Click OK to close the Environment Options dialog



Installing the Components in Delphi 2
-------------------------------------

 1. Copy the files in the dlcomponents\delphi2 folder into your VCL components folder

 2. In Delphi, open the Component menu and select "Install..."

 3. Click the button labelled Add

 4. Click the Browse button and locate the directory where you
    stored the DL Components

 5. Set the file type to *.DCU so you can see the file regdl.dcu

 6. Select regdl.dcu then select OK twice to close all dialogue boxes.

The component library will rebuild, and you will see a new tab labelled "DLComponents".



Installing the Components in Delphi 4, 5 and 6
-----------------------------------------------

 1. Copy the files from the appropriate folder listed below into your VCL components folder

      Delphi 4:  dlcomponents\delphi4
      Delphi 5:  dlcomponents\delphi5
      Delphi 6:  dlcomponents\delphi6

 2. In Delphi, Open the "Component" menu and select "Install Packages..."

 3. Click "Add..."

 4. Browse to the location where you have stored the DL Components, 
    select the file DLComponentsx.bpl (where x is 4, 5 or 6 depending
    on the version you are installing), then click Open.

 5. The "DL Components" package should now be listed with the other
    Design Packages. Click OK to close the components dialog.


Installing the Help
-------------------
 
For Delphi 2 users, you should copy the files

      dlcomponents\help\DLComponents.hlp
      dlcomponents\help\DLComponents.cnt

to the same location as the components or to the Delphi\help folder.
You will need to search for and open this file yourself. (Context 
sensitivity requires a keywords file but this is not currently
available)


For Delphi 4, 5 and 6, you can install the help such that it is context
sensitive:

 1. Firstly make sure Delphi is not running

 2. Copy both of the files:

      dlcomponents\help\DLComponents.hlp
      dlcomponents\help\DLComponents.cnt

   into the Delphi help folder (eg c:\Program Files\Borland\Delphi5\Help )

 3. Use Windows Explorer to delete delphiX.gid and and DelphiX.fts files
    if they exist (ie Delphi4.gid for Delphi 4, Delphi5.gid for Delphi 5 and so on).

 4. Edit the file DelphiX.cnt that is found in the Delphi Help folder 
    (Delphi4.cnt for Delphi 4, Delphi5.cnt for Delphi 5 and so on), and 
    copy-paste the following two lines:

      :Index DLComponents Help=DLComponents.hlp
      :include DLComponents.cnt

 5. Save and close the DelphiX.cnt file.

 6. When you next run Help from within Delphi, you will see the message
    "Preparing help file for first use". The help system is now ready for
    you to access.



Trouble Shooting
================


File not found: 'dsgnintf.dcu'
------------------------------

In some circumstances, you may see this message after attempting to run a
program to which you have added a DL Component. This occurs because Delphi 5
(for some odd reason) was shipped without the dsgnintf.dcu file.

The quickest workaround for this is to copy the file dsgnintf.pas from the 
Delphi5\Source\Toolsapi to the Delphi5\Lib folder. (Alternatively, you could 
add Delphi5\Source\Toolsapi to the Library paths instead)

Once you have performed this workaround, you will be able to compile your
application.


File not found: 'dlde.dcu' (or 'dlled.dcu')
-------------------------------------------

This error occurs because the location you have stored the components has not 
been listed in the Library paths. Follow the instructions in the Before you Begin
section of this file.

The problem may also occur if you have not copied the DCU files to the same 
location as the BPL and DCP files, or have deleted the DCU files. Make sure 
that all 8 files listed in the Installation section above are together in your 
components folder.


Context Help is not available
-----------------------------

If you have attempted to install the help file into Delphi, but when you select
one of the DL Components and press F1, the Delphi Help contents window is all that 
is displayed, then it is possible you didn't complete the installation.

  * Did you copy the DLComponents.hlp and the DLComponents.cnt file into the 
    correct folder (eg Delphi Help)?

  * Did you delete the DelphiX.gid and DelphiX.fts files?

  * Did you edit the DelphiX.cnt file and save the changes?



Using the Components
====================

Most of the components are fairly self-explanatory, and you will probably find
you can work out how to use them simply by dropping them onto a form. Examine
the demos for some examples of how the components can be used.

The only components that require a little bit of explanation are the TDLCalendar 
and TDLLED components. The calendar is not visible at design time other than by
way of an icon placed on your form. you can set all of its visual properties at 
run-time or design-time, but must open it programmatically by using OpenCalendar. 
When the calendar closes, read its Date property.

The LED components are visible at design-time, and you can alter its properties 
while developing your form. However, these are most effective when you change
their properties at run-time in response to changing conditions in your 
application. See demo3 for some ideas on how you can use them.

The on-line help files will provide you with full details on how to
use the components. However, the information below will give you a head start
in understanding the properties, methods and events belonging to these
components.


TDLDateEdit & TDLDBDateEdit Properties
--------------------------------------

AllowKeyEntry:  When set to False, this property will prevent and end-user
                from using the keyboard to enter a date; they are forced
                to use the calendar. Note that they can still use DEL
                to clear the contents of the field. Note that AllowKeyEntry
                and CalendarEnabled cannot both be False.

CalendarCaption: This property is used to store a caption for the calendar.
                This property is ignored if the CalendarStyle is set to
                csStandard.

CalendarEnabled: When set to False, the calendar component is inaccessible
                to the end-user, and date entry must occur via the keyboard.
                You will generally only use this property to hide the
                calendar button when a field is in a read-only state. Note 
                that CalendarEnabled and AllowKeyEntry cannot both be False.

CalendarFillPage: When set to True, the last few days of the previous month
                and the first few days of the next month are used to fill
                the entire calendar page. When set to False, only the
                current month can be seen in the calendar.

CalendarStyle:  This property determines whether the calendar should appear 
                as a simple pop-up object, or in an independent dialog box.


CalendarWeekendColor: This property takes a normal TColor value, the value
                being used to determine what colour to display dates occurring
                on Saturday and Sunday.

CalendarWeekStart: This property determines which day the week is considered
                to start on. By default, wsSunday is used. However, if you 
                want the weekend dates to appear next to each other, you
                may prefer to select wsSaturday or wsMonday instead. You may
                choose any day.

CuspYear:       This property is used to determine how 2-digit year values
                are interpreted. If the 2-digit year value is less than 
                CuspYear, then the year is assumed to be after 2000; if the
                2-digit year is equal to or greater than CuspYear, it is 
                assumed to be in the 1900s. The default value is 30. This
                property is ignored if UseCentury is True.

Date:           A run-time only property representing the Date stored in 
                in the TDLDateEdit or TDLDBDateEdit component.

DateFormat:     A string value representing the format the date is displayed 
                in. All date formats include 4-digit years in keeping with
                current Year 2000 methodologies.

ErrorMessage:   This property is a string that you can use in place of the
                the default error message. Add %s to the string to include
                the users invalid date in the message.

ErrorMessageTitle: This property contains a short string that is used as
                the caption for the message box if the ErrorMessageType
                is set to mtWindows.

ErrorMessageType: This property determines how the component deals with
                invalid dates entered by the user. mtDelphi and mtWindows
                types will cause a dialogue box to be displayed; mtBeep
                causes a warning beep only to be sounded; mtSilent prevents
                any warning from being issued. If you choose mtSilent
                you may wish to add your own error messaging or handling
                to the OnInvalidDate property.

Glyph:          The Glyph property allows you to select a bitmap of your
                own to use in the calendar button. Generally, you will pick 
                an image with dimensions less than 16 pixels x 16 pixels. 
                However, if you have sized the TDLDateEdit or TDLDBDateEdit
                fields larger than normal, you may be able to get away with
                a bigger image. When using this property, you must also
                set the GlyphNum property.

GlyphNum:       This property is used to tell Delphi how many individual
                images are contained within Glyph. GlyphNum can take a 
                value from 1 to 3. All images in the Glyph should be the same
                size and arranged horizontally from left to right. The first 
                image should be the standard button image, the second the 
                'disabled' state, and the third the 'Down' state.

GlyphType:      This property determines whether you use a custom Glyph
                or one of the 6 in-built glyphs, or none at all. When set
                to anything other than gtCustom, the Glyph and GlyphNum 
                properties are ignored.

UseCentury:     When set to True, this property will cause all 2-digit
                year values to be interpreted as occurring in the
                current century.


TDLDBDateText Properties
------------------------

The only special property of this component is the DateFormat property described above.


TDLCalendar Properties
----------------------

In addition to the CalendarCaption, CalendarFillPage, CalendarStyle, 
CalendarWeekendColor, CalendarWeekStart and Date properties:

CalendarLeft:   This property of the TDLCalendar determines the horizontal position
                on the screen where the calendar should be displayed. 

CalendarTop:    This property of the TDLCalendar determines the vertical position
                on the screen where the calendar should be displayed. 


TDLLED Properties
-----------------

Enabled:        This property of the TDLLED component determines whether the
                control should be displayed normally, or with a "grey" LED.

LEDColor:       This property of the TDLLED component determines the colour
                of the LED graphic. A choice of nine colours is available. 

LEDSize:        This property of the TDLLED component determines the size
                of the LED control. LEDs can be displayed in two sizes

LEDState:       This property of the TDLLED component determines the state
                of the LED control. The control can exist in "Off", "On" and
                "Bright" states.

	
TDLDateEdit, TDLDBDateEdit and TDLCalendar Methods
--------------------------------------------------

OpenCalendar:   This method allows you to open the calendar programmatically.
                For example, you may want to have the calendar open 
                automatically when an end-user enters a particular 
                DL DateEdit field; this method will enabled that.

TDLDateEdit and TDLDBDateEdit Events
------------------------------------

OnCloseCalendar: This event occurs just before the calendar is closed.
		
OnInvalidDate:  This event occurs when a user enters an invalid date, 
                just before any ErrorMessage warning is given

OnOpenCalendar: This event occurs immediately before the calendar is
                opened.

TDLCalendar Events
------------------

The TDLCalendar component shares the OnCloseCalendar and OnOpenCalendar events.


Alternative LEDs
----------------

You may find that the LED graphics provided do not satisfy your tastes. Hundreds of
images where prepared, adjusted, tweaked, and destroyed before the set you have before
you was assembled. In fact, the decision to include two sizes of LED with two "On" states
was an attempt to provide something for (nearly) everybody. However, it is recognised that
you can't please everybody all the time.

It is possible for you to modify the LED graphics to suite yourself. To do this, backup the 
file DLLED.RES and then edit this file in the Delphi Image editor. You may even wish to make
several different sets of LEDs.

When you open the DLLED file, you will see that it contains a list of bitmaps with names 
taking the form:

  DLLEDzccs

where:

  z   is the size (S=Small, L=Large)
  cc  is the colour (AM=Amber, BL=Blue, GN=Green, LB=Light Blue, LM=Lime,
                     PK=Pink, PP=Purple, RD=Red, TL=Teal, GY=Grey)       
  s   is the state (0=Off, 1=On, 2=Bright)    

So DLLEDSRD1 would be a small red LED in the On state. Note that the grey LEDs are only
available in the Off state. These are used when the control is disabled.

Things to bear in mind:

 1. The names of the bitmaps cannot be changed. This will result in runtime errors.

 2. You cannot add new images (representing additional colours or states), they will be 
    ignored.

 3. All LEDs are 10 pixels by 10 pixels, and these dimensions cannot be altered. If you 
    were to change the size, only the top area of 10x10 pixels will be displayed.

 4. You should have the colour of the LEDs match roughly with the existing description,  
    otherwise you will be making things harder for yourself if you want to control
    the LEDs programmatically.

 5. Similarly, always make State 0 the dullest and state 2 the brightest.

 6. Once you have modified the LEDs, all applications you compile thereafter will use the
    new LEDs. So if you want to use different LEDs for different projects, you will need 
    to remember to swap the different .RES

(Note that items 1, 2 and 3 above are actually possible if you purchase and modify the 
source code.)

If you create new LEDs, please do NOT distribute them in the package in place of the 
DLLED.RES file. By all means distribute them, but provide them in a separate zip file, with
an alternate name. Include a short text file saying who they were created by, and how to 
incorporate them, for example:

    Cool LEDs by T Paris (tparis@voyager.com.au) for Delphi 5
 
    This zip file contains a cool alternative to the wonderful, brilliant, artistic 
    original LEDS provided with the DLComponents collection.
 
    Rename the original DLLED.RES file to DLLED_OLD.RES, then copy COOL_LEDS.RES into
    the directory where you have installed DLComponents and rename it to DLLED.RES.



Compiling the Demos
===================

Before you compile the demos, you must have successfully installed the DL Components.

Three separate demos are available with this release. Each is in a separate ZIP file;
it is recommended that you extract the contents of each file into a separate folder
since certain file names are duplicated.


demo1           This project demonstrates the properties of the
		TDLDateEdit component. Simply open the project in
		Delphi and select Run. The program allows you to
                change the properties and observe the results
                immediately. You will need to open the calendar
                of the TDLDateEdit control to see some of these.

demo2           This project demonstrates the properties of the
		TDLLED component. Simply open the project in
		Delphi and select Run. The program allows you to
                change the properties and observe the results
                immediately.

demo3           This project puts together the TDLDBDateEdit, TDLDBDateText,
                TDLCalendar and TDLLED components into a mock application.
                This shows one possible application of the TDLLED controls, as
                well as an example of how the TDLCalendar can be used. The 
                example also demonstrates the possibility of allowing the 
                end-user to customise the appearance of the controls 
                (in a real application you would probably store these in the 
                registry, an INI file or a table).

		If you receive an error message on opening demo3, 
		it is because the TTable components could not find the
		appropriate tables. The demo program will reset the DatabaseName 
                property of the Table at run-time, so you can safely ignore the 
                error message. If you want to experiment with the demo in
		design-time, you will need to set the Database property of
		the TTable component to the directory where you have stored
		the demo source code.

Note that if you open these projects in Delphi 2, you are likely to see
some "Property not found" messages. Click "Ignore" in response to each of
these, then save the form again. 


File List
=========


Folders
-------

dlcomponents                     Documentation
dlcomponents\delphi2             Delphi 2 version of the DL Components 
dlcomponents\delphi4             Delphi 4 version of the DL Components 
dlcomponents\delphi5             Delphi 5 version of the DL Components 
dlcomponents\delphi6             Delphi 6 version of the DL Components 
dlcomponents\demos\demo1         Demo 1 (TDLDateEdit properties)
dlcomponents\demos\demo2         Demo 2 (TDLLED properties) 
dlcomponents\demos\demo3         Demo 3 (Mock application) 
dlcomponents\help                Help files


Files
-----

Many of the files in the above directories are duplicated amongst the 
folders in order to simplify the installation. They are listed here
once for clarity:

dlde.frm            Form used by the calendar component 
dlde.res            Resource file for the Date Editing components
dlde.dcu            Compiled unit for the Date Editing components
dlled.res           Resource file for the LED component
dlled.dcu           Compiled unit for the LED component
regdl.dcu           Registration unit 

DLComponents4.bpl   DL Components package for Delphi 4
DLComponents4.dcp   DL Components package for Delphi 4
DLComponents5.bpl   DL Components package for Delphi 5
DLComponents5.dcp   DL Components package for Delphi 5
DLComponents6.bpl   DL Components package for Delphi 6
DLComponents6.dcp   DL Components package for Delphi 6

regdl.dcr           Icon file for Delphi 2 and 4

DLComponents.hlp    DL Components Help file
DLComponents.cnt    DL Components Help contents file


Note that the DCU files were each compiled with a different version of
Delphi. The FRM file is in the Delphi 4 style "binary" format to provide
compatibility between the Delphi 4, 5 and 6 versions. The FRM file for
Delphi 2 is special made for Delphi 2, and should only be used in
Delphi 2.


Source Code
===========

Source code is available for sale or licensing. Refer to order.txt for 
information and pricing.


Getting Help
============

Support for the use of these components is available on an if and when basis 
(that is, if I can actually help, Ill do it when I can squeeze time into
 my schedulelife is busy with three daughters under the age of 9!). 
Support can be obtained via Mail or Email, or from the DLComponents Web site. 
When seeking support via email, please do not send your entire Delphi project; 
a simple code-snippet should be sufficient to demonstrate the problem you have.

Mail
----

DL Components Support
13 Treherne Court 
Carrum Downs   3201
Australia

Email
-----

davidml@ozemail.com.au

Web Site
--------

www.ozemail.com.au/~davidml/dlcomp


Bugs & Typos
------------

If you discover any bugs or errors in the DL Components,
(and can replicate the bugs at will), please submit details of
the problem to the Author.

