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: -

1. Unzip the file YEARPLAN.ZIP to any directory, using the directory switch (This is VERY important).
2. Copy the file YEARPLAN.PAS to the directory [Program Path]\Source\Samples.
3. 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.
4. 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:

1. Click on Options and then select Install Components.
2. In the Install Components dialog, click Add. In the next dialog, click Browse and open the file YEARPLAN.PAS.
3. Click Ok to install the component.

Delphi 2.0:

This procedure should also work with C++Builder 1.0, but I'm not sure.

1. Click on Component and select Install.
2. In the Install Components dialog, click Add. In the next dialog, click Browse and open the file YEARPLAN.PAS.
3. Click Ok to install the component.

Delphi 4.0:

1. Click on Tools and select Environment Options.
2. 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.
3. Click on Component and select Install Component.
4. 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:

1. Click on Tools and select Environment Options.
2. 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.
3. Click on Component and select Install Component.
4. 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.

1. Click on Tools and select Environment Options.
2. 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.
3. Click on Component and select Install Component.
4. 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.

1. Click on Tools and select Environment Options.
2. 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.
3. Click on Component and select Install Component.
4. 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)

• Added some selection information routines to the component. Thanks to Goldschmidt Jean-Jacques for providing the code.

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)

• Initial release.

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/