Common Windows Forms Controls

Many controls are available for use in your Windows forms application. Most of these are derived from the System.Windows.Forms.Control class, as detailed in Figure 2.4.

Figure 2.4. The Controls hierarchy showing many common Windows forms controls.

In this section, we'll look at many of the members of some of the more common control classes. If you are familiar with the Visual Studio development environment, many of these may be familiar to you already.

GroupBox and Panel

Like the Form control itself, some controls are meant to contain other controls in order to arrange or group controls together. The GroupBox control can contain other controls and includes a caption, whereas the Panel control adds scroll bars to allow you to present more controls within the same panel. The Panel control does not include a caption. Table 2.1 details the important members of the GroupBox class, and Table 2.2 details those of the Panel class.

Table 2.1. Important Members of the GroupBox Class

Member	Type	Description
Controls	Property	Collection of controls contained in the group box
Text	Property	Caption of the group box

Table 2.2. Important Members of the Panel Class

Member	Type	Description
AutoScroll	Property	Specifies whether scroll bars should be displayed when the display of all controls exceeds the panel's area
Controls	Property	Collection of controls contained in the panel

GroupBox and Panel controls may be used on the same form in order to group other controls, as desired, or to allow the use of scroll bars in order to access a larger control within a smaller area. Figure 2.5 shows the use of a Panel control to provide a scrollable area containing a larger PictureBox control displaying an image, along with a GroupBox control showing the file statistics for the image file within several Label controls.

Figure 2.5. Panel and GroupBox controls are used in combination to display an image file and its statistics.

Label and LinkLabel

The Label control displays read-only data to the user , including both text and image information. The LinkLabel control extends this to include a clickable hyperlink capability that may open a Web page, application, or folder. Table 2.3 details the important members of the Label class, whereas Table 2.4 details those of the LinkLabel class.

Table 2.3. Important Members of Label Class

Member	Type	Description
Image	Property	Image displayed on the label
Font	Property	Font for the displayed text
Text	Property	The displayed text
TextAlign	Property	The alignment of the text on the label (Center, Left, or Right and Bottom, Middle, or Top)

Table 2.4. Important Members of LinkLabel Class

Member	Type	Description
ActiveLinkColor	Property	The color used to display an active link.
DisabledLinkColor	Property	The color used to display a disabled link.
Links	Property	Gets the collection of Link objects in the LinkLabel control. The Link class contains information about the hyperlink. Its LinkData property allows you to associate a URL with the hyperlink.
LinkArea	Property	Specifies which portion of text in the LinkLabel control is treated as part of the link.
LinkBehavior	Property	Specifies how the link will appear when the mouse pointer is placed over it.
LinkClicked	Event	The default event. This is generated when the link is clicked. Inside its event handler, the LinkLabelLinkClickedEventArgs parameter will provide you with data for the event.
LinkColor	Property	The color used to display a link.
VisitedLinkColor	Property	The color used to display a previously visited link.

TextBox and RichTextBox

The TextBox and RichTextBox classes both derive from the TextBoxBase class. They allow for single-line or multiline user input, including masked input such as that used in a password-input field, where each input character is displayed simply as the masking charactertypically the asterisk (*). The RichTextBox control includes the capability to display formatted text using the standard Rich Text Format (RTF). Table 2.5 details the important members of the TextBox class, and Table 2.6 details those of the RichTextBox class.

Table 2.5. Important Members of the TextBox Class

Member	Type	Description
AcceptsReturn	Property	A Boolean value (True/False) which is set to True if pressing the Enter key in a multiline text box will insert a new line.
CharacterCasing	Property	Controls the case of characters as they are entered (Lower, Normal, or Upper). The default value is Normal, which does not modify the case of entered characters .
MultiLine	Property	Specifies whether the TextBox control can accept multiple lines of input. The default value is False.
PasswordChar	Property	Used to display input characters with the specified mask character. This is typically used to protect the display of sensitive information such as passwords. The setting is null by default; if this value is not set, then characters are displayed normally.
ReadOnly	Property	Determines whether the displayed text is read-only, in which case the control will appear with the system's disabled control color for its background, and its text cannot be edited. The default value is False.
ScrollBars	Property	Specifies which scroll bars (none, horizontal, vertical, or both) should appear in a multiline text box.
Text	Property	The text contained in the text box.
TextChanged	Event	The default event, which occurs when the value of the control's Text property changes.
WordWrap	Property	Specifies whether text in a multiline control can automatically wrap words to the next line. The default value is True.

Table 2.6. Important Members of the RichTextBox Class

Member	Type	Description
DetectUrls	Property	Specifies whether the control will automatically detect and format URLs
Rtf	Property	A version of the text that contains RTF formatting codes
SelectionColor	Property	The color of the currently selected text
SelectionFont	Property	The font of the currently selected text
SelectedRtf	Property	The currently selected RTF text
TextChanged	Event	The default event, which occurs when the value of the control's Text property changes
WordWrap	Property	Specifies whether the control can automatically wrap words to the next line if required
ZoomFactor	Property	The current zoom level

PictureBox

The PictureBox control can display graphical images from many sources, including icon ( .ico ), bitmap ( .bmp ), metafile ( .wmf ), JPEG/JPG, PNG, and GIF files. Table 2.7 details the important members of the PictureBox class.

Table 2.7. Important Members of the PictureBo Class

Member	Type	Description
Click	Event	The default event, which occurs when the control is clicked.
Image	Property	The displayed image.
SizeMode	Property	Specifies how the image is displayed. This property holds one of the PictureBoxSizeMode enumeration values: AutoSize (auto- sized to the image size), CenterImage (displayed in the center of the control), Normal (placed in the upper-left corner of the control), or StretchImage ( stretched or reduced to fill the control).

Button, RadioButton, and CheckBox

When you need to obtain selection information from users, the Button, RadioButton, and CheckBox controls may be used. These derive from the ButtonBase control and are often grouped within container controls such as GroupBox. The Button control is used to initiate actions when clicked, whereas the RadioButton and CheckBox controls are used to select state. For example, you might use a RadioButton control to indicate whether an option is enabled or disabled in your application.

A CheckBox control may have two states (on/off) or three states (on/off/indeterminate), depending on how it is configured.

A group of CheckBox controls may be used to allow the selection of several states, whereas a group of RadioButton controls may be used to allow the selection of one of the options listed. Table 2.8 details the important members of the Button class, Table 2.9 details those of the RadioButton class, and Table 2.10 details those of the CheckBox class.

Table 2.8. Important Members of the Button Class

Member	Type	Description
Click	Event	The default event, which fires when the button control is clicked
Image	Property	The image displayed on the button
Text	Property	The text displayed on the button

Table 2.9. Important Members of the RadioButton Class

Member	Type	Description
Checked	Property	Indicates whether the radio button is checked. (True if checked; False otherwise .)
CheckedChanged	Event	The default event of RadioButton control. This event fires every time the control is checked or unchecked.
Text	Property	The text displayed along with the radio button.

Table 2.10. Important Members of the CheckBox Class

Member	Member	Description
Checked	Property	True if the check box is checked; otherwise False.
CheckedChanged	Event	The default event for the CheckBox control. This event fires every time the check box is checked or unchecked.
CheckState	Property	The state of the check box: Checked, Unchecked, or Indeterminate.
ThreeState	Property	Determines whether the CheckBox control allows three states. If this is set to False, the CheckState property can only be set to Indeterminate via code and not through the user interface.
Text	Property	The text displayed adjacent to the check box.

When the AutoCheck property is set to True (the default) on a CheckBox or RadioButton control, the control will change the value of its Checked and CheckState properties as well as its appearance automatically when the user clicks the control. This saves the developer from needing to trap the Click event to change those properties.

ListBox and CheckedListBox

The ListBox and CheckedListBox controls both derive from the ListControl class and allow for the selection of values from a predetermined list of options. The ListBox control may be configured to allow only a single selection or multiple selections from the displayed values, whereas the CheckedListBox control includes integrated CheckBox controls for each item and may not be restricted to allow only a single value. Table 2.11 details the important members of the ListBox class, and Table 2.12 details those of the CheckedListBox class.

Table 2.11. Important Members of the ListBox Class

Member	Type	Description
ColumnWidth	Property	The column width in a multicolumn list box.
FindString	Method	Finds the first item in the list box that starts with the specified string.
FindStringExact	Method	Finds the first item in the list box that exactly matches the specified string.
ItemHeight	Property	The height of an item in the list box.
Items	Property	A collection of objects representing the list of items in the list box.
MultiColumn	Property	Determines whether the list box supports multiple columns .
SelectedIndex	Property	The index of the currently selected item. This property returns -1 if no item is selected.
SelectedIndexChanged	Event	The default event, which occurs when the SelectedIndex property changes.
SelectedIndices	Property	The collection of indexes of currently selected items.
SelectedItem	Property	The currently selected item.
SelectedItems	Property	The collection of currently selected items.
SelectionMode	Property	Specifies the number of items that can be selected. The values are specified by the SelectionMode enumeration. They can be MultiSimple (allows multiple selections), MultiExtended (allows multiple selections with the help of the Ctrl, Shift, and arrow keys), None (no selectiondisplay only), and One (allows a single selection).
Sorted	Property	Specifies whether the items are sorted alphabetically .

Table 2.12. Important Members of the CheckedListBox Class

Member	Type	Description
CheckedIndices	Property	The collection of indexes of currently checked items.
CheckedItems	Property	The collection of currently checked items.
ItemCheck	Event	Occurs when an item is checked or unchecked.
SelectionMode	Property	Indicates the number of items that can be checked. The values are specified by the SelectionMode enumeration. They can be only None (no selectiondisplay only) or One (allows multiple selections).

Figure 2.6 shows the use of a CheckBox and a ListBox control to provide selectable lists of values.

Figure 2.6. CheckBox and ListBox controls are used on the same form to display list-selection options.

ComboBox

The ComboBox control is also derived from the ListControl class and is used to allow the selection of one value from a specified list or to allow the entry of a new value. It combines a scrollable list of values with a text-entry area that may be used to modify the selected value or input a new value not already in the list, if the control has been configured to allow this. Table 2.13 details the important members of the ComboBox class.

Table 2.13. Important Members of the ComboBox Class

Member	Type	Description
DrawMode	Property	Specifies how the combo box items are drawn. The value Normal specifies that the list of items is drawn by the system. The other two values specify that elements are drawn by your own program (preferably using the DrawItem event handler). OwnerDrawFixed specifies that elements will all be of the same size, whereas OwnerDrawVariable specifies a variable size.
DropDownStyle	Property	The style of the combo box. DropDown (the default style; click the arrow button to display items and the text portion is editable), DropDownList (click the arrow button to display items, but the text portion is not editable) and Simple (no arrow button; the list and text portions are always visible and the text is editable) are values of the DropDownStyle property.
DropDownWidth	Property	The width of the drop-down list portion of the combo box.
Items	Property	The collection of items in the control.
MaxDropDownItems	Property	The maximum number of items the drop-down list portion can display at a time. If the number of items is more than this, a scroll bar appears.
MaxLength	Property	The maximum length of text allowed in the editable portion.
SelectedIndex	Property	The index of the currently selected item.
SelectedIndexChanged	Event	The default event, which occurs when the selected index property changes.
SelectedItem	Property	The currently selected item.
SelectedText	Property	The currently selected text in the editable portion.
Sorted	Property	Specifies whether the items are sorted alphabetically.

DomainUpDown and NumericUpDown

The DomainUpDown and NumericUpDown controls inherit from the System.Windows.Forms.UpDownBase class and allow the selection of values from an ordered list of values using the up and down buttons of the controls. If the ReadOnly value is False (the default value), then values may be typed into the control as well as selected by using the buttons. The DomainUpDown control allows for selection from a list of objects with the result being returned as a string to the control, whereas the NumericUpDown control contains a numeric value that may be adjusted between the Minimum and Maximum values by an amount specified by the Increment property. Table 2.14 details the important members of the DomainUpDown class, and Table 2.15 details those of the NumericUpDown class.

Table 2.14. Important Members of the DomainUpDown Class

Member	Type	Description
Items	Property	The collection of objects assigned to the control.
ReadOnly	Property	Specifies whether you can enter a value directly, without using the buttons.
SelectedIndex	Property	The index value of the currently selected item.
SelectedItem	Property	The value of the currently selected item.
SelectedItemChanged	Event	The default event, which occurs when the SelectedIndex property is changed.
Sorted	Property	Determines whether the Items collection is sorted.
Wrap	Property	Specifies whether the SelectedIndex property wraps to the first or the last item if the user continues past the end of the list. If the Wrap property is True, then clicking the Up button when you're at the end of the list returns the selected index to zero.

Table 2.15. Important Members of the NumericUpDown Class

Member	Type	Description
Increment	Property	The value of the increment used to decrease or increase the value when a button is clicked.
Maximum	Property	The maximum allowed value.
Minimum	Property	The minimum allowed value.
ReadOnly	Property	Specifies whether you can change the value directly.
ThousandsSeparator	Property	Specifies whether a thousands separator should be used, when appropriate.
Value	Property	The value assigned to the control.
ValueChanged	Event	The default event, which occurs when the Value property is changed.

MonthCalendar and DateTimePicker

The MonthCalendar and DateTimePicker controls allow the selection of date and time values. The MonthCalendar control includes an easily navigable user interface to select a particular date within a calendar format, whereas the DateTimePicker control allows selection of date and time values using different formats. Figure 2.7 provides an example of the use of the MonthCalendar and DateTimePicker controls.

Figure 2.7. MonthCalendar and DateTimePicker controls displaying selected values.

Table 2.16 details the important members of the MonthCalendar class, and Table 2.17 details those of the DateTimePicker class.

Table 2.16. Important Members of the MonthCalendar Class

Member	Type	Description
CalendarDimensions	Property	The number of columns and rows of months displayed
DateChanged	Event	The default event, which occurs when the date selected in the control changes
DateSelected	Event	Occurs when a date is selected in the control
FirstDayOfWeek	Property	The first day of week displayed by the calendar
MaxDate	Property	The maximum allowable date to be selected
MaxSelectionCount	Property	The maximum number of days that can be selected
MinDate	Property	The minimum allowable date to be selected
SelectionEnd	Property	The end date of the selected range
SelectionRange	Property	The selected range of dates
SelectionStart	Property	The start date of the selected range
ShowToday	Property	Specifies whether today's date should be displayed at the bottom of the control
ShowTodayCircle	Property	Specifies whether today's date should be circled
ShowWeekNumbers	Property	Specifies whether the week numbers (152) should be displayed at the beginning of each row of days
TodayDate	Property	Represents today's date

Table 2.17. Important Members of the DateTimePicker Class

Member	Type	Description
CustomFormat	Property	Represents a custom date and time format string.
Format	Property	Specifies the format of the date and time displayed in the control. The values are specified by the DateTimePickerFormat enumeration: Custom, Long (the default), Short, and Time. Long, Short, and Time display the date in the value formats set by the operating system. Custom lets you specify your own custom format.
FormatChanged	Event	Occurs when the Format property changes.
MaxDate	Property	The maximum allowable date and time to be selected.
MinDate	Property	The minimum allowable date and time to be selected.
ShowCheckBox	Property	Specifies whether a check box should be displayed at the left of the selected date.
ShowUpDown	Property	Specifies whether an up/down control should be displayed to allow user selections rather than the default calendar control.
Value	Property	The value of the date and time selected.
ValueChanged	Event	The default event, which occurs when the value changes.

TreeView and ListView

The TreeView and ListView controls allow the display of hierarchical collections of nodes. Within the TreeView control, nodes are represented by TreeNode objects, each of which can have its own collection of child nodes. The ListView control includes a list of items, each of which can have a name , icon, and additional columns of associated text. Figure 2.8 provides an example of the use of the TreeView and ListView controls.

Figure 2.8. TreeView and ListView controls used to display a simple folder hierarchy and objects contained within the selected folder.

Table 2.18 details the important members of the TreeView class, and Table 2.19 details those of the ListView class.

Table 2.18. Important Members of the TreeView Class

Member	Type	Description
AfterCheck	Event	Occurs after a tree node is checked.
AfterCollapse	Event	Occurs after a tree node is collapsed .
AfterExpand	Event	Occurs after a tree node is expanded.
AfterSelect	Event	The default event, which occurs after a tree node is selected.
CheckBoxes	Property	Specifies whether a check box should appear along with each item in the control.
ImageList	Property	The image list that contains node icons.
Nodes	Property	The collection of tree nodes in the control.
Scrollable	Property	Specifies whether scroll bars should be displayed when needed. The default value is True.
SelectedNode	Property	The currently selected node.
Sorted	Property	Specifies whether the tree nodes are sorted.

Table 2.19. Important Members of the ListView Class

Member	Type	Description
Activation	Property	Indicates how an item can be activated: OneClick (single click), Standard (double-click) and TwoClick (double-click and the item color changes when mouse hovers over it). These values are defined in the ItemActivation enumeration.
CheckBoxes	Property	Specifies whether a check box should appear along with each item in the control.
CheckedIndices	Property	The collection of indexes of the currently checked items.
CheckedItems	Property	The collection of currently checked items.
ItemActivate	Event	Occurs when an item is activated.
ItemCheck	Event	Occurs when an item's check state changes.
Items	Property	The collection of items displayed by the ListView control.
LargeImageList	Property	The image list to be used to display large icons.
MultiSelect	Property	Specifies whether multiple items can be selected.
Scrollable	Property	Specifies whether scroll bars need to be added when the list of items exceeds the size of the client area. The default value is True.
SelectedIndexChanged	Event	The default event, which occurs when the selected index changes.
SelectedIndices	Property	The collection of indexes of the currently selected items.
SelectedItems	Property	The collection of currently selected items.
SmallImageList	Property	The image list to be used to display small icons.
Sorting	Property	The sort order of items in the control from SortOrder : Ascending, Descending, or None (default).
View	Property	Represents the way items are displayed. The values are specified by the View enumeration: Details (items are displayed with multicolumn information about them), LargeIcon (the default value; the items appear with a large icon and a label below them in multiple columns), List (single-column list with small icons displayed with a label to the right), and SmallIcon (small icons with a label on the right displayed in multiple columns).

Timer, TrackBar, and ProgressBar

Several progress- related controls are important to know well. The Timer control is used when an event needs to occur after a particular interval. This is the preferred method for handling timer requirements within a form, rather than using the class System.Timers.Timer , which fires from another thread and may cause unpredictable results. Table 2.20 details the important members of the Timer class.

Table 2.20. Important Members of the Timer Class

Member	Type	Description
Enabled	Property	Indicates whether the timer is currently running
Interval	Property	The time in milliseconds between Tick events of the timer
Start	Method	Starts the Timer control
Stop	Method	Stops the Timer control
Tick	Event	Occurs when the timer interval elapses and the timer is enabled

The TrackBar control is used to allow a user to select a value from a range by sliding the scroll bar along the displayed scale. The ProgressBar control is used in order to display progress during a lengthy operation. Figure 2.9 provides an example of the use of the TrackBar and ProgressBar controls.

Figure 2.9. The TrackBar and ProgressBar controls display the progress and slide bar selection.

Table 2.21 details the important members of the TrackBar class, and Table 2.22 details those of the ProgressBar class.

Table 2.21. Important Members of TrackBar Class

Member	Type	Description
LargeChange	Property	Specifies the number of units the value changes when the scroll box is moved a large distance.
Maximum	Property	The upper bound of the track bar's range.
Minimum	Property	The lower bound of the track bar's range.
Orientation	Property	Specifies the orientation of the control (Horizontal or Vertical).
Scroll	Event	The default event, which occurs when the scroll box is moved by a keyboard or mouse action.
SmallChange	Property	Specifies the number of units the value changes when the scroll box is moved a small distance.
TickFrequency	Property	The frequency within which scale ticks are drawn in the control.
TickStyle	Property	The way in which the control appears. The values are specified by the TickStyle enumeration: Both, BottomRight, None, or TopLeft.
Value	Property	The scroll box's current position in the control.
ValueChanged	Property	Occurs when the Value property changes.

Table 2.22. Important Members of the ProgressBar Class

Member	Type	Description
Maximum	Property	The upper bound of the control's value
Minimum	Property	The lower bound of the control's value
Value	Property	The current position of the control

HScrollBar and VScrollBar

The HScrollBar and VScrollBar controls are members of the ScrollBar class and are used in combination with other controls, such as the PictureBox control, in order to provide basic scrolling capabilities. Table 2.23 details the important members of the ScrollBar class, which are inherited by both the HScrollBar and VScrollBar controls.

Table 2.23. Important Members of the ScrollBar Class

Member	Type	Description
LargeChange	Property	Specifies the amount the value changes when the scroll box is moved a large distance
Maximum	Property	The upper bound of the control's value
Minimum	Property	The lower bound of the control's value
Scroll	Event	The default event, which occurs when the scroll box is moved by a keyboard or mouse action
SmallChange	Property	The amount the value changes when the scroll box is moved a small distance
Value	Property	The current position of the control
ValueChanged	Event	Occurs when the Value property changes

TabControl

The TabControl can contain other controls, arranged on tabbed pages. This control is useful in organizing large numbers of controls within a manageable format. Visual Studio itself relies on a tabbed display format. Table 2.24 details the important members of the TabControl class.

Table 2.24. Important Members of the TabControl Class

Member	Type	Description
Alignment	Property	The area where the tabs will be aligned: Bottom, Left, Right, or Top (default)
ImageList	Property	The image list from which images are displayed on tabs
MultiLine	Property	Specifies whether tabs can be displayed in multiple rows
SelectedIndex	Property	The index of the selected tab page
SelectedIndexChanged	Property	The default event, which occurs when the selected index changes
SelectedTab	Property	The selected tab page
TabCount	Property	The count of tabs in the control
TabPages	Property	The collection of tab pages in the control

ToolTips

A ToolTip is a feature that allows an application to provide additional information relevant to a control when the user hovers his or her cursor over the control. Some controls have a ToolTipText property, such as the StatusBarPanel, ToolBarButton, and TabControl. For other controls, you must add a ToolTip component in the container object. For each control, you will find a new property named "ToolTip on ComponentName ," where ComponentName is the name of the ToolTip component you added to the container previously. Entering the ToolTip message into this property's value will provide the ToolTip functionality needed for each control.