BinaryDatePicker

Initialises a date picker showing today's date in the long date format, with the right-click menu and an always-visible border.

Gets or sets the background of the text box.

The calendar has its own background; see CalendarMonthBackColor.

Gets or sets the culture the date is written, read and shown in – month and day names, the long and short date formats.

Set it to show dates in a culture other than the user's – new CultureInfo("fr-FR") for a French form on an English system. The calendar and the dates in CustomDateXMLFeed follow it too.

Gets or sets the colour of the text box's border.

A value set while EditControlStyleIsExtended is false is ignored.

Gets or sets the colour of the day numbers, the day names and the legend text in the calendar.

Gets or sets the colour of the days of the previous and next months that fill the calendar's first and last rows.

Gets or sets whether the calendar shows a legend under the days, explaining the Today and Selection circles.

The legend is drawn only while MarkSelectedDate is also set; without it the calendar is shorter.

Gets or sets the colour of the two small arrows at the ends of the calendar's title, which move to the previous and next month.

Holding an arrow down keeps moving. Clicking the title itself opens a list of months.

Gets or sets the background of the calendar.

Gets or sets the colour of the month and year in the calendar's title.

Gets or sets the colour of the arrow on the glass drop-down button.

Gets or sets the dark colour of the glass drop-down button, also used for its outline.

Gets or sets the light colour of the glass drop-down button.

Used while UseDropDownImageStyle is DropDownImageStyle.GlassRendering.

Gets or sets the background colour of the calendar's Close button.

Takes effect the next time the calendar opens.

Gets or sets how the calendar's Close button is drawn: flat, popup, standard or by the system.

Use FlatStyle.Flat or FlatStyle.Popup for the button colours to show in full.

Gets or sets the colour of the text on the calendar's Close button.

Gets or sets the caption of the calendar's Close button, which closes the calendar without changing the date.

The button is 47 by 20 logical pixels, so keep a translation short.

Gets or sets the path of an XML file of named dates the user can type, and of dates to pick out in the calendar.

Each DateLookup gives a name the user can type – matched exactly, case included – and its date; names are used only while EnableCustomDateXMLFeed is set. Each Date under HighlightDates becomes one of the SpecialDates as soon as the path is set. Dates are read in BinaryCultureInfo.

<?xml version="1.0" encoding="utf-8" ?>
<CustomDates>
  <DateLookup>
    <DateName>Year end</DateName>
    <DateValue>31/03/2027</DateValue>
  </DateLookup>
  <DateLookup>
    <DateName>Board meeting</DateName>
    <DateValue>14/01/2027</DateValue>
  </DateLookup>
  <HighlightDates>
    <Date>25/12/2026</Date>
    <Date>26/12/2026</Date>
  </HighlightDates>
</CustomDates>

Gets or sets the picture drawn on the drop-down button when UseDropDownImageStyle is DropDownImageStyle.CustomImage.

It is drawn at its own size from the button's top-left corner. The button is as wide as a vertical scroll bar and as tall as the text, so a picture of about that size suits it.

Gets or sets the .NET date format the text is written and read in, such as "dd/MM/yyyy" or "ddd d MMM yyyy".

It takes effect at once, whatever Format says, but setting Format to Long or Short replaces it – so set Format to BinaryDatePickerFormat.Custom as well. Literal text goes in quotes: "MMMM dd yyyy 'at' hh tt" gives March 27 2026 at 09 AM.

Gets or sets whether the user can type in the text box; the calendar works either way.

Gets or sets the length of each dash in the text box's dotted border.

Used while DrawBorderAs is BorderState.Dotted. A value set while EditControlStyleIsExtended is false is ignored.

Gets or sets the space between the dashes of the text box's dotted border.

Used while DrawBorderAs is BorderState.Dotted. A value set while EditControlStyleIsExtended is false is ignored.

Gets or sets whether the text box's border is a continuous line or dotted.

A value set while EditControlStyleIsExtended is false is ignored. A dotted border is drawn with DotBorderDepth and DotBorderGap.

datePicker.DrawBorderAs = BorderState.Dotted;
datePicker.DotBorderDepth = 2;
datePicker.DotBorderGap = 2;
datePicker.BorderColor = Color.SlateGray;

Gets or sets whether a hosted picker's calendar is open.

Gets or sets whether the text box has the control's flat, single-line border rather than the standard sunken one.

BorderColor, ShowBorderAlways, DrawBorderAs, DotBorderDepth and DotBorderGap apply only while it is set; set it first.

Gets or sets whether typed text is looked up among the named dates in CustomDateXMLFeed.

While it is set, the words today, tomorrow and the rest are not recognised: text that is not a date in the format is looked up in the file instead.

Gets or sets the font of the date text and of the calendar, which is sized to fit it.

Gets or sets the colour of the date text.

The calendar has its own colours; see CalendarForeColor.

Gets or sets the format the date is written in: the long or short date of the culture, or CustomFormat.

BinaryDatePickerFormat.Long and BinaryDatePickerFormat.Short set CustomFormat to "D" and "d"; BinaryDatePickerFormat.Custom keeps the format you set there. Typed text is read back in the same format.

Gets or sets whether the picker is hosted inside another control, such as a grid cell, rather than placed on a form.

A hosted picker opens its calendar in a drop-down window rather than a form of its own. Set it before SpecialDates and its colours, which are kept by the calendar this selects.

Gets or sets whether the date is shown but cannot be changed – neither typed nor picked from the calendar.

The calendar still opens, but ignores clicks and keys. DisplayTextState makes only the text read-only; the two set the same text box, so the one set last decides it.

Gets or sets whether the calendar marks the chosen day and today with filled circles.

While it is false the legend is not drawn either, whatever CalendarLegendDisplay says.

Gets the latest date MaxValue can be set to: 31 December 9999.

Gets or sets the latest date the control accepts.

A later date set in Value, chosen or committed becomes this date.

Gets the earliest date MinValue can be set to: 1 February 0001.

Gets or sets the earliest date the control accepts.

An earlier date set in Value, chosen in the calendar or committed from the text (Enter, or leaving the control) becomes this date.

Gets or sets the text shown when the control holds no date, such as "No date" or "Not shipped".

While ValueIsNull is set, Value returns this text unless the control is data bound. Typing it, or clearing the text box, makes the control hold no date.

Gets or sets whether the drop-down arrow button is drawn in the Windows visual style, with a hover effect, rather than as a classic combo-box button.

Used while UseDropDownImageStyle is DropDownImageStyle.DropDownArrow, and only when the application has visual styles enabled.

Gets or sets the colour of the filled circle marking the chosen day in the calendar.

Drawn while MarkSelectedDate is set.

Gets or sets the colour of the chosen day's number in the calendar, drawn on its circle.

Gets or sets whether the text box's border is always drawn in BorderColor, rather than only while the pointer is over it or it has the focus.

Set it to false for a hover effect: the border is drawn in a quieter colour at rest. A value set while EditControlStyleIsExtended is false is ignored.

Gets or sets whether right-clicking the text box shows the control's own menu.

The menu has Cut, Copy, Paste, Select All, Clear All, Display Calendar (Ctrl+L) and Quick Dates – yesterday, today, tomorrow, next week and last week. With false the text box's standard menu is shown instead.

Gets or sets whether the calendar opens above the control when there is no room for it below.

Gets or sets whether the calendar opens as soon as the control receives the focus.

The Control.Enter event is raised first, then the calendar opens.

Gets or sets dates to pick out in the calendar – holidays, delivery days, booked dates.

Each is drawn in SpecialDatesForeColor on SpecialDatesFillColor. The dates go to the calendar HostedFromChildContainer selects, so set that first.

Gets or sets the background of the SpecialDates in the calendar.

Gets or sets the colour of the day numbers of the SpecialDates in the calendar.

Gets or sets the background colour of the calendar's Today button.

Takes effect the next time the calendar opens.

Gets or sets how the calendar's Today button is drawn: flat, popup, standard or by the system.

Use FlatStyle.Flat or FlatStyle.Popup for the button colours to show in full.

Gets or sets the colour of the text on the calendar's Today button.

Gets or sets the caption of the calendar's Today button, which picks today's date and closes the calendar.

The button is 47 by 20 logical pixels, so keep a translation short – "Heute", "Auj.". The caption is also used on the calendar's right-click menu.

Gets or sets whether the calendar shows its Today and Close buttons.

Without them the calendar is shorter, and offers Today and Close on its right-click menu instead. Takes effect the next time the calendar opens.

Gets or sets the colour of the filled circle marking today in the calendar.

Drawn while MarkSelectedDate is set.

Gets or sets the colour of today's day number in the calendar, drawn on its circle.

Gets or sets what is drawn on the drop-down button: an arrow, a calendar picture, your own picture, or a glass button.

Gets or sets the date in the control.

Set a DateTime, or null or DBNull for no date; anything else is ignored. A date outside MinValue to MaxValue is moved to the nearer limit. The time of day is kept, and is carried over when the user picks a day.

Check ValueIsNull before casting: with no date the value is not a DateTime.

orderDate.Value = order.OrderedOn;      // a DateTime
shippedDate.Value = null;               // no date yet

if (!shippedDate.ValueIsNull)
{
    order.ShippedOn = (DateTime)shippedDate.Value;
}

Gets or sets whether the control holds no date, showing NullDateString.

Clearing the text, or setting Value to null or DBNull, sets it. Setting it back to false shows the date held before, or today.

Closes and releases the drop-down window of a hosted calendar, then the control.

Raises the Control.Enter event, then opens the calendar when ShowPopupOnEnter is set.

Raises the Control.FontChanged event and passes the new font to the calendar.

Commits the typed text as the date when the focus leaves the control, then raises the Control.Leave event.

Raises UserDateCustomValidating, then reads the text: in CustomFormat, then through CustomFormatDateChanged or the named dates. Text that cannot be read, or empty text, leaves the control with no date.

Reads the typed text and, when the press is on the drop-down button, opens the calendar; then raises the Control.MouseDown event.

Raises the Control.MouseLeave event and returns the drop-down button to its resting look.

Raises the Control.MouseMove event and lights up the drop-down button while the pointer is over it.

Returns the drop-down button to its resting look, then raises the Control.MouseUp event.

Draws the drop-down button in the UseDropDownImageStyle; the text box draws itself.

Fits the text box and the drop-down button to the new width, keeps the control as tall as its text, then raises the Control.Resize event.

The height follows Font; setting a taller size has no lasting effect.

Raises the Control.SystemColorsChanged event and redraws the control in the new colours.

Selects all the text in the control's text box, so the user's next keystroke replaces it.

Occurs just before the calendar opens.

The calendar is a window of its own. On a form whose Form.TopMost is set, clear Form.TopMost here and set it again in BinaryCalendarDeactivated, or the calendar opens behind the form.

Occurs when the calendar has opened.

Occurs when the calendar closes – a day chosen, Today or Close pressed, Escape, or a click elsewhere.

Occurs as the date is about to change: on each change of the text, when Value is set, and when the null state is set or cleared.

The value passed is Value before the change, whether the user types or code sets Value or ValueIsNull.

Occurs whenever the date changes: picked in the calendar, set from code or the menu, stepped by a key, made null – and on each keystroke while the user types.

Read Value in the handler; check ValueIsNull first. It is not raised before the control's window exists.

Occurs when the user leaves the control with text that does not match CustomFormat, so you can interpret it.

Raised only while Format is BinaryDatePickerFormat.Custom. The date the handler returns becomes the value; without a handler, unreadable text leaves the control with no date.

Occurs as the pointer moves over a day in the calendar, so you can show a tooltip for that date.

Raised on each move of the pointer while it is over a day. A tooltip is shown when the handler gives tipInfo body text and does not cancel.

datePicker.MouseIsOverADate += (object sender, DateInfo date, ref bool cancel, ref DateToolTipInfo tip) =>
{
    if (bankHolidays.TryGetValue(date.TheDateMousePointerIsOver.Date, out string name))
    {
        tip.ToolTipTitleText = "Bank holiday";
        tip.ToolTipBodyText = name;
    }
    else
    {
        cancel = true;
    }
};

Occurs before the typed text is read as a date – when the user presses Enter, leaves the control, clicks it or opens the calendar – so you can correct or translate it.

The text the handler leaves in dateText replaces the control's text and is then read in CustomFormat.

// Accept "eom" for the end of this month.
datePicker.UserDateCustomValidating += (object sender, ref string text) =>
{
    if (string.Equals(text.Trim(), "eom", StringComparison.OrdinalIgnoreCase))
    {
        DateTime today = DateTime.Today;
        text = new DateTime(today.Year, today.Month, DateTime.DaysInMonth(today.Year, today.Month))
            .ToString(datePicker.CustomFormat, datePicker.BinaryCultureInfo);
    }
};