Introduction

I decided to write this control because I needed a month calendar that's much more
customizable and flexible than the standard Visual Studio Calendar, in one of my projects.
My primary focus was the ability to add information (color, text, image etc.) to each day,
and for this to work reasonably well, it must also be resizable.

This is my second article for CodeProject, and it shares some of the implementation
techniques of the previous article, so if you want some detail on the implementation of
themes, nested properties, and TypeEditors, check out my MozBar article. For information
about how to edit and persist collections, check out Daniel Zaharia's excellent article.

Using the control

Like any other .NET control, for using in the IDE, you should add the MonthCalendar
control to the Toolbox panel. This can be accomplished by right-clicking on a Toolbox tab
and selecting "Add/Remove items...", browsing to the MonthCalendar assembly, and
selecting it. This will add the MonthCalendar control to the Toolbox so that it can be
dragged/dropped to a Windows Form.

Once an instance of MonthCalendar is added to the form, select it and view its properties.

Layout and design

The basic design for the control is pretty much like the standard Visual Studio Calendar,
but it is a lot more flexible. To make it more portable and to reduce the overhead,
everything is drawn directly with GDI. MonthCalendar basically consists of five different
regions, each with its own set of properties.
The only region that must be visible is the month region, all the others can be switched
on or off.

Properties

The following properties control the most significant behavior and the look and feel of the
MonthCalendar control:

 BorderColor: Color used for the border.

 BorderStyle: The style used for the border.
 ShowFooter: Indicates whether the footer should be visible (default=true).
 ShowHeader: Indicates whether the header should be visible (default=true).
 ShowWeekdays: Indicates whether weekdays should be visible (default=true).
 ShowWeeknumbers: Indicates whether week numbers should be visible
(default=false).
 TodayColor: The color used for the circle that marks today's date.
 ActiveMonth: The month currently shown in the calendar.
 Culture: The culture used for the calendar.
 Dates: A collection of formatted dates.
 ImageList: The ImageList used to hold images for the calendar, this must be set
if you want to assign images to dates.
 MaxDate: The maximum date that can be selected.
 MinDate: The minimum date that can be selected.
 SelectedDates: Collection of selected dates.
 SelectionMode: Indicates the selection mode used in the calendar (None, One,
MultiSimple, or MultiExtended).
 ExtendedSelectionKey: The key used for the extended selection mode.
 FirstDayOfWeek: Sets the first day of week for the current culture.
 SelectButton: The mouse button used for selections.
 SelectTrailingDates: Indicates whether selecting trailing dates is possible
(default=true).
 ShowFocus: Toggles hot tracking when moving the mouse over a date
(default=true).
  ShowToday: Indicates if today's date should be marked, the color used for the mark
is the one assigned to TodayColor (default=true).
 ShowTrailingDates: Indicates whether trailing dates should be visible or not
(default=true).
 Theme: Indicates whether the calendar should use theme colors (default=false).
 KeyboardEnabled: Indicates whether keyboard support is enabled (default=true).
 Keyboard: Collection of keys used for keyboard control.
 Version: Returns the version number.

Month
 BackgroundImage: Image used as background.
 Transparency: Text and background transparency (used when painting colors).
 FormatTrailing: Indicates whether formatting should be shown for trailing dates
(default=true).
 Padding: Vertical and horizontal spacing.
 DateAlign: Date alignment within a day.
 ShowMonthInDay: Indicates whether the first and the last day of a month should
have the month displayed in the date (default=false).
 TextAlign: Text alignment within a day.
 EnableImageClick: Enables the ImageClick event (default=false).
 ImageAlign: Image alignment within a day.
 DateFont: Font used for the date.
 TextFont: Font used for the text.
 Colors: Collection of colors used in the calendar.
 BorderStyles: Collection of border styles used in the calendar.

Header
 Align: Alignment of the month/text in the header.
 MonthSelectors: Indicates whether the next/previous month button should be
visible (default=true).
 YearSelectors: Indicates whether the next/previous year button should be visible
(default=false).
 ShowMonth: Indicates if the month name should be visible in the header (default =
true).
 Text: The text to be displayed in the header (if ShowMonth is false).
 BackColor1: The color used for the header background.
 BackColor2: The second color used for background when using a gradient.
 GradientMode: Type of gradient used.
 Font: The font used for the month/text.
 TextColor: The color used for the month/text.
 MonthContextMenu: Indicates whether a month selection menu should be
displayed while right-clicking the header (default = true).

Footer
 Align: The text alignment for the footer.
 Text: The text to be displayed in the footer, if ShowToday is false.
 ShowToday: Indicates whether today's date should be displayed in the footer
(default=true).
 Format: The format used for today's date.
 BackColor1: The color used for the header background.
 BackColor2: The second color used for background when using a gradient.
 GradientMode: Type of gradient used.
 Font: The font used for the date/text.
 TextColor: The color used for the date/text.

Weekdays
  BorderColor: The color used for the border.
 BackColor1: The color used for the header background.
 BackColor2: The second color used for background when using a gradient.
 GradientMode: Type of gradient used.
 Font: The font used for weekdays.
 TextColor: The color used for weekdays.
 Format: The format used to display weekdays.
 Align: Text alignment for weekdays.

Weeknumbers
 BorderColor: The color used for the border.
 BackColor1: The color used for the header background.
 BackColor2: The second color used for background when using a gradient.
 GradientMode: Type of gradient used.
 Font: The font used for week numbers.
 TextColor: The text color used for week numbers.
 Align: Text alignment for week numbers.

Events

The most useful events are:

Month
 MonthChanged: Indicates that the active month was changed.
 BeforeMonthChanged: Raised before a month is displayed. Use this event to
prevent the selection of certain months.
 DayDragDrop: Indicates that data was dropped on a day, AllowDrop must be true
for this event to be raised.
 ImageClick: Indicates that an image was clicked.
 DayClick: Indicates that a day was clicked.
 DayRender: Occurs before a date is updated.
 DayQueryInfo: Occurs before a date is updated.
 DayDoubleClick: Indicates that a day was double clicked.
 DaySelected: Indicates that one or more days were selected.
 BeforeDaySelected: Raised before a day is selected. Use this event to prevent
selection of days.
 DayDeselected: Indicates that one or more days were deselected.
 BeforeDayDeselected: Raised before a day is deselected. Use this event to
prevent deselection of days.
 DayGotFocus: Indicates that a day received focus.
 DayLostFocus: Indicates that a day lost focus.
 DayMouseMove: Indicates that the mouse is moved inside a day.

Header
 HeaderClick: Indicates that the header was clicked.
 HeaderDoubleClick: Indicates that the header was double clicked.
 HeaderMouseEnter: Indicates that the mouse entered the header region.
 HeaderMouseLeave: Indicates that the mouse left the header region.

Footer
 FooterClick: Indicates that the footer was clicked.
 FooterDoubleClick: Indicates that the footer was double clicked.
 FooterMouseEnter: Indicates that the mouse entered the footer region.
 FooterMouseLeave: Indicates that the mouse left the footer region.
Weekday
 WeekdayClick: Indicates that a weekday was clicked.
 WeekdayDoubleClick: Indicates that a weekday was double clicked.
 WeekdayMouseEnter: Indicates that the mouse entered the weekday region.
 WeekdayMouseLeave: Indicates that the mouse left the weekday region.

Weeknumber
 WeeknumberClick: Indicates that a week was clicked.
 WeeknumberDoubleClick: Indicates that a week was double clicked.
 WeeknumberMouseEnter: Indicates that the mouse entered the week number
region.
 WeeknumberMouseLeave: Indicates that the mouse left the week number region.

As usual, when using events, the supplied eventArgs parameter contains the properties
useful for that particular event.

Methods

The following methods are supported:

Date formatting
 void AddDateInfo(DateItem[] info): Adds an array of formatted dates.
 void RemoveDateInfo(DateTime dt): Removes the DateItem associated with the
supplied date.
 void RemoveDateInfo(DateItem item): Removes the supplied DateItem.
 void AddDateInfo(DateItem info): Adds a formatted date.
 void ResetDateInfo(): Removes all date formatting.
 DateItem[] GetDateInfo(): Returns all the formatted dates.
 DateItem[] GetDateInfo(DateTime dt): Returns an array of DateItems
matching the supplied date.

Selection
 void SelectDate(DateTime d): Selects the supplied date. The date must be
between MinDate and MaxDate.
 void ClearSelection(): Clears the existing selection.
 bool IsSelected(DateTime dt): Returns true if the supplied date is selected,
otherwise false.
 void SelectArea(DateItem topleft, DateItem bottomright): Selects the
area described by the two dates.
 void DeselectArea(DateItem topleft, DateItem bottomright): Deselects the
area described by the two dates.
 void SelectRange(DateItem from, DateItem to): Selects the range described
by the two dates.
 void DeselectRange(DateItem from, DateItem to): Deselects the range
described by the two dates.
 void SelectWeek(int week): Selects every day in the supplied week.
 void DeselectWeek(int week): Deselects every selected day in the supplied
week.
 void SelectWeekday(DayOfWeek day): Selects every DayOfWeek in the current
month.
 void DeselectWeekday(DayOfWeek day): Deselects every selected DayOfWeek in
the current month.

Misc.
 void Print(): Prints the current calendar on the default printer.
  Bitmap Snapshot(): Returns a bitmap of the current calendar.
 void SaveAsImage(string filename, ImageFormat format): Saves the
calendar to a file.
 void Copy(): Copies the calendar to the clipboard.

Adding date formatting

You can add formatted dates either during runtime by using one of the DateInfo
methods, or in design mode by using the built-in DateItemCollection.

Adding date formatting in design mode is, of course, not very practical for real
applications, your info will most likely be stored in some kind of database, so the best
way to add date formatting is to respond to the MonthChanged event and add the dates
during runtime:

private void monthCalendar1_MonthChanged(object sender,

Pabo.Calendar.MonthChangedEventArgs e)
{
AddInfo(e.Year,e.Month);
}

To add formatted dates during runtime, you need to create DateItem objects. A DateItem
has several properties that define the appearance of the date:

 Date: The date for which the info applies.

 BackgroundImage: The image used as background.
 BackColor1: The color used for background.
 BackColor2: The second color used for background when using a gradient.
 GradientMode: Type of gradient used.
 Weekend: Indicates whether the date should be handled as a weekend (default =
false).
 DateColor: Color used for the date.
 TextColor: Color used for the text.
 ImageListIndex: Index for the image to be displayed in the date. For this to work,
an ImageList must be assigned to the MonthCalendar.
 Image: Image to be displayed in the date. If this property is set, it will override the
ImageList.
 BoldedDate: Indicates if the date should use a bold font (default = false).
 Enabled: Indicates whether the date is enabled or not. A date that is disabled is
not selectable, and will be drawn using the disabled colors. Any image will be
drawn in a disabled state (default = true).
 Pattern: Describes the recurring pattern used for this DateItem (default = None).
 Range: Describes the maximum range (end date) for the recurring pattern.

Creating and adding DateItems could look something like this:

private void FormatDates()

{
 DateItem[] d = new DateItem[5];
d.Initialize();
for (int i = 0;i<5;i++)
d[i] = new DateItem();

d[0].Date = new DateTime(2005,6,3);

d[0].BackColor1 = Color.Red;
d[0].ImageListIndex = 3;
d[0].Text = "Help";
d[1].Date = new DateTime(2005,6,12);
d[1].ImageListIndex = 2;
d[2].Date = new DateTime(2005,6,16);
d[2].BackColor1 = Color.LightBlue;
d[2].ImageListIndex = 8;
d[3].Date = new DateTime(2005,6,18);
d[3].BackColor1 = Color.GreenYellow;
d[3].ImageListIndex = 1;
d[3].Text = "NorDev";
d[4].Date = new DateTime(2005,6,22);
d[4].ImageListIndex = 1;
d[4].Text = "Cebit";

monthCalendar1.AddDateInfo(d);
}

If you don't want to add a lot of DateItems at once, you can use the DayQueryInfo event
and add formatting depending on the date. The DayQueryInfo event is raised before
each date is rendered, and makes it possible to supply date formatting using the
DateItem properties.

private void monthCalendar1_DayQueryInfo(object sender,

DayQueryInfoEventArgs e)
{
// Check date
if (e.Date.DayOfWeek == DayOfWeek.Thursday)
{
// Add custom formatting
e.Info.BackColor1 = Color.Yellow;
e.Info.BackColor2 = Color.GhostWhite;
e.Info.ImageListIndex = 3;
e.Info.GradientMode = mcGradientMode.Horizontal;
// Set ownerdraw = true to add custom formatting
e.OwnerDraw = true;
}
}

Note that you must set OwnerDraw=true to add formatting, and the formatting added by
this event is overridden by the DayRender event if that is used.

Recurring dates

MonthCalendar supports basic recurring date formatting. This functionality is controlled

by the Pattern and Range properties.

The following patterns can be applied to a DateItem:

 None: No recurring pattern is applied (default), the formatting is only valid for the
day specified by the Date property.
 Daily: The formatting will be applied to every day within the Range.
 Weekly: The formatting will be applied to every same weekday within the Range.
 Monthly: The formatting will be applied to the same day each month within the
Range.
  Yearly: The formatting will be applied to the same day every year within the
Range.

Note that there is no "collision detection", so overlapping patterns will be drawn on top of
each other. You can use functions like GetDateInfo to check which DateItems are
applied to a certain date. The Range and Pattern properties do not have any impact
when set through the DayQueryInfo event.

Owner-drawn dates

If the built-in formatting doesn't give you the appearance you want, then you can provide
your own by using the DayRender event. The DayRender event is raised before each date
in the calendar is painted. You can control the contents and formatting of a date by
providing code in the event handler for the DayRender event. To make the date owner-
drawn, set DayRenderEventArs.OwnerDraw=true:

Collapse
private void monthCalendar1_DayRender(object sender,
Pabo.Calendar.DayRenderEventArgs e)
{
Brush bgBrush = new SolidBrush(Color.White);
Brush dateBrush = new SolidBrush(Color.Black);
Font dateFont = new Font("Microsoft Sans Serif",(float)8.25);
StringFormat dateAlign = new StringFormat();

dateAlign.Alignment = StringAlignment.Far;
dateAlign.LineAlignment = StringAlignment.Near;

Rectangle rect = new Rectangle(0,0,e.Width,e.Height);

// Set OwnerDraw = true to override built in formatting...

e.OwnerDraw = true;
// ...then Draw the appearance of the date
e.Graphics.FillRectangle(bgBrush,rect);
e.Graphics.DrawString(e.Date.Day.ToString(),
dateFont,dateBrush,rect,dateAlign);

// Clean up
bgBrush.Dispose();
dateBrush.Dispose();
dateAlign.Dispose();
dateFont.Dispose();
}

Note that using the DayRender event to draw the appearance of a date completely
overrides all other formatting done by the control for the specific date.

Multi-select ala Excel

One thing I wanted to add to the control was multi-select. The problem with this is that
when selected days have different colors for border and background, then it doesn't look
very nice drawing all the selected days individually, and drawing the days as selected will
also cover the previous backcolor; so what you have to do is draw the entire selected
area with one transparent background and one border ala Excel. So, how can we do this?
It's pretty simple. The month region basically consists of an array of days, each with its
own rectangle, so what we need is the start and the end day for the selection so that we
can construct our "selection" rectangle. When the user clicks on a day, we set the start
day (m_selStart). And when the mouse is pressed and moved over a new day (that can
be selected), we set the end day (m_selEnd). When drawing the selection, we only need
to get the coordinates for the selection area and draw it with the desired transparent
color.

Collapse
// Check if an selection exist
if (m_selectedDays.Length>0)
{
Brush selBrush = new SolidBrush(Color.FromArgb(125,
Colors.SelectedBackground));

// Get Coordinates for selection rectangle

m_selRight = System.Math.Max(m_days[m_selStop].Rectangle.Right,
m_days[m_selStart].Rectangle.Right);
m_selLeft = System.Math.Min(m_days[m_selStop].Rectangle.Left,
m_days[m_selStart].Rectangle.Left);
m_selTop = System.Math.Min(m_days[m_selStop].Rectangle.Top,
m_days[m_selStart].Rectangle.Top);
m_selBottom = System.Math.Max(m_days[m_selStop].Rectangle.Bottom,
m_days[m_selStart].Rectangle.Bottom);

// Draw selection
Rectangle selRect = new Rectangle(m_selLeft,m_selTop,
m_selRight-m_selLeft,m_selBottom-m_selTop);
e.FillRectangle(selBrush,selRect);
ControlPaint.DrawBorder(e,selRect,Colors.SelectedBorder,
BorderStyles.Selected);
selBrush.Dispose();
}

Easy indeed, but I think it adds a nice touch to the control.

Different selection modes

MonthCalendar supports the following selection modes indicated by the SelectionMode

property:

 None: No selection is possible.

 One: Only one date can be selected at a time.
 MultiSimple: A continuous block of dates can be selected.
 MultiExtended: Same as MultiSimple, but pressing a key enables
selection/deselection of discontinuous dates. You can set the key used, with the
ExtendedSelectionKey property.

When selecting/deselecting dates in code, make sure that the appropriate

SelectionMode is set; when deselecting more than one date, it must be set to
MultiExtended, and when selecting more than one date, at least MultiSimple is
required.

Retrieving selected/deselected days

When selecting/deselecting dates, the DaySelected and DayDeselected events are

raised. To retrieve the days, you can either use the information contained in the
DaySelectedEventArgs, or use the SelectedDates collection. Getting the dates selected
by the user could look something like this:

private void monthCalendar1_DaySelected(object sender,

Pabo.Calendar.DaySelectedEventArgs e)
{
// Using the days from the EventArgs
string[] m_daysSelected = e.Days;

// Using SelectedDates
SelectedDatesCollection m_dates = monthCalendar1.SelectedDates;
}

Dynamically created dropdown in PropertyGrid

Sometimes, you want to provide the user with a list of possible choices for a property.
One way to do this is to use enumerations which automatically provide you with a
dropdown with the possible choices. But this solution is static, the list will always have the
same content. What if you want the choices to change depending on other choices the
user makes?

The solution is to create a custom TypeConverter and override some functions that will
let us supply our own values through the StandardValuesCollection.

GetStandardValuesSupported decides if standard values are supported. Returning true

means it's supported:

public override bool GetStandardValuesSupported(

ITypeDescriptorContext context)
{
// return true to allow standard values.
return true;
}
GetStandardValuesExclusive decides if the user should be allowed to type values or
not. Returning false means typing is allowed:

public override bool GetStandardValuesExclusive(

ITypeDescriptorContext context)
{
// Allow user to enter values with keyboard
return false;
}

Now, all we have to do is override GetStandardValuesCollection and return the list that
we want to use:

public override System.ComponentModel.TypeConverter.StandardValuesCollection

GetStandardValues(ITypeDescriptorContext context)
{
activeMonth m = (activeMonth)context.Instance;
return new StandardValuesCollection(m.Calendar.AllowedYears());
}

You will also need to override OnConvertFrom and OnConvertTo to validate the input, and
if you don't inherit from StringConverter, you must override CanConvertFrom and
CanConvertTo as well.

Week number

Calculating week number is somewhat problematic since different countries in the world
have different rules associated with their calendars. In most parts of Europe, we calculate
week number according to the ISO8601 calendar, which means we use the
FirstFourDayWeek rule and Monday as the first day of the week. Using these settings and
the Swedish culture with the GetWeekOfYear function found in
System.Globalization.Calendar doesn't always give you the correct week (according
to ISO8601), so it seems there are bugs in the .NET week calculation routines.

Looking around, I found a webpage that describes this problem in more detail, and even
better, provides a function that works:

Collapse
private int GetISO8601WeekNumber(DateTime date)
{
// Calculates the ISO 8601 Weeknumber
// In this scenario the first day of the week is monday,
// and the week rule states that:
// [...] the first calendar week of a year is the one
// that includes the first Thursday of that year and
// [...] the last calendar week of a calendar year is
// the week immediately preceding the first
// calendar week of the next year.
// The first week of the year may thus start in the
// preceding year

const int JAN = 1;

const int DEC = 12;
const int LASTDAYOFDEC = 31;
const int FIRSTDAYOFJAN = 1;
const int THURSDAY = 4;
bool Week53Flag = false;

// Get the day number since the beginning of the year

int DayOfYear = date.DayOfYear;

// Get the numeric weekday of the first day of the

 // year (using sunday as FirstDay)
int StartWeekDayOfYear =
(int)(new DateTime(date.Year, JAN, FIRSTDAYOFJAN)).DayOfWeek;
int EndWeekDayOfYear =
(int)(new DateTime(date.Year, DEC, LASTDAYOFDEC)).DayOfWeek;

// Compensate for the fact that we are using monday

// as the first day of the week

if (m_calendar.m_dateTimeFormat.FirstDayOfWeek!=0)
{
//if( StartWeekDayOfYear == 0)
StartWeekDayOfYear = 8 - StartWeekDayOfYear;
//if( EndWeekDayOfYear == 0)
EndWeekDayOfYear = 8 - EndWeekDayOfYear;
}

// Calculate the number of days in the first and last week

int DaysInFirstWeek = 8 - (StartWeekDayOfYear );
int DaysInLastWeek = 8 - (EndWeekDayOfYear );

// If the year either starts or ends on a

// thursday it will have a 53rd week
if (StartWeekDayOfYear == THURSDAY ||
EndWeekDayOfYear == THURSDAY)
Week53Flag = true;

// We begin by calculating the number of FULL

// weeks between the start of the year and
// our date. The number is rounded up, so the
// smallest possible value is 0.
int FullWeeks =
(int) Math.Ceiling((DayOfYear - (DaysInFirstWeek))/7.0);

int WeekNumber = FullWeeks;

// If the first week of the year has at least four days,

// then the actual week number for our date
// can be incremented by one.

if (DaysInFirstWeek >= THURSDAY)

WeekNumber = WeekNumber +1;

// If week number is larger than week 52 (and the year

// doesn't either start or end on a thursday)
// then the correct week number is 1.
if (WeekNumber > 52 && !Week53Flag)
WeekNumber = 1;

// If week number is still 0, it means that we are trying

// to evaluate the week number for a
// week that belongs in the previous year (since that week
// has 3 days or less in our date's year).
// We therefore make a recursive call using the last day of
// the previous year.
if (WeekNumber == 0)
WeekNumber = GetISO8601WeekNumber(
new DateTime(date.Year-1, DEC, LASTDAYOFDEC));
return WeekNumber;
}

If you use the ISO8601 calendar (most of Europe), MonthCalendar will give you a correct
week, if not, you will get the Microsoft week that might be right or wrong depending on
your culture setting.

Using a callback to calculate week number

If you don't get the correct week, all hope is not lost, you can override the calendar's
standard week routines and supply your own callback function that calculates the week
numbers through the WeeknumberCallback property. The callback function must take a
DateTime as the only parameter, and return an integer:

public int GetWeek(DateTime dt)

{
// Calculate weeknumber here
}

If the above function is our callback, setting it up could look something like this:

private void Form1_Load(object sender, System.EventArgs e)

{
monthCalendar1.WeeknumberCallBack =
new WeekCallBack(this.GetWeek);
}

Known problems/issues

 Since this control uses an ImageList, it suffers from the infamous ImageList bug
that destroys the alpha channel for 32 bit images when you add images to the
ImageList in design mode. Workarounds for this could be to replace the
ImageList with a control like the ImageSet by Tom Guinter (that is available
here), or to add the images at run time. This is, hopefully, fixed in Visual Studio
2005 so it might not be worth the hassle.

Conclusion

I hope this control can be of use to you. I'm sure there is plenty of room for improvements
and added functionality, so if you have any ideas or suggestions, please post a comment.