TYearPlanner
ReadMe
By Jonathan Hosking
V2.21 (18/11/2000)
Table of contents
What
is the TYearPlanner component?
How to install the TYearPlanner component
TYearPlanner reference
Revision history
Future ideas
Other components
Contacting me
What
is the TYearPlanner component?
The TYearPlanner
component is a new component I have written for Delphi and C++Builder. It simply
looks like a year planner. It can be fully customised if desired. It has the
following features: -
- Individual dates
can have their own hints and custom colours.
- Multiple cells
can be selected.
- Fully customisable
source code, which can be edited if necessary.
- A popup menu
can be used with the control.
- Works on Windows
95, NT & 2000. (I have not tested it with Windows 98)
- Compact size,
only occupying 40KB when compiled in Delphi 1.0! (34KB in Delphi 5.0!)
The component code
was written by modifying some code for my TOffice97Button component. The routine
that tests for leap years is the routine used in Delphi 5.0. The code works
fine on Delphi 1.0, 2.0, 4.0, 5.0 and C++Builder 3.0 & 4.0, but I have not
tested it with other versions.
You are free to
distribute the code, but you may NOT sell it. If you modify the code, you must
include me in the acknowledgements. If you do want your ideas or modifications
to be incorporated into the latest version, send them to the address at the
end of this document.
Thanks to Simon
Nicholson for helping with the message hook to reduce flickering.
Thanks to Richard
Haven for helping with the heading setup routine.
Thanks to Wolfgang
Kleinrath for helping with the data setup routine and providing the
code for the original routines for loading and saving cell data to INI files
Thanks to Nacho
Urenda for helping with the size calculation routine.
Thanks to Rob
Schoenaker for helping with the drawing routine.
Thanks to Robert
Gesswein for adding the NoDayPriority and StartDayOfWeek
properties, and for helping with the SetColorAtDate routine.
Thanks to Paul
Fisher for adding printing support, the original routines for loading
and saving cell data to streams, and for helping out with the new cell selection
routines.
Thanks to Paolo
Prandini for removing the range check errors in the component routines.
Thanks to Max
Evans for the navigation buttons and graphical customisation improvements.
Thanks to Goldschmidt
Jean-Jacques for the selection information routines.
Thanks to Roberto
Chieregato for the cell images routines.
Thanks to Martin
Roberts for fixing a bug with cell selections.
Thanks to Kaj
Ekman for the code to draw images without stretching.
Thanks to David
Oakes for the code to control the display of default hints.
How
to install the TYearPlanner component
To unzip the TYearPlanner
component, assuming [Program Path] is the path to Delphi or C++Builder,
follow these steps: -
- Unzip the file
YEARPLAN.ZIP to any directory, using the directory switch (This is
VERY important).
- Copy the file
YEARPLAN.PAS to the directory [Program Path]\Source\Samples.
- If you want
documentation, copy the file YEARPLAN.HTM to the directory [Program
Path]\Bin, if you are using Delphi 1.0. Otherwise, copy it to the directory
[Program Path]\Help.
- If you are using
Delphi 1.0, copy the files in the 16-Bit directory of this Zip to the
directory [Program Path]\Source\Samples. Otherwise, copy the files
in the 32-Bit directory of this Zip to the directory [Program Path]\Source\Samples.
You can now install
the component into the component library. Follow the procedure for the version
of Delphi or C++Builder that you are using.
Delphi 1.0:
- Click on Options
and then select Install Components.
- In the Install
Components dialog, click Add. In the next dialog, click Browse
and open the file YEARPLAN.PAS.
- Click Ok
to install the component.
Delphi 2.0:
This procedure
should also work with C++Builder 1.0, but I'm not sure.
- Click on Component
and select Install.
- In the Install
Components dialog, click Add. In the next dialog, click Browse
and open the file YEARPLAN.PAS.
- Click Ok
to install the component.
Delphi 4.0:
- Click on Tools
and select Environment Options.
- In the next
dialog, click on the Library tab and add the full path of the TYearPlanner
source code to the Library Path edit box. Then click Ok.
- Click on Component
and select Install Component.
- In the Install
Component dialog, click on the Into existing package tab. Click
on the first Browse button and open the file YEARPLAN.PAS. Then
click on the second Browse button and open the file DCLUSR40.DPK.
Finally, click Ok to install the component.
Delphi 5.0:
- Click on Tools
and select Environment Options.
- In the next
dialog, click on the Library tab and add the full path of the TYearPlanner
source code to the Library Path edit box. Then click Ok.
- Click on Component
and select Install Component.
- In the Install
Component dialog, click on the Into existing package tab. Click
on the first Browse button and open the file YEARPLAN.PAS. Then
click on the second Browse button and open the file DCLUSR50.DPK.
Finally, click Ok to install the component.
C++Builder 3.0:
This procedure
should also work, with minor modifications, with Delphi 3.0, but I'm not sure.
- Click on Tools
and select Environment Options.
- In the next
dialog, click on the Library tab and add the full path of the TYearPlanner
source code to the Library Path edit box. Then click Ok.
- Click on Component
and select Install Component.
- In the Install
Component dialog, click on the Into existing package tab. Click
on the first Browse button and open the file YEARPLAN.PAS. Then
click on the second Browse button and open the file DCLUSR35.BPK.
Finally, click Ok to install the component.
C++Builder 4.0:
This procedure
should also work, with minor modifications, with C++Builder 5.0, but I'm not
sure.
- Click on Tools
and select Environment Options.
- In the next
dialog, click on the Library tab and add the full path of the TYearPlanner
source code to the Library Path edit box. Then click Ok.
- Click on Component
and select Install Component.
- In the Install
Component dialog, click on the Into existing package tab. Click
on the first Browse button and open the file YEARPLAN.PAS. Then
click on the second Browse button and open the file DCLUSR40.BPK.
Finally, click Ok to install the component.
TYearPlanner
reference
Remarks:
Just in case you
didn't know, here is how you get information about a cell. You get the day using
Day := CurrentDate.Day and the month by using Month := CurrentDate.Month.
The date details are then obtained with the following: -
- For the cell
hint use CellHint := CellData[Month,Day].CellHint.
- For the cell
color use CellColor := CellData[Month,Day].CellColor.
- To see if the
date is using a custom color rather than the default use CustomColor :=
CellData[Month,Day].CustomColor.
- To see if a
cell is selected look at CellData[Month,Day].Selected;
- To set the image
for a cell, assign a TImageList to the Images property. Then set CellData[Month,Day].CellImage
to the number of the image.
To get the start
and end dates in a selection, use the GetStartDate and GetEndDate
routines. Both routines return a TDateTime as the value.
To see if a date
is selected, use the IsCellSelected routine. You need to specify the
date as a TDateTime, and the return value is a boolean.
You can select
a cell manually using the SelectCells procedure, specifying two TDateTimes
as the start date and end date.
The SetColorAtDate
procedure can be used to set the cell colour of a date. You need to specify
the date, as a TDateTime, the cell colour and whether or not the control
should immediately show the change.
The SetHintAtDate
procedure can be used to set the hint of a date. You need to specify the date,
as a TDateTime, the hint and whether or not the control should immediately
show the change.
The SetImageAtDate
procedure can be used to set the cell image of a date. You need to specify the
date, as a TDateTime, the cell image and whether or not the control should
immediately show the change.
The GetCellData
function is used to retrieve cell data for a date. You specify the date as a
TDateTime, and it will return a TCellData with the cell data.
IMPORTANT: You
must use the SetColorAtDate, SetHintAtDate, SetImageAtDate
and GetCellData routines to read and set the CellData variable in C++Builder.
Do not directly access the CellData variable.
You can use the
LoadFromFile and SaveToFile procedures to load and save the cell
data to a file.
You can use the
LoadFromStream and SaveToStream procedures to load and save the
cell data to a stream.
Known problems:
There is a problem
with the control in C++Builder. Basically, due to some strange reason, you cannot
directly access the CellData variable. To read the CellData variable,
you must use the GetCellData function. To set the CellData variable,
use the SetColorAtDate, SetHintAtDate and SetImageAtDate
functions.
Key properties:
- property
Align;
Determines how the control is aligned within its parent.
- property
AllowSelections;
Determines if cells can be selected on the control.
- property
Color;
Determines the colour of the control.
- property
DayColor;
Determines the colour of the day cells.
- property
DayFont;
Determines the font that is used in the day cells.
- property
DragCursor;
Determines the mouse pointer that is displayed when an object is dragged over
the control.
- property
DragMode;
If this is set to automatic, the control can be dragged and dropped at any
time. If this is set to manual, the control can only be dragged when the BeginDrag
method is called.
- property
DrawOffScreen;
If this is set to True, the control is drawn using an off-screen bitmap.
- property
Enabled;
If this is set to False, the control cannot be used until this is set
to true.
- property
EndEllipsis;
If this is set to True, text is fitted into cells using ellipses.
- property
FlatCells;
If this is set to True, cells are drawn in a flat style.
- property
Font;
Determines the font that is used in the control.
- property
GridLines;
If this is set to True, the gridlines are drawn.
- property
GridPen;
Determines the pen that is used for drawing the gridlines.
- property
HeadingColor;
Determines the colour of the heading cells.
- property
HintColor;
Determines the colour of the hints.
- property
HintDelay;
Determines the delay time of the hints. A value of 0 uses the application
default.
- property
MonthColor;
Determines the colour of the month heading cells.
- property
MonthFont;
Determines the font that is used in the month cells.
- property
NoDayColor;
Determines the colour of the no day cells.
- property
NoDayPriority;
Determines if blank cells have the same colour.
- property
ParentFont;
If this is set to True, the control uses the font used by its parent.
- property
ParentShowHint;
If this is set to True, the parent of the control displays the hints.
- property
PopupMenu;
If this is set, right clicking the control displays the set popup menu
- property
SelectionStyle;
If this is set to ypNormal, cells are selected in a date range style.
Otherwise, cells are selected in rectangles.
- property
Seperator;
If this is set to True, seperator lines are drawn between the months.
- property
ShowDefaultHint;
If this is set to True, the default hints are displayed for cells which
don't have custom hints.
- Property
ShowHint;
If this is set to True, the control displays its own popup hints.
- property
SoftBorder;
If this is set to True, a soft border is drawn around the control.
- property
StartDayOfWeek;
Determines the day the calender week starts on.
- property
StretchImages;
If this is set to True, cell images are stretched.
- property
UseFreeSpace;
If this is set to True, the control occupies any unused canvas space.
- property
Visible;
If this is set to False, the control cannot be seen.
- property
WeekendColor;
Determines the colour of the weekend cells.
- property
WeekendHeadingColor;
Determines the colour of the weekend heading cells.
- property
Year;
Determines the year to display.
- property
YearColor;
Determines the colour of the year cells.
- property
YearFont;
Determines the font that is used in the year cell.
- property
YearNavigators;
If this is set to True, the year arrows are displayed in the year cell,
allowing the user to navigate forwards or backwards.
Key events:
- property
OnClick: TNotifyEvent;
Occurs when the control is selected.
- property
OnDblClick: TYearEvent;
Occurs when the control is double-clicked.
- property
OnDragDrop: TNotifyEvent;
Occurs when an object being dragged is dropped.
- property
OnDragOver: TNotifyEvent;
Occurs when an object is dragged over the control.
- property
OnEndDrag: TNotifyEvent;
Occurs whenever the dragging of an object ends, either by dropping the object
or by cancelling the dragging.
- property
OnMouseDown: TNotifyEvent;
Occurs when a mouse button is pressed with the pointer over the control.
- property
OnMouseMove: TNotifyEvent;
Occurs when the pointer is moved whilst over the control.
- property
OnMouseUp: TNotifyEvent;
Occurs when a mouse button that was pressed is released with the pointer over
the control.
- property
OnMouseUp: TNotifyEvent;
Occurs when a mouse button that was pressed is released with the pointer over
the control.
- property
OnYearChange: TYearEvent;
Occurs when the year changes.
Runtime properties:
- CellData;
This contains the information about the dates. Set CellHint to give
the date a hint. Set CellColor to set the cell colour, and set CustomColor
to use the specified colour. The array is reset when the year changes, and
changes do not automatically update the control. The Selected variable
indicates if a cell has been selected. Set the CellImage property to
set the cell image.
- CurrentDate;
This contains the current date. Day is the day and Month is
the month, quite simply.
Revision
history
V2.21 (18/11/2000)
- Bug Fixed -
Sometimes the selection routines caused an EConvertError error.
V2.2 (04/11/2000)
- Added a new
ShowDefaultHint property, allowing the user to determine whether the
default hints are shown for cells without custom hints. Thanks to David
Oakes for providing the code.
V2.13 (18/10/2000)
- Bug Fixed -
When the control was printed, images and soft borders were incorrectly sized.
V2.12 (17/10/2000)
- Bug Fixed -
When you destroyed the control, it occasionally didn't destroy itself until
any hints had finished displaying.
V2.11 (07/10/2000)
- Bug Fixed -
If you directly accessed the CellData variable in C++Builder, access
violations were generated. To fix this, I added new GetCellData, SetHintAtDate
and SetImageAtDate routines, allowing the user to read and set the
CellData variable.
V2.1 (26/09/2000)
- Added a new
StretchImages property, allowing the user to determine whether cell
images are stretched or not. Thanks to Kaj
Ekman for providing the code.
V2.01 (23/07/2000)
- Bug Fixed -
The cell selection routines sometimes picked up the wrong cells. Thanks to
Martin Roberts for
fixing this bug.
V2.0 (18/06/2000)
- Added a new
Images property, allowing individual cells to be assigned images. Thanks
to Roberto Chieregato for providing
the code.
V1.9 (14/06/2000)
- Added a new
AllowSelection property, which determines whether cells can be selected.
- Added a new
SelectionStyle property, allowing the user to determine how cells are
selected. Cells can either be selected in date ranges or rectangles.
V1.8 (11/03/2000)
- Renamed the
SelectCell procedure to SelectCells, as it now allows the user
to manually select a range of cells.
- Completely rewrote
the LoadFromStream and SaveToStream procedures so that they
now read and write all of the cell data.
- Added LoadFromFile
and SaveToFile procedures, allowing the user to store the cell data
in files.
V1.75 (07/03/2000)
- Added a new
SelectCell procedure which allows the user to manually select a cell.
V1.74 (22/02/2000)
- Added a new
OnYearChange event procedure which occurs when the year changes.
V1.73 (19/02/2000)
- Bug Fixed -
When multiple TYearPlanners were used on a form, they were sharing the same
hint windows and some other internal variables.
V1.72 (12/02/2000)
V1.71 (06/02/2000)
- Bug Fixed -
The mouse procedures now respond properly. In previous versions, the mouse
procedures weren't called sometimes.
V1.7 (25/01/2000)
- Bug Fixed -
The control now uses the correct colour to draw gridlines.
- Added DayFont,
MonthFont and YearFont properties which allow the user to control
the font used in day cells, month cells and the year cell. Thanks to Max
Evans for providing the code.
- Added an EndEllipsis
property, allowing the text to fit into cells using ellipses. Thanks to Max
Evans for providing the code.
- Added a FlatCells
property which allows the cells to be flat. Thanks to Max
Evans for providing the code.
- Added a GridPen
property, allowing the user to change the pen used for the gridlines. As a
result, the GridLineColor property has been removed. Thanks to Max
Evans for providing the code.
- Added a GridLines
property which toggles the display of gridlines. Thanks to Max
Evans for providing the code.
- Added a Separator
property, allowing a simple separator between the months. Thanks to Max
Evans for providing the code.
- Added a SoftBorder
property, which allows the control to have a soft style border. Thanks to
Max Evans for
providing the code.
- Added a YearColor
property, allowing the user to change the colour of the year cell. Thanks
to Max Evans for
providing the code.
- Added a YearNavigators
property which toggles the display of the year arrows in the year cell to
allow navigation forward or backward. Thanks to Max
Evans for providing the code.
V1.63 (22/01/2000)
- Bug Fixed -
Fixed the irritating problem with the tagSize data type in 32-Bit compilation.
A tSize data type is now used instead, and this seems to work perfectly.
- The OnDblClick
procedure now returns the coordinates of a selected range of cells.
V1.62 (08/12/1999)
- Bug Fixed -
Some of the routines caused errors if range checking was enabled. Thanks to
Paolo Prandini for correcting
the routines.
- Bug Fixed -
The component was using a tagSize data type for 32-Bit compilation.
It seems that Delphi 2.0 and C++Builder 1.0 do not have this data type.
V1.61 (22/11/1999)
- Bug Fixed –
In V1.6, I accidentally disabled the OnClick event procedure.
- The user can
now choose whether to use a TStream or TBlobStream for loading
and saving cell data.
V1.6 (21/11/1999)
- Added a Print
procedure, allowing the control to print itself. Thanks to Paul
Fisher for providing the code.
- The user can
now select multiple cells in the control. Thanks to Paul
Fisher for helping with this.
- Added an OnMouseRightClick
event, allowing the control to handle right clicks on a selection. Thanks
to Paul Fisher
for helping with this.
- Added a SelectionColor
property, allowing the selection colour to be changed.
- Replaced the
LoadFromFile and SaveToFile routines with new LoadFromStream
and SaveToStream routines. These now save the cell hints to a stream.
Thanks to Paul Fisher
for providing the code.
V1.57 (01/11/1999)
- Bug Fixed –
If a hint was not being displayed when the control was destroyed, the program
crashed.
V1.56 (23/10/1999)
- Bug Fixed –
If a hint was being displayed when the control was destroyed, an error was
generated.
V1.55 (02/10/1999)
- Added a NoDayPriority
property, allowing the user to select whether blank cells have the same
colour. Thanks to Robert Gesswein
for providing this.
- Added a StartDayOfWeek
property, allowing the user to select the day that appears at the left of
the component. Thanks to Robert Gesswein
for providing this.
- Added a SetColorAtDate
routine, allowing the user to select a cell colour for a date. Thanks to Robert
Gesswein for helping with this.
V1.54 (29/09/1999)
- The component
is now much faster at painting itself. Thanks to Rob
Schoenaker for helping with the drawing routine.
- Added a DrawOffScreen
property, allowing the control to be drawn using an off-screen bitmap.
- Added a HintColor
property, allowing the user to change the colour of hints.
- Added a MonthColor
property, allowing the user to change the colour of the month headings.
V1.53 (20/09/1999)
- The component
is now descended from TCustomControl rather than TGraphicControl
as this apparently reduces flickering.
V1.52 (13/09/1999)
- Bug Fixed -
The control now correctly identifies leap years.
V1.51 (11/09/1999)
- Added a new
UseFreeSpace property, allowing the control to make use of any unused
canvas space. Thanks to Nacho
Urenda for helping with the size calculation routine.
- Added comments
to the routines for loading and saving the cell data. Thanks to Wolfgang
Kleinrath for providing the comments.
V1.5 (07/09/1999)
- You can now
load and save the cell data to files. Thanks to Wolfgang
Kleinrath for providing the code for the routines. A new IniFileName
property has been added so you can set the filename.
- New HintDelay
property added, allowing you to adjust the hint delay.
- The hint string
restriction has been removed, except in Delphi 1.0.
V1.4 (04/09/1999)
- Bug Fixed –
The top left cell now updates when the year changes.
- The cX
and cY variables are no longer public, as I have added a new CurrentDate
property which stores the current date.
- Multiple line
cell hints are supported! Just add return characters to the hint string where
needed.
- Delphi 5.0 is
now supported!
V1.3 (29/08/1999)
- The cX
and cY variables are now public, allowing the user to get the co-ordinates
of the cell that the mouse is currently over.
- The routine
for the cell headings setup has been improved. Thanks to Richard
Haven for helping with this.
V1.2 (21/08/1999)
- A new CellData
runtime property has been added. This now allows individual dates to have
their own hints and custom colours.
V1.12 (17/08/1999)
- Added a message
hook to help reduce flickering. Thanks to Simon
Nicholson for his help with this.
V1.11 (12/08/1999)
- Bug Fixed –
The control now correctly recognises C++Builder 4.0.
- Updated the
drawing routines to reduce flicker on the control.
V1.1 (25/05/1999)
- C++Builder 3.0
is now supported.
V1.0 (26/07/1998)
Future
ideas
I currently only
have no ideas for future versions of the TYearPlanner component.
Other
components
Below is a list
other components that I have written: -
- TLCD99 – A control
that looks like an LCD display.
- TOffice97Balloon
– A control that looks and acts like the Office Assistant balloons in Office
97.
- TOffice97Button
– A control that looks and acts like the controls (Buttons, radiobuttons,
up buttons and down buttons) that appear in the Office Assistant balloons
in Office 97.
Contacting
me
I am currently
on the Internet. If you have any bug reports, comments, ideas, modifications,
etc. then you can Email me at the address given below. You can also go to my
web site to find out the latest information on my components.
Email: jonathan@the-hoskings.freeserve.co.uk
WWW: http://www.the-hoskings.freeserve.co.uk/