Properties

A property is some value associated with a control. Often, a property corresponds in an obvious way to one of the control’s visual or behavioral features. For example, the Text property represents the text that the control displays, BackColor represents the control’s background color, Top and Left represent the control’s position, and so forth.

Many properties, including Text, BackColor, Top, and Left, apply to many kinds of controls. Other properties only work with certain specific types of controls. For example, the ToolStrip control has an ImageList property that indicates the ImageList control containing the images the ToolStrip should display.

You can manipulate a control’s properties interactively at design time or using code at runtime.

Properties at Design Time

To modify a control’s properties at design time, open its form in the Form Designer and click on the control. The Properties window displays the control’s properties. Figure 2-5 shows the Properties window displaying a Button control’s properties. For example, the control’s Text property has the value Make Hi Button, and its TextAlign property (which determines where the button displays its text) is set to MiddleCenter.

Figure 2-5: The Properties window lets you change a control’s properties at design time.

The drop-down list at the top of the Properties window, just below the Properties title, indicates that this control is named btnMakeHiButton and that it is of the System.Windows.Forms.Button class.

You can set many properties by clicking on a property’s value in the Properties window and then typing the new value. This works with simple string values such as the controls’ name and Text property, and it works with some other properties where typing a value makes some sense.

For example, the HScrollBar control (horizontal scrollbar) has Minimum, Maximum, and Value properties that determine the control’s minimum, maximum, and current values. You can click those properties in the Properties window and enter new values. When you press the Enter key or move to another property, the control validates the value you typed. If you entered a value that doesn’t make sense (for example, if you typed ABC instead of a numeric value), the IDE reports the error and lets you fix it.

Compound Properties

A few properties have compound values. The Location property includes the X and Y coordinates of the control’s upper-left corner. The Size property contains the control’s width and height. The Font property includes the font’s name, size, boldness, and other font properties.

The Properties window displays these properties with a plus sign on the left. When you click the plus sign, the window expands the property to show the values that it contains. Figure 2-6 shows the same Properties window shown in Figure 2-5 with the Font and Location properties expanded. You can click these subvalues and set them independently just as you can set any other property value.

Figure 2-6: The Properties window lets you change even complex properties at design time.

When you expand a compound property, a minus sign appears to the left (see the Font and Location properties in Figure 2-6). Click this minus sign to collapse the property and hide its members.

In some cases, you can also set a compound property’s values in a single step. The Location property shown in Figure 2-6 has the value “8, 8.” You can type a new value (such as “16, 8”) directly into the Property window.

Some compound properties provide more sophisticated methods for setting the property’s values. If you click the ellipsis button to the right of the Font property shown in Figure 2-6, the IDE presents the font selection dialog box shown in Figure 2-7. You can use this dialog box to set many of the font’s properties.

Figure 2-7: The Font property displays a dialog box that lets you set the font’s properties.

Restricted Properties

Some properties allow more restricted values. For example, the Visible property is a Boolean, so it can only take the values True and False. When you click the property, a drop-down arrow appears on the right. When you click this arrow, the window displays a drop-down list where you can select one of the choices, True or False.

Many properties have enumerated values. The Button control’s FlatStyle property allows the values Flat, Popup, Standard, and System. When you click the drop-down arrow to the right of this property, you’ll see the list shown in Figure 2-8. You can select a new value from this list.

Figure 2-8: Some properties provide an enumerated list of allowed values.

You can also double-click the property to cycle through its allowed values. After you select a property, you can use the up and down arrows to move through the values.

Some properties determine at any given moment exactly what values they can take. For example, some properties contain references to other controls. The Button control’s ImageList property is a reference to an ImageList component that contains the picture that the Button control should display. If you click the drop-down arrow to the right of this value, the Properties window displays a list of the ImageList components on the form that you might use for this property. This list also contains the entry (none), which you can select to remove any previous control reference in the property.

Many properties take very specialized values and provide specialized property editors to let you select values easily. For example, the Anchor property lets you anchor a control’s edges to the edges of its container. Normally, a control is anchored to the top and left edges of the container so that it remains in the same position even if the container is resized. If you also anchor the control on the right, its right edge moves in or out as the container gets wider or narrower. This lets you make controls that resize with their containers in certain useful ways.

If you select the Anchor property and click the drop-down arrow on the right, the Properties window displays the small graphical editor shown in Figure 2-9. Click the skinny rectangles on the left, top, right, or bottom to anchor or unanchor (sometimes called float) the control on those sides. Press the Enter key to accept your choices or press Escape to cancel them.

Figure 2-9: Some properties, such as Anchor, provide specialized editors to let you select their values.

Other complex properties may provide other editors. These are generally self-explanatory. Click the ellipsis or drop-down arrow to the right of a property value, and experiment to see how these editors work.

You can right-click any property and select Reset from its context menu to reset the property to a default value. Many complex properties can take the value “(none),” and for those properties, selecting Reset usually sets the value to “(none).”

Collection Properties

Some properties represent collections of objects. For example, the ListBox control displays a list of items. Its Items property is a collection containing those items. The Properties window displays the value of this property as “(Collection).” If you select this property and click the ellipsis to the right, the Properties window displays a simple dialog box where you can edit the text displayed by the control’s items. This dialog box is quite straightforward: Enter the items’ text on separate lines and click OK.

Other properties are much more complex. For example, to create a TabControl that displays images on its tabs, you must also create an ImageList component. Select the ImageList component’s Images property, and click the ellipsis to the right to display the dialog box shown in Figure 2-10. When you click the Add button, the dialog box displays a file selection dialog box that lets you add an image file to the control. The list on the left shows you the images you have loaded and includes a small thumbnail picture of each image. The values on the right show you the images’ properties.

Figure 2-10: This dialog box lets you load images into an ImageList control at design time.

After you add pictures to the ImageList control, create a TabControl. Select its ImageList property, click the drop-down arrow on the right, and select the ImageList control you created. Next, select the TabControl’s TabPages property, and click the ellipsis on the right to see the dialog box shown in Figure 2-11.

Figure 2-11: This dialog box lets you edit a TabControl’s tab pages.

Select a tab page, click its ImageIndex property, click the drop-down arrow to the right, and pick the number of the image in the ImageList that you want to use for this tab. Figure 2-12 shows the result.

Figure 2-12: A TabControl displays the images stored in an ImageList component on its tabs.

Some properties even contain a collection of objects, each of which contains a collection of objects. For example, the ListView control has an Items property that is a collection. Each item in that collection is an object that has a SubItems property, which is itself a collection. When you display the ListView control as a list with details, an object in the Items collection represents a row in the view and the SubItems property represents the secondary values in a row.

To set these values at design time, select the control and click the ellipsis to the right of the control’s Items property in the Properties window. Create an item in the editor, and click the ellipsis to the right of the item’s SubItems property. Figure 2-13 shows these editors in action. The one in the back is the Items editor; the one in front is the SubItems editor.

Figure 2-13: The objects in the ListView control’s Items collection each have a SubItems property, which is also a collection.

Other complicated properties provide similarly complex editors. Although they may implement involved relationships among various controls and components, they are usually easy enough to figure out with a little experimentation.

Properties at Runtime

Visual Basic lets you set most control properties at design time, but often you will need to view and modify property values at runtime. For example, you might need to change a label’s text to tell the user that something has changed, disable a button because it is not applicable at a particular moment, or read the value selected by the user from a list.

As far as your code is concerned, a property is just like any other public variable defined by an object. You get or set a property by using the name of the control, followed by a dot, followed by the name of the property. For example, the following code examines the text in the TextBox named txtPath. If the text doesn’t end with a / character, the code adds one. This code both reads and sets the Text property.

  If Not txtPath.Text.EndsWith("/") Then txtPath.Text &= "/" 

If a property contains a reference to an object, you can use the object’s properties and methods in your code. The following code displays a message box indicating whether the txtPath control’s font is bold. It examines the TextBox control’s Font property. That property returns a reference to a Font object that has a Bold property.

  If txtPath.Font.Bold Then     MessageBox.Show("Bold") Else     MessageBox.Show("Not Bold") End If 

Note that a Font object’s properties are read-only, so the code cannot set the value of txtPath.Font.Bold. To change the TextBox control’s font, the code would need to create a new font as shown in the following code. This code passes the Font object’s constructor a copy of the TextBox control’s current font to use as a template, and a value indicating that the new font should be bold.

  txtPath.Font = New Font(txtPath.Font, FontStyle.Bold) 

If a property represents a collection or array, you can loop through or iterate over the property just as if it were declared as a normal collection or array. The following code lists the items the user has selected in the ListBox control named lstChoices. (If the ListBox control’s SelectionMode property is set to MuliExtended, the user can select any or all of the items.)

  For Each selected_item As Object In lstChoices.SelectedItems()     Debug.WriteLine(selected_item.ToString) Next selected_item 

A few properties are read-only at runtime, so your code can examine them but not change their values. For example, a Panel control’s Controls property returns a collection holding references to the controls inside the Panel. This property is read-only at runtime so you cannot set it equal to a new collection. Note that the collection provides methods for adding and removing controls so you don’t really need to replace the whole collection, you can change the controls that it contains instead.

Note also that at design time, this collection doesn’t appear in the Properties window. Instead of explicitly working with the collection, you add and remove controls interactively by dropping them in and out of the Panel control.

A control’s Bottom property is also read-only and not shown in the Properties window. It represents the distance between the top of the control’s container and the control’s bottom edge. This value is really just the control’s Top property plus its Height property (control.Bottom = control.Top + control.Height), so you can modify it using those properties instead of setting the Bottom property directly.

In theory, a property can also be write-only at runtime. Such a property is really more like a method than a property, however, so most controls use a method instead. In practice, read-only properties are uncommon and write-only properties are extremely rare.

Useful Control Properties

Appendix A summarizes the Control class’s most important properties.

All controls (including the Form control) inherit directly or indirectly from the Control class. That means they inherit the Control class’s properties, methods, and events, unless they take action to override the Control class’s behavior.

Although these properties are available to all controls that inherit from the Control class, many are considered advanced, so they are not shown by the IntelliSense pop-up’s Common tab. For example, a program is intended to set a control’s position by using its Location property not its Left and Top properties, so Location is in the Common tab while Left and Top are only in the Advanced tab.

Figure 2-14 shows the Common tab on the IntelliSense pop-up for a Label control. It shows the Location property but not the Left property. If you click the All tab, you can see Left and the other advanced properties. When you type the control’s name and enough of the string Left to differentiate it from the Location property (in this case lblDirectory.Le), the pop-up automatically switches to the All tab.

Figure 2-14: The Location property is on the IntelliSense Common tab but the Left property is not.

Many of the properties described in the previous list are straightforward, but a few deserve special attention. The following sections describe some of the more confusing properties in greater detail.

Anchor and Dock

The Anchor and Dock properties allow a control to automatically resize itself when its container is resized. The Anchor property determines which of the control’s edges should remain a fixed distance from the corresponding edges of the container.

For example, normally a control’s Anchor property is set to Top, Left. That means the control’s top and left positions remain fixed when the container resizes. If the control’s upper-left corner is at the point (8, 16) initially, it remains at the position (8, 16) when you resize the container. This is the normal control behavior, and it makes the control appear fixed on the container.

For another example, suppose that you set a control’s Anchor property to Top, Right, and you place the control in the container’s upper-right corner. When you resize the container, the control moves, so it remains in the upper-right corner.

If you set two opposite Anchor values, the control resizes itself to satisfy them both. For example, suppose that you make a button that starts 8 pixels from its container’s left, right, and top edges. Then suppose that you set the control’s Anchor property to Top, Left, Right. When you resize the container, the control resizes itself so that it is always 8 pixels from the container’s left, right, and top edges.

In a more common scenario, you can place Label controls on the left with Anchor set to Top, Left so they remain fixed on the form. On the right, you can place TextBoxes and other controls with Anchor set to Top, Left, Right, so they resize themselves to take advantage of the resizing form’s new width.

Figure 2-15 shows a New Customer dialog box. The Labels, state ComboBox, and ZIP code TextBox controls all have Anchor set to Top, Left so they do not move when the form resizes. The two buttons have Anchor set to Top, Right, so they keep their positions relative to the upper-right corner of the form. The First Name, Last Name, Street, and City TextBox controls have Anchor set to Top, Left, Right, so they resize themselves to fill in whatever space is between the labels and the buttons. This arrangement lets the TextBox controls use as much of the form’s available space as possible. The Anchor properties are set at design time and do all the work automatically, so you don’t need to write any extra code to rearrange the controls at runtime.

Figure 2-15: This dialog box uses Anchor properties to make its TextBox controls use whatever space is available on the form.

Similarly, you can make controls that stretch vertically as the form resizes. Figure 2-16 shows a form listing customer orders. The upper ListView control has Anchor set to Top, Left, Right, so it keeps its initial height and fills the width of the form. The bottom ListView has Anchor set to Top, Bottom, Left, Right. It fills the width of the form and fills the form from its initial Top position to the bottom of the form. If the user makes the form taller, the control resizes itself to use the available space.

Figure 2-16: The bottom ListView control resizes itself to use up any extra verticalspace on the form.

If you do not provide any Anchor value for either the vertical or horizontal directions, the control anchors its center to the container’s center. For example, suppose that you position a button in the bottom middle of the form and you set Anchor to Bottom (omitting Left and Right). Because you placed the control in the middle of the form, the control’s center coincides with the form’s center. When you resize the form, the control moves so it remains centered horizontally.

If you place other controls on either side of the centered one, they will all move so they remain together centered as a group as the form resizes. Figure 2-17 shows a form containing a group of controls with Anchor set to Bottom. You may want to experiment with this property to see the effect.

Figure 2-17: Controls with Anchor set to Bottom remain centered as a group.

At runtime, you can set a control’s Anchor property to AnchorStyles.None or to a Boolean combination of the values AnchorStyles.Top, AnchorStyles.Bottom, AnchorStyles.Left, and AnchorStyles .Right. For example, the following code moves the Button1 control to the form’s lower-right corner and sets its Anchor property to Bottom, Right, so it stays there.

  Private Sub Form1_Load(ByVal sender As System.Object, _  ByVal e As System.EventArgs) Handles MyBase.Load     Button1.Location = New Point( _         Me.ClientRectangle.Width - Button1.Width, _         Me.ClientRectangle.Height - Button1.Height)     Button1.Anchor = AnchorStyles.Bottom Or AnchorStyles.Right End Sub 

Dock

The Dock property determines whether a control attaches itself to one or more of its container’s sides. For example, if you set a control’s Dock property to Top, the control docks to the top of its container. It fills the container from left to right and is flush with the top of the container. If the container is resized, the control remains at the top, keeps its height, and resizes itself to fill the container’s width. This is how a typical toolbar behaves. The effect is similar to placing the control at the top of the container so that it fills the container’s width and then setting the Anchor property to Top, Left, Right.

You can set a control’s Dock property to Top, Bottom, Left, Right, Fill, or None. The value Fill makes the control dock to all of its container’s remaining interior space. If it is the only control in the container, that makes it fill the whole container.

If the container holds more than one control with Dock set to a value other than None, the controls are arranged according to their stacking order (also called the Z-order). The control that is first in the stacking order (would normally be drawn first at the back) is positioned first using its Dock value. The control that comes next in the stacking order is arranged second, and so on until all of the controls are positioned.

Figure 2-18 shows four TextBoxes with Dock set to different values. The first in the stacking order has Dock set to Left so it occupies the left edge of the form. The next control has Dock set to Top, so it occupies the top edge of the form’s remaining area. The third control has Dock set to Right, so it occupies the right edge of the form’s remaining area. Finally, the last control has Dock set to Fill so it fills the rest of the form.

Figure 2-18: Docked controls are arranged according to their stacking order.

Controls docked to an edge resize to fill the container in one dimension. For example, a control with Dock set to Top fills whatever width the container has available. A control with Dock set to Fill resizes to fill all of the form’s available space.

Other than that, the Dock property does not arrange controls very intelligently when you resize the container. For example, suppose that you have two controls, one above the other. The first has Dock set to Top and the second has Dock set to Fill. You can arrange the controls so that they evenly divide the form vertically. When you make the form taller, however, the second control, with Dock set to Fill, takes up all of the new space, and the other control remains the same size.

You cannot use the Dock property to make the controls divide the form evenly when it is resized. You cannot use the Anchor property to evenly divide the form either. Instead, you need to use code similar to the following. When the form resizes, this code moves and sizes the two controls TextBox1 and TextBox2 to fill the form, evenly dividing it vertically.

  Private Sub Form1_Load(ByVal sender As Object, _  ByVal e As System.EventArgs) Handles Me.Load     ArrangeTextBoxes() End Sub Private Sub Form1_Resize(ByVal sender As Object, _  ByVal e As System.EventArgs) Handles Me.Resize     ArrangeTextBoxes() End Sub Private Sub ArrangeTextBoxes()     Dim wid As Integer = Me.ClientRectangle.Width     Dim hgt1 As Integer = Me.ClientRectangle.Height \ 2     Dim hgt2 As Integer = Me.ClientRectangle.Height - hgt1     TextBox1.SetBounds(0, 0, wid, hgt1)     TextBox2.SetBounds(0, hgt1, wid, hgt2) End Sub 

When you want to divide a form, the SplitterContainer control can also be useful. The Splitter?Container contains two panels that can hold other controls. The user can drag the divider between the two panels to adjust the size allocated to each.

Position and Size Properties

Controls contain many position and size properties, and the differences among them can be confusing. Some of the more bewildering aspects of controls are the ideas of client area, nonclient area, and display area.

A control’s client area is the area inside the control where you can draw things or place other controls. A control’s nonclient area is everything else. In a typical form, the borders, title bar, and menus are the non-client area. The client area is the space inside the borders and below the menus where you can place controls or draw graphics.

A control’s display area is the client area minus any internal decoration. For example, a GroupBox control displays an internal border and a title. Although you can place controls over these, you normally wouldn’t. The display area contains the space inside the GroupBox’s borders and below the space where the title sits.

The following table describes properties related to the control’s size and position.

Open table as spreadsheet

Property	Data Type	Read/Write	Purpose
Bounds	Rectangle	Read/Write	The control’s size and position within its container including nonclient areas.
ClientRectangle	Rectangle	Read	The size and position of the client area within the control.
ClientSize	Size	Read/Write	The size of the client area. If you set this value, the control adjusts its size to make room for the nonclient area, while giving you this client size.
DisplayRectangle	Rectangle	Read	The size and position of the area within the control where you would normally draw or place other controls.
Location	Point	Read/Write	The position of the control’s upper-left corner within its container.
Size	Point	Read/Write	The control’s size including non-client areas.
Left, Top, Width, Height	Integer	Read/Write	The control’s size and position within its container including nonclient areas.
Bottom, Right	Integer	Read	The position of the control’s lower-right corner within its container.