NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Calendar Web Control

The Calendar Web control displays a one-month calendar that the user can use to view dates or select a specific day, week, or month.

ASP+ Syntax

Required properties are noted in boldface type.

<asp:Calendar id="Calendar1" runat="server"
   CellPadding="pixels"
   CellSpacing="pixels"
   DayNameFormat="FirstLetter|FirstTwoLetters|Full|Short"
   FirstDayOfWeek="Default|Monday|Tuesday|Wednesday|
      Thursday|Friday|Saturday|Sunday"
   NextMonthText="HTML text"
   NextPrevFormat="ShortMonth|FullMonth|CustomText"
   PrevMonthText="HTML text"
   SelectedDate="date"
   SelectionMode="None|Day|DayWeek|DayWeekMonth"
   SelectMonthText="HTML text"
   SelectWeekText="HTML text"
   ShowDayHeader="True|False"
   ShowGridLines="True|False"
   ShowNextPrevMonth="True|False"
   ShowTitle="True|False"
   TitleFormat="Month|MonthYear"
   TodaysDate="date"
   VisibleDate="date"
   TodayDayStyle-property="value"
   DayHeaderStyle-property="value"
   DayStyle-property="value"
   NextPrevStyle-property="value"
   OtherMonthDayStyle-property="value"
   SelectedDayStyle-property="value"
   SelectorStyle-property="value"
   StyeDayHeaderStyle-property="value"
   TitleStyle-property="value"
   TodayDayStyle-property="value"
   WeekendDayStyle-property="value"
/>

Properties

Property Description
(Base control properties) The properties defined in Base Web Control Properties.
CellPadding The amount of space, in pixels, between cells.

When programming, this property is set using Units.

CellSpacing The amount of space, in pixels, between the contents of a cell and the cell's border.

When programming, this property is set using Units.

DayNameFormat A value that determines the format of the day names. Day names are derived from the server's locale settings. The default is Short.

When programming, this property is set using the DayNameFormat enumeration.

FirstDayOfWeek A value for the day of the week that will be displayed in the calendar's first column. The default is Default, which uses the server's locale settings to determine the day.

When programming, this property is set using the FirstDayOfWeek enumeration.

NextMonthText The HTML text shown for the next month navigation hyperlink if ShowNextPrevMonth is true. If set, this value overrides the default (the month name).
NextPrevFormat A value that specifies the format of the next and previous month hyperlinks in the title. To create your own link text, specify Custom and set the NextMonthText and PrevMonthText properties. The default is Custom.

When programming, this property is set using the NextPrevFormat enumeration.

PrevMonthText The HTML text shown for the previous month navigation hyperlink if ShowNextPrevMonth is true. If set, this value overrides the default (the month name).
SelectedDate A date that specifies the highlighted date. The default is the value of TodaysDate.

When programming, this property is set using a DateTime data type.

SelectedDates (Read only) A collection of DateTime objects representing days highlighted on the calendar. If SelectionMode is set to anything but Day, the collection can contain multiple dates.

This property is only used when programming.

SelectionMode A value that specifies whether the user can select a day, week, or month. The default is Day. To disable date selection, set this property to None.

When programming, this property is set using a CalendarSelectionMode enumeration.

SelectMonthText The HTML text shown for month selection in the selector column if SelectionMode is DayWeekMonth.
SelectWeekText The HTML text shown for week selection in the selector column if SelectionMode is DayWeek or DayWeekMonth.
ShowDayHeader A value that determines whether the names of the days of the week are displayed.
ShowGridLines A value that specifies whether days are displayed with lines around them. Not all browsers can display gridlines.
ShowNextPrevMonth A value that specifies whether the calendar displays next and previous month hyperlinks in the title.
ShowTitle A value that specidies whether the calendar's title is displayed. Hiding the calendar hides the month name and month selection hyperlinks.
TitleFormat A value that specifies how the month name is formatted in the title bar. The default is Month.

When programming, this property is set using the TitleFormat enumeration.

TodaysDate The date to use as the current date. (This date might have to be adjusted to accommodate users who are in a another time zone.) TodaysDate is displayed on the calendar only if you have set properties of the TodayDayStyle object.

When programming, this property is set using a DateTime data type.

VisibleDate A date that specifies what month to display. The date can be any day within the month. The VisibleDate property is updated after the VisibleMonthChanged event is raised.

When programming, this property is set using a DateTime data type.

Style Objects

For information about the properties supported for each style class, see Style Object Properties.

Style object Description Style class
DayHeaderStyle Days of the current month. Weekends, the current date, and the selected day can have different styles. TableItemStyle
DayStyle Row above the calendar where the names of the days appear. TableItemStyle
NextPrevStyle Sections at the left and right ends of the title bar where the month navigation LinkButtons are. TableItemStyle
OtherMonthDayStyle Days from the previous and next month that appear on the current month view. TableItemStyle
SelectedDayStyle Day selected by the user. TableItemStyle
SelectorStyle Column to the left containing links for selecting a week or the whole month. TableItemStyle
TitleStyle Title bar at the top of the calendar containing the month name and month navigation links. If NextPrevStyle is set, it overrides the extreme ends of the title bar. Style
TodayDayStyle The current date. TableItemStyle
WeekendDayStyle Weekend days. TableItemStyle

Events

Event (and paramters) Description
OnDayRender(Object sender, DayRenderEventArgs e) Raised on the server as each day cell is created.

The following are properties of the e events argument object:

e.Cell   (TableCell) An object representing a table cell into which the day is rendered.

e.Cell.RowSpan   (Integer)

e.Cell.ColumnSpan   (Integer)

e.Cell.HorizontalAlign   (HorizontalAlign)

e.Cell.VerticalAlign   (VerticalAlign)

e.Cell.Wrap   (Boolean)

e.Day   (CalendarDay) An object representing the day being rendered.

e.Day.Date   (DateTime) The date being rendered.

e.Day.DayNumberText   (String) The number of the day (for example, "20") as a string.

e.Day.IsOtherMonth   (Boolean)

e.Day.IsSelectable   (Boolean)

e.Day.IsSelected   (Boolean)

e.Day.IsToday   (Boolean)

e.Day.IsWeekend   (Boolean)

OnVisibleMonthChanged(Object sender, MonthChangedEventArgs e) Raised on the server when the user clicks a button for the next or previous month in the Calendar's title.

The following are properties of the e events argument object:

e.NewDate   (DateTime)

e.PreviousDate   (DateTime)

OnSelectionChanged(Object sender, EventArgs e) Raised on the server when the user selects a day, week, or month selector. This event always causes the page to be posted to the server.

The e events argument object has no properties.

Example

The following shows a sample declaration for a Calendar control in an .aspx file. The declaration includes a number of style object properties and establishes the method Date_Selected as the handler for the OnSelectionChanged event.

<asp:Calendar id=Calendar2 runat="server"
   OnSelectionChanged="Date_Selected"
   DayNameFormat="FirstTwoLetters"
   SelectionMode="DayWeekMonth"
   Font-Name="Verdana;Arial" Font-Size="12px"
   Height="180px" Width="230px"
   TodayDayStyle-Font-Bold="True"
   DayHeaderStyle-Font-Bold="True"
   OtherMonthDayStyle-ForeColor="gray"
   TitleStyle-BackColor="#3366ff"
   TitleStyle-ForeColor="white"
   TitleStyle-Font-Bold="True"
   SelectedDayStyle-BackColor="#ffcc66"
   SelectedDayStyle-Font-Bold="True"
   NextPrevFormat="ShortMonth"
   NextPrevStyle-ForeColor="white"
   NextPrevStyle-Font-Size="10px"
   SelectorStyle-BackColor="#99ccff"
   SelectorStyle-ForeColor="navy"
   SelectorStyle-Font-Size="9px"
   SelectWeekText = "week"
   SelectMonthText = "month"
   />

The following example shows how an event-handling method for a Calendar control's OnSelectionChanged event. By querying the s events argument object, the code can determine how many days were selected, and therefore whether the user selected a day, week, or month. Information about the selection is displayed in a Label Web control.

[C#]
protected void Date_Selected(object s, EventArgs e)
{
   switch (((Calendar)s).SelectedDates.Count)
   {
       case (0):   //None
       {
           Label1.Text = "No dates are currently selected";
           break;
       }
       case (1):   //Day
       {
           Label1.Text = "The selected date is " + 
              ((Calendar)s).SelectedDate.ToShortDateString();
           break;
       }
       case (7):   //Week
       {
           Label1.Text = "The selection is a week beginning " + 
             ((Calendar)s).SelectedDate.ToShortDateString();
           break;
       }
       default:    //Month
           Label1.Text = "The selection is a month beginning " + 
             ((Calendar)s).SelectedDate.ToShortDateString();
   }
}

See Also

Web Forms Controls by Function | Using the Calendar Web Control