TYearPlanner
ReadMe
By Jonathan Hosking
V2.1 (26/09/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 39KB when compiled in Delphi 1.0! (33KB 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.
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.
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 are currently
no known problems with the control.
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
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
to draw images
without stretching.
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/