DateTimePicker

Namespace: Wisej.Web

Assembly: Wisej.Framework (4.1.0.0)

• Control
  • DateTimePicker

Represents a control that allows the user to select or type a date and a time.

C#

public class DateTimePicker : Control, INotifyPropertyChanged, IModified, ILabel, IReadOnly, IValidation

VB.NET

Public Class DateTimePicker
    Inherits Control
    Implements INotifyPropertyChanged, IModified, ILabel, IReadOnly, IValidation

There are 4 tooltip labels that can be localized for this control. They are already localized in the default languages provided by Wisej. An application can localize the tooltip labels by adding the string resources to the localized Resources.resx or /Properties/Resources.resx.

• $Next year The tooltip text displayed on the popup calendar for the next-year button.
• $Last year The tooltip text displayed on the popup calendar for the last-year button.
• $Next month The tooltip text displayed on the popup calendar for the next-month button.
• $Last month The tooltip text displayed on the popup calendar for the last-month button.

Constructors

DateTimePicker()

Initializes a new instance of the DateTimePicker class.

DateTimePicker(onValueChanged)

Initializes a new instance of the DateTimePicker class with specific initial settings.

Name	Type	Description
onValueChanged	Action<Object, EventArgs>	Handler for the ValueChanged event.

DateTimePicker(label, onValueChanged)

Initializes a new instance of DateTimePicker class with specific initial settings.

Name	Type	Description
label	String	Initial LabelText value.
onValueChanged	Action<Object, EventArgs>	Handler for the ValueChanged event.

DateTimePicker(location, size, onValueChanged)

Initializes a new instance of DateTimePicker class with specific initial settings.

Name	Type	Description
location	Point	The Point representing the upper-left corner of the control relative to the upper-left corner of its container.
size	Size	The Size representing the height and width of the control.
onValueChanged	Action<Object, EventArgs>	The delegate to invoke when the ValueChanged event is raised.

DateTimePicker(label, location, size, onValueChanged)

Initializes a new instance of DateTimePicker class with specific initial settings.

Name	Type	Description
label	String	Initial LabelText value.
location	Point	The Point representing the upper-left corner of the control relative to the upper-left corner of its container.
size	Size	The Size representing the height and width of the control.
onValueChanged	Action<Object, EventArgs>	The delegate to invoke when the ValueChanged event is raised.

Properties

AutoSize

Boolean: Returns or sets whether the height of the control is set automatically. (Default: True)

BorderStyle

BorderStyle: Returns or sets the type of border that is drawn around the DateTimePicker. (Default: Solid)

Checked

Boolean: Returns or sets whether the checkbox in the DateTimePicker is checked and the user can change the control's value. Works in conjunction with the ShowCheckBox property. (Default: True)

CustomFormat

String: Returns or sets the custom date/time format string. (Default: "")

See Custom Date and Time Format Strings for the supported format definitions.

DefaultSize

Size: Returns the default size for a text box control.

Editable

Boolean: Returns or sets whether the user can edit the text in the control. (Default: True)

EnableNativeContextMenu

Boolean: Enables or disables the browser's context menu. (Default: True)

FirstDayOfWeek

Day: Returns or sets the first day of the week as displayed in the month calendar. (Default: Default)

Format

DateTimePickerFormat: Returns or sets the format of the date/time value displayed in the control. (Default: Long)

HidePromptOnLeave

Boolean: Returns or sets whether the prompt characters in the input mask are hidden when the masked datetime picker loses focus. (Default: False)

Invalid

Boolean: Returns or sets a value that indicates that the control is invalid. (Default: False)

InvalidMessage

String: Returns or sets the invalid message that is shown in the invalid tooltip. (Default: "")

Label

LabelWrapper: Provides a label related to the control.

LabelText

String: Returns or sets the localizable label associated with this control. (Default: "")

Mask

String: Returns or sets the input mask. (Default: "")

When setting an edit mask on the DateTimePicker control you must also select a Format that matches the mask. Otherwise the formatted date selected using the drop down calendar or by code will be formatted into a string that is not compatible with the edit mask. For example, if the mask is "##/##/####" the Format should be Short or CustomFormat should be "dd/MM/yyyy".

See also the TextMaskFormat property to determine how the mask is stripped when reading the Text property.

MaxDate

DateTime: Returns or sets the maximum date and time that can be selected in the control.

Throws:

• ArgumentException The value assigned is not less than the MaximumDateTime value (12/31/9998).
• SystemException The value assigned is less than the MinimumDateTime value (01/01/1753).

MinDate

DateTime: Returns or sets the minimum date and time that can be selected in the control.

Throws:

• ArgumentException The value assigned is not less than the MaximumDateTime value (12/31/9998).
• SystemException The value assigned is less than the MinimumDateTime value (01/01/1753).

Modified

Boolean: Returns or sets a value that indicates that the date time picker control has been modified by the user since the control was created or its contents were last set. (Default: False)

NullableValue

Nullable<DateTime>: Returns or sets the date/time Value assigned to the control with the difference that if the value is DateTime.MinValue it returns null.

This property should be used when the DateTimePicker may hold a null date and it's bound to a database nullable column. Throws:

• ArgumentOutOfRangeException The set value is less than MinDate or more than MaxDate.

PreserveTime

Boolean: Returns or sets whether the time portion of the Value is preserved when the date is changed. Since 4.0.6 (Default: True)

PromptChar

Char: Returns or sets the character used to represent the absence of user input in the DateTimePicker control. (Default: _)

Throws:

• ArgumentException The character specified when setting this property is not a valid prompt character.

ReadOnly

Boolean: Returns or sets whether the control is read-only. (Default: False)

SelectOnEnter

Boolean: Selects the text when gaining the focus. (Default: False)

ShowCalendar

Boolean: Returns or sets a value indicating if a calendar button (drop down control) is displayed and can be used to pick the date/time value. (Default: True)

ShowCheckBox

Boolean: Returns or sets whether a check box is displayed to the left of the selected date. (Default: False)

ShowToday

Boolean: Returns or sets whether the current date is displayed at the bottom of the control. (Default: False)

ShowToolTips

Boolean: Returns or sets whether the popup calendar shows ToolTips. (Default: True)

ShowUpDown

Boolean: Returns or sets a value indicating if the spin buttons (up and down controls) are displayed and can be used to adjust the date/time value. (Default: False)

ShowWeekNumbers

Boolean: Returns or sets whether the calendar control displays week numbers (1-52) to the left of each row of days. (Default: True)

Text

String: Returns or sets the text associated with this control. (Default: "")

The default value is DateTime.Today

TextMaskFormat

MaskFormat: Since 3.2.8 Returns or sets a value that determines whether literals and prompt characters are included in the Text value when the DateTimePicker also specifies a Mask. (Default: IncludeLiterals)

This property lets you control the value returned by the Text property when there is an edit Mask. The default is to remove the prompt and keep the literal in order to return a text value that can be parsed to a valid date: i.e. "1_/10/__23" is retuned as "1/10/23".

Since 3.2.8 Note that when the value is null or empty, and regardless of the mask, the Text property returns an empty string.

TodayDate

DateTime: Returns or sets the value that is used by DateTimePicker as today's date.

Throws:

• ArgumentOutOfRangeException The value is less than the minimum allowable date; or the value is greater than the maximum allowable date.

TodayFormat

String: Returns or sets the format string used to display today's date. (Default: "d")

See Custom Date and Time Format Strings for the supported format definitions.

Tools

ComponentToolCollection: Returns the instance of ComponentToolCollection associated with this control.

Value

DateTime: Returns or sets the DateTime value assigned to the control.

Throws:

• ArgumentOutOfRangeException The set value is less than MinDate or more than MaxDate.

Watermark

String: Returns or sets the text to show when the field is empty. (Default: null)

Methods

Dispose(disposing)

Dispose the control.

Parameter	Type	Description
disposing	Boolean	true when this method is called by the application rather than a finalizer.

GetDisplayText(value)

Formats the date value using the format type specified in Format and CustomFormat .

Parameter	Type	Description
value	Nullable<DateTime>

Returns: String. The formatted text to display in the control.

OnCheckedChanged(e)

Fires the CheckedChanged event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnCloseUp(e)

Fires the CloseUp event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnDropDown(e)

Fires the DropDown event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnEditableChanged(e)

Fires the EditableChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnFormatChanged(e)

Fires the FormatChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnMaskChanged(e)

Fires the MaskChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains event data.

OnModifiedChanged(e)

Fires the ModifiedChanged event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnReadOnlyChanged(e)

Fires the ReadOnlyChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnTextChanged(e)

Fires the TextChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnToolClick(e)

Fires the ToolClick event.

Parameter	Type	Description
e	ToolClickEventArgs	A ToolClickEventArgs that contains the event data.

OnValidating(e)

Fires the Validating event.

Parameter	Type	Description
e	CancelEventArgs	A EventArgs that contains the event data.

OnValueChanged(e)

Fires the ValueChanged event.

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

OnWebEvent(e)

Processes the event from the client.

Parameter	Type	Description
e	WisejEventArgs	Event arguments.

OnWebRender(config)

Renders the client component.

Parameter	Type	Description
config	Object	Dynamic configuration object.

OnWebUpdate(state)

Updates the client component using the state information.

Parameter	Type	Description
state	Object	Dynamic state object.

ParseEditText(text, value)

Parses a string to a valid DateTime using a range of formats, including the custom format.

Parameter	Type	Description
text	String	The text to part.
value	DateTime	Parsed DateTime value to store in the control.

Returns: Boolean. True if the text is considered a valid date; otherwise false.

SetBoundsCore(x, y, width, height, specified)

Sets the specified bounds of the ComboBox control.

Parameter	Type	Description
x	Int32	The new Left property value of the control.
y	Int32	The new Top property value of the control.
width	Int32	The new Width property value of the control.
height	Int32	Not used.
specified	BoundsSpecified	A combination of the BoundsSpecified values.

ValidateEditText()

Validates and updates the text displayed in the date/time picker.

Returns: Boolean.

Events

CheckedChanged

EventHandler Fired when the value of the Checked property changes.

CloseUp

EventHandler Fired when the drop-down calendar is dismissed and disappears.

DropDown

EventHandler Fired when the drop-down calendar is shown.

EditableChanged

EventHandler Fired when the value of the Editable property has changed.

FormatChanged

EventHandler Fired when the Format property value has changed.

MaskChanged

EventHandler Occurs after the input mask is changed.

ModifiedChanged

EventHandler Fired when the value of the Modified property has changed.

ReadOnlyChanged

EventHandler Fired when the value of the ReadOnly property has changed.

ToolClick

ToolClickEventHandler Fired when a ComponentTool is clicked.

ValueChanged

EventHandler Fired when the Value property changes.

Inherited By

Name	Description
DataGridViewDateTimePickerEditingControl	Represents a DateTimePicker control that can be hosted in a DataGridViewDateTimePickerCell.

Implements

Name	Description
IUserData	Provides access to the UserData and Tag properties associated to the component implementing this interface.
IBindableComponent	Bindable components implement this interface.
IDropTarget	Controls that support drag & drop operations implement this interface.
ILabel	Provides access to the LabelWrapper associated with the controls that implement this interface.
IReadOnly	Provides access to the ReadOnly property for coontrols that support the read-only mode.
IModified	Provides access to the Modified property and ModifiedChanged event for controls that implement this interface.
IValidation	Provides access to the validation events and properties property for controls that support validation.
IWisejComponent	All wisej components implement this interface.
IWisejControl	All wisej controls derived from the Control class must implement this interface.
IWisejSerializable	Allows an object to serialize itself.