366 CHAPTER 11 MORE CONTROLS The Photographs group box is now replaced with a Photos tab page. This tab is aligned on the left side of the tab control. The Alignment property uses the Tab- Alignment enumeration, with possible values Top, Bottom, Left, and Right. As you may have noticed, when the Alignment property for a tab control is Left or Right, the Multiline property is automatically set to true. Compile and run the application to make sure the controls still behave as expected, including mul- tiple selection and the owner-drawn list feature via the Thumbnails menu. We will add a second TabPage later in the chapter to display the set of dates asso- ciated with the album in a calendar format. This will enable a discussion of the MonthCalendar class. Before we can do this, we will first provide the appropriate support for the DateTaken property of the Photograph class. 11.3 DATES AND TIMES We will return to tab pages and our MyAlbumEditor application in a moment. In this section we finally preserve the Date Taken value entered by the user in our Pho- toEditDlg form. As you may recall, in chapter 9 we intentionally ignored this value to avoid converting the user-entered string value into a date. At the time we said there was a better way to deal with date constructs. In this section we finally see exactly what this looks like. Dealing with dates and times is one of those issues that prevent some program- mers from getting a good night’s sleep. With 3600 seconds in an hour, and 24 hours in a day, and different days per month, and leap years almost but not quite every four years, it’s no wonder. Fortunately, most languages and environments these days pro- vide direct support for date-time values to simplify handling of these constructs. In the .NET Framework, this support extends to Windows Forms controls as well. In chapter 5 we saw how the DateTime structure is used to represent a date-time value within a program. In this section we will look at representing a date-time value 8 Manually reestablish the event handlers for the controls. This includes the DoubleClick, DrawItem, MeasureItem, and SelectedIndexChanged event handlers for the list box, and the Click handlers for each of the four button controls. How-to Use the Events listing in the Properties window, and select the existing methods from the appropriate dropdown lists. The event handlers for the controls are assigned to the appropriate events. Note: This step is required whenever a control is cut from one location and pasted into another. The event handlers are not preserved, although the properties of the controls are. REPLACE THE GROUPBOX WITH A TABPAGE (continued) Action Result DATES AND TIMES 367 on a form using the DateTimePicker class, as summarized in .NET Table 11.3. This class displays a date and/or time to the user, and allows the user to change the values from the keyboard or from a dropdown calendar control. The dropdown calendar is based on the MonthCalendar class, which we will examine in the next section. 11.3.1 D ATES AND TIMES Our Photo Properties dialog with a DateTimePicker control in place is shown in figure 11.5. As you can see, the dropdown calendar control is displayed for the object. .NET Table 11.3 DateTimePicker class The DateTimePicker class represents a date and/or time value on a form. It allows the user to select a specific date and/or time, and presents this selection in a specified format. The DateTime value is presented in a text box control, with a down arrow providing access to a calendar from which an alternate date can be selected. The various parts of the DateTime value can alternately be modified using an up-down button or the arrow keys on the keyboard. This class is part of the System.Windows.Forms namespace, and inherits from the Con- trol class. See .NET Table 4.1 on page 104 for a list of members inherited from this class. Public Properties CalendarFont Gets or sets the Font to apply to the calendar portion of the control. CalendarForeColor Gets or sets the foreground color for the calendar. Checked When the ShowCheckBox property is true, gets or sets whether the check box is checked. CustomFormat Gets or sets the custom date-time format. Format Gets or sets how the date-time value is formatted in the control. MaxDate Gets or sets the maximum date-time value for the control. MinDate Gets or sets the minimum date-time value for the control. ShowCheckBox Gets or sets whether a check box displays to the left of the selected date. ShowUpDown Gets or sets whether an up-down control is used to adjust the date-time value. Value Gets or sets the DateTime value assigned to the control. Default is the current date and time. Public Events CloseUp Occurs when the dropdown calendar is dismissed and disappears. DropDown Occurs when the dropdown calendar is shown. FormatChanged Occurs when the Format property changes. ValueChanged Occurs when the Value property changes. 368 CHAPTER 11 MORE CONTROLS We can add this control to our dialog using the following steps. We will begin with the default display settings for this control, and look at how to modify these settings later in the section. Set the version number of the MyPhotoAlbum application to 11.3. Figure 11.5 The DateTimePicker shown here displays the Long date for- mat, which is the default. REPLACE THE DATE TEXT BOX WITH A DATETIMEPICKER CONTROL Action Result 1 In the PhotoEditDlg.cs [Design] window, delete the TextBox control next to the Date Taken label. 2 Place a DateTimePicker control where the text box used to be. Note: The location of this control is shown in figure 11.5. 3 Locate the ResetSettings method in the MainForm.cs source file. protected override void ResetSettings() { // Initialize the ComboBox settings . . . 4 Set the Value property for the date and time control. How-to Use the DateTaken property. Photograph photo = _album.CurrentPhoto; if (photo != null) { txtPhotoFile.Text = photo.FileName; txtCaption.Text = photo.Caption; dtpDateTaken.Value = photo.DateTaken; cmbxPhotographer.SelectedItem = photo.Photographer; txtNotes.Text = photo.Notes; } } Settings Property Value (Name) dtpDateTaken TabIndex 5 DATES AND TIMES 369 And there you have it. One DateTimePicker control ready to work. Compile and run the application, and set the dates for your photographs as appropriate. Make sure your albums preserve the selected date after exiting and restarting the program. You may have noticed that our control does not display the time. By default, the date and time control displays what .NET calls the long date. This includes the day of the week and month written out in the local language as well as the two-digit day and four-digit year. The format used by the control is specified by the Format property, using the DateTimePickerFormat enumeration described in .NET Table 11.4. As you can see from the table, various values allow either the date or time to be displayed in a format specified by the operating system. 11.3.2 C USTOMIZING A DATETIMEPICKER CONTROL As can be seen in .NET Table 11.4, a custom display setting for the DateTime- Picker control is used when the Format property is set to DateTimePicker- 5 Locate the SaveSettings method. protected override void SaveSettings() { 6 Set the DateTaken property to the date-time value specified by the user. Photograph photo = _album.CurrentPhoto; if (photo != null) { photo.Caption = txtCaption.Text; photo.DateTaken = dtpDateTaken.Value; photo.Photographer = cmbxPhotographer.Text; photo.Notes = txtNotes.Text; } } REPLACE THE DATE TEXT BOX WITH A DATETIMEPICKER CONTROL (continued) Action Result .NET Table 11.4 DateTimePickerFormat enumeration The DateTimePickerFormat enumeration specifies how to display a date-time value in a DateTimePicker control. This enumeration is part of the System.Windows.Forms namespace. For each value, the default setting for the U.S. English culture is provided. The for- mat codes used here correspond to the codes supported by the DateTimeFormatInfo class. Enumeration Values Custom A custom format is used, as specified by the CustomFormat property. Long The long date format is used. In Windows, this is typically “dddd, MMMM dd, yyyy” for U.S. English environments. This is the default value. Short The short date format is used. In Windows, this is typically “MM/dd/yyyy” for U.S. English environments. Time The time format is used. In Windows, this is typically “HH:mm:ss tt” for U.S. English environments. 370 CHAPTER 11 MORE CONTROLS Format.Custom. The CustomFormat property contains the string value to use in this case. A number of format codes are available within this string. These codes are managed by the sealed DateTimeFormatInfo class. The following table shows a number of these codes, along with some corresponding properties in the DateTimeFormatInfo class, which can be especially useful when operating in a multi-language environment. Consult the .NET documentation for the complete list of codes and additional information on the specified properties. Let’s modify our date and time control to display a customized value. We will include both the date and time in the display. Date-time codes for the DateTimeFormatInfo class Pattern Description Default U.S. English Value s DateTimeFormatInfo Property d Day of the month. 1 to 31 dd Two-digit day of the month. 01 to 31 ddd Abbreviated day of the week. Sun to Sat AbbreviatedDayNames dddd Full day of the week. Sunday to Saturday DayNames M Numeric month. 1 to 12 MM Two-digit numeric month. 01 to 12 MMM Abbreviated month name. Jan to Dec AbbreviatedMonthNames MMMM Full month name. January to December MonthNames y Year without century. 1 to 99 yy Two-digit year without century. 01 to 99 yyyy Four-digit century. 0001 to 9999 gg Period or era, if any. B.C. or A.D. h Hour on a 12-hour clock. 1 to 12 hh Two-digit hour on a 12-hour clock. 01 to 12 H Hour on a 24-hour clock. 1 to 24 HH Two-digit hour on a 24-hour clock. 01 to 24 m Minute. 0 to 59 mm Two-digit minute. 00 to 59 s Second. 0 to 59 ss Two-digit second. 00 to 59 tt AM/PM designator. AM or PM AMDesignator and PMDesignator : Default time separator. : ( a colon) TimeSeparator / Default date separator. / (a slash) DateSeparator ‘c’ Displays the specified character. For example, ‘s’ will display the character s rather than the number of seconds. DATES AND TIMES 371 If you compile and run these changes, you will find that the dropdown calendar still appears. The time values can be modified by hand or with the arrow keys. You might try using some alternate format strings, or setting the ShowUpDown property to true as a way to experiment with these customized settings. The DateTimePicker class is great for displaying a single date-time value. When multiple dates or a range of dates are required, the MonthCalendar class can be used. We will discuss this control next. More .NET As an alternative to a DateTimePicker control, another option here is to create separate controls for the month, day, and year, and if necessary the time of day. While the TextBox or ComboBox controls could be used for this purpose, you could also use the DomainUpDown and NumericUpDown controls. These controls are derived from the UpDownBase control, which in turn is based on the ContainerControl class presented in chapter 7. The up-down controls present a text-box-like window that displays a range of values. The DomainUpDown control presents a string value tak- en from a collection of objects, while the NumericUpDown control pre- sents a numeric value, optionally over a defined range. For separate month, day, and year controls, the properties for the DateTime- FormatInfo class shown earlier in this section may be used to obtain the default set of month strings for display within a DomainUpDown control. The day and year values can be displayed in a NumericUpDown control, with the range set based on the current month and the requirements of the application. DISPLAY A CUSTOM DATE-TIME VALUE IN THE DATETIMEPICKER CONTROL Action Result 1 Display the properties for the DateTimePicker control in the PhotoEditDlg.cs [Design] window. 2 Modify this control to display a custom format string. The control displays the new format within Visual Studio. Settings Property Value CustomFormat MM/dd/yy 'at' hh:mm tt Format Custom 372 CHAPTER 11 MORE CONTROLS 11.4 CALENDARS Sometimes a single date will not do. A scheduling program, for example, might need to show a calendar with meeting days highlighted, or display a meeting that covers a range of dates. The MonthCalendar class allows one or more months to be dis- played on a Form, with individual days highlighted or a range of days selected. Since our PhotoAlbum class permits each photograph to specify its own date, it seems appropriate to demonstrate the calendar control by highlighting the days in a calendar on which a photograph was taken. We will do this by adding a second TabPage object to our MyAlbumEditor main window. The result of our changes is shown in figure 11.6. Note how some dates are in bold to indicate one or more pho- tographs were taken that day. If the user clicks on a date, a context menu pops up con- taining the corresponding photographs. When a photograph is selected from this context menu, the properties for that photograph are displayed. The interface in figure 11.6 provides a very different view of our album. While the order of photographs in the album is not apparent, the specific days that a collec- tion of pictures was taken is immediately available. This section will discuss the month calendar control in general and add the con- trol to a new tab page in our application. We will discuss how to bold the dates when photographs were taken, and how to process and respond to mouse clicks made within the control. 11.4.1 A DDING A MONTHCALENDAR CONTROL An overview of the MonthCalendar class is provided in .NET Table 11.5. This class handles the entire range of dates possible in DateTime objects, which is basically any date with a four-digit century. This class is a good way to display a series of dates related to an object or collection of objects. Figure 11.6 The MonthCalendar control will automatically display multiple months as it is resized. CALENDARS 373 In our case, we will display the dates associated with a collection of photographs. Let’s begin by adding a new TabPage containing a MonthCalendar control to our form. .NET Table 11.5 MonthCalendar class The MonthCalendar class represents a control that displays one or more months to the user. Days in each month can be displayed in bold, and the user can select single or multiple dates. This class is part of the System.Windows.Forms namespace, and inherits from the Control class. See .NET Table 4.1 on page 104 for a list of members inherited from this class. Public Properties AnnuallyBoldedDates Gets or sets an array of DateTime objects that indicate which days to show in bold on an annual basis. BoldedDates Gets or sets an array of DateTime objects of specific dates to show in bold. MaxDate Gets or sets the maximum date. The user will not be able to display months occurring after this date. MaxSelectionCount Gets or sets the maximum number of dates that can be selected in the control. Defaults to seven (7). ScrollChange Gets or sets the number of months to scroll per click of a scroll button. Defaults to one (1). SelectionRange Gets or sets the range of dates selected in the control. SelectionStart Gets or sets the initial date of the range selected in the control. ShowToday Gets or sets whether to display the TodayDate value at the bottom of the control. ShowTodayCircle Gets or sets whether the TodayDate value is circled. TodayDate Gets or sets the DateTime value used as today’s date. Public Methods AddAnnuallyBoldedDate Adds a day to display in bold on an annual basis. GetDisplayRange Retrieves the range of dates displayed by the control. HitTest Determines which aspect of the month calendar control is located at a specific point. RemoveBoldedDate Removes a specific date from the list of nonrecurring bolded dates. SetDate Selects the given date in the control. Public Events DateChanged Occurs when the current date in the control is modified, such as when a new month is displayed. DateSelected Occurs when the dates selected in the control are modified. 374 CHAPTER 11 MORE CONTROLS Set the version number of the MyAlbumEditor application to 11.4. You will note that the Dock property for our month calendar object is set to Fill. This ensures that the number of months displayed will expand to fill the entire tab page as the form is enlarged. As we will see in the next section, months before the MinDate property value and after the MaxDate value will not be accessible from this control. 11.4.2 I NITIALIZING A CALENDAR Now that our MonthCalendar control is on the form, we can hook it up to our PhotoAlbum class. We do not want to initialize the calendar needlessly, so we will only do so when the Dates tab is displayed. By the same token, we do not want to ini- tialize the lstPhotos list box needlessly, so we need to ensure that this only occurs when the Photos tab is displayed. Since we used the method UpdateList for our list box, we will create an UpdateCalendar method to initialize and update our MonthCalendar control. The following steps are required for this change: CREATE THE DATES TAB PAGE Action Result 1 In the MainForm.cs [Design] window, add a second tab page to the TabControl object. 2 Add a MonthCalendar control to this page. Note: Your MonthCalendar control will circle the current date, which is likely not the date shown in the graphic. Settings Property Value (Name) tabDates Text Da tes Settings Property Value (Name) monthCalDates Dock Fill MaxSelection- Count 1 ShowToday False CALENDARS 375 INITIALIZE THE MONTH CALENDAR CONTROL Action Result 1 In the MainForm.cs source file, add an UpdateCalendar method to update the MonthCalendar control in the Dates tab. private void UpdateCalendar() { // Initialize MonthCalendar control 2 In this method, calculate the range of dates used by photographs in this album. DateTime minDate = DateTime.MaxValue; DateTime maxDate = DateTime.MinValue; DateTime[] dates = new DateTime[_album.Count]; 3 For each Photograph in the album, record its date and adjust the minimum and maximum date as required. Note: We could use a foreach loop here, of course. A for loop works a little better since an index for the dates array is required. for (int i = 0; i < _album.Count; i++) { DateTime newDate = _album[i].DateTaken; dates[i] = newDate; if (newDate < minDate) minDate = newDate; if (newDate > maxDate) maxDate = newDate; } 4 Assign the MonthCalendar properties based on the calculated date values. Note: The SelectionStart prop- erty ensures that the initial date for the album is displayed by the calendar. if (_album.Count > 0) { monthCalDates.BoldedDates = dates; monthCalDates.MinDate = minDate; monthCalDates.MaxDate = maxDate; monthCalDates.SelectionStart = minDate; } } 5 Add a new UpdatePhotographs method to update the appropriate tab page. How-to Use the SelectedTab property of the tcPhotos control. private void UpdatePhotographs() { if (tcPhotos.SelectedTab == tabPhotos) UpdateList(); else if (tcPhotos.SelectedTab == tabDates) UpdateCalendar(); } 6 Modify the OpenAlbum method to update the appropriate tab page. private void OpenAlbum(string fileName) { CloseAlbum(); _album.Open(fileName); this.Text = _album.FileName; UpdatePhotographs(); } 7 In the MainForm.cs [Design] window, handle the SelectedIndexChanged event for our tab control. Note: This is the default event for tab controls, and occurs when- ever a new tab is selected by the user. private void tcPhotos_SelectedIndexChanged (object sender, System.EventArgs e) { UpdatePhotographs(); } [...]... the MenuItem object provided by the Windows Forms namespace This technique is useful when you need a class that is similar to an existing control, and the ability to downcast objects in C# ensures that you can access the additional members of your derived class in a type-safe manner You can also build custom controls by extending the Control class directly Windows Forms also provides a UserControl class... will take up an assortment of different topics related to Windows Forms application development 382 CHA PTE R 11 MORE CONTROLS C H A P T E R 1 2 A NET assortment 12.1 12.2 12.3 12.4 12.5 Keyboard events 384 Mouse events 387 Image buttons 393 Icons 405 Recap 409 In the last three chapters we looked at various controls available in the Windows Forms namespace, and demonstrated the use of these controls... handler for the MouseDown event in the MonthCalendar control 4 Determine if the user clicked on a date How-to Use the HitTest method Result private void monthCalDates_MouseDown (object sender, System .Windows. Forms. MouseEventArgs e) { MonthCalendar.HitTestInfo info = monthCalDates.HitTest(e.X, e.Y); if (info.HitArea == MonthCalendar.HitArea.Date) { 5 If so, create a new context menu to hold any photographs... documentation entitled “Authoring a User Control with Visual C#” that introduces this concept Custom controls can also be tightly integrated into the Toolbox and other parts of Visual Studio NET The System .Windows. Forms. Design namespace contains the classes and other types to support such integration If you are interested in this topic, search for more information at any of the NET web sites listed in appendix... control Typically, this is used when analyzing a specific point in a calendar control using the HitTest method This enumeration is defined within the MonthCalendar class, and is part of the System .Windows. Forms namespace CalendarBackground The specified point is part of the calendar’s background Date The specified point is part of a specific date of the current month in the calendar The Time property... selected item The possible values for the HitArea property are defined by the MonthCalendar.HitArea enumeration, as described in NET Table 11.6 private void monthCalDates_MouseDown (object sender, System .Windows. Forms. MouseEventArgs e) { MonthCalendar.HitTestInfo info = monthCalDates.HitTest(e.X, e.Y); if (info.HitArea == MonthCalendar.HitArea.Date) { Another important part of this code is the definition and... three chapters we looked at various controls available in the Windows Forms namespace, and demonstrated the use of these controls in applications In this chapter we take a break from this aspect of Windows Forms development, and turn our attention to interacting with the keyboard and mouse, and the placement of images within certain controls For this discussion we return to the MyPhotos application we... KeyPressEventArgs class The KeyPressEventArgs class is the event argument class associated with the KeyPress event This class represents the keyboard character pressed by the user It is part of the System .Windows. Forms namespace, and inherits from the System.EventArgs class Handled Gets or sets whether the keyboard character was handled If true, then the control will not receive the character KeyChar Gets the... The KeyEventArgs class is the event argument class associated with the KeyDown and KeyUp events This class represents the keyboard key pressed down or released by the user It is part of the System .Windows. Forms namespace, and inherits from the System.EventArgs class Alt Control Gets whether the Ctrl key was pressed Handled Gets or sets whether the event was handled KeyCode Gets the specific keyboard... is the event argument class associated with the mouse events This class represents information about the mouse device and the mouse pointer position when the event occurs It is part of the System .Windows. Forms namespace, and inherits from the System.EventArgs class Button Clicks Gets the number of times the mouse button was pressed and released Note that the DoubleClick event should normally be used . controls available in the Windows Forms namespace, and demonstrated the use of these controls in applications. In this chapter we take a break from this aspect of Windows Forms development, and. using an up-down button or the arrow keys on the keyboard. This class is part of the System .Windows. Forms namespace, and inherits from the Con- trol class. See .NET Table 4.1 on page 104 for a. display a date-time value in a DateTimePicker control. This enumeration is part of the System .Windows. Forms namespace. For each value, the default setting for the U.S. English culture is provided.