Property Window Attributes
Microsoft has defined a fairly large assortment of attributes to give extra information to the Properties window. They give hints about how the window should display information about properties and how to interact with pieces of your code. These attributes are defined in the System.ComponentModel namespace so you can make your life a little easier if you Import
that namespace before you get started.
The PropertyGrid control is basically its own little Properties window so it also honors these attributes (mostly). That means, for example, that if you create a Customer class and let the user modify Customer objects at run time in a PropertyGrid, you can use these attributes to influence how the control behaves.
The following list describes some of the most useful of the property-oriented attributes.
This tells the Properties window whether to display a property. If you set this to False
, code can get and set the property at run time but developers cannot see or change the value in the Properties window. For example, the following code makes the Price
Public Property Price() As Decimal
This sets the category in which the Properties window will group a property or event when displaying items grouped by category rather than sorted alphabetically. You can put any string in the constructor; the Properties window will create a new category if one with that name doesn't already exist.
This tells designers which of this class's events is most commonly used. If you double-click on an object in the form designer, for example, the code editor opens to this event. If you click the Properties window's Events button and then select an object from this class, it's also the event that the window initially selects.
This sets a default value for a property. If you right-click the property in the Properties window and select Reset, the property gets this value. This is particularly useful for properties that take objects as values because you can't just type a new value into the property. Normally you set an object's default value to Nothing
as in the following code.
<DefaultValue(GetType(Image), "Nothing")> _
Public Property Picture() As Image
This gives the description that the Properties window displays for a property.
This indicates whether the property should be localizable. If you set this to True
, then Visual Studio automatically saves the property's value in localized resource files rather than in the form's shared resource file.
This tells the Properties window whether to surround the property's name with parentheses. Parenthesized properties are shown at the top of the windowor at the top of their category if the list is grouped by category.
This tells the Properties window that a property is read-only. The window displays the property grayed out and doesn't let users change its value. Because ReadOnly
is also a Visual Basic keyword, you must enclose this attribute's name in square brackets so Visual Basic doesn't get confused.
Note that you can achieve a similar effect by creating a read-only property as in the following code:
Public ReadOnly Property FirstNameLast() As String
The difference is that when you use the [ReadOnly] attribute, you can define both property get and set routines in the code, meaning that code can set and retrieve the property at run time but the Properties window won't let developers set it at design time. In contrast, when you create a read-only property, you can't set the value from code either.
This tells the Properties window whether it should refresh the object's other properties whenever this property's value changes. For example, suppose an Employee class has FirstName
properties. Suppose it also provides a FullName
property that gets and sets both of those properties in the format "FirstName LastName." If a developer changes either the FirstName
value, then the Properties window must update its display of the FullName
property. Similarly if the developer changes the FullName
value, the window must update its FirstName
values. To force these updates to occur, you can set the RefreshPropertiesAttribute to True
for all three properties.
|Figure 1. Employee Object Properties: The figure shows the property-related attributes in action in the Properties pane in Visual Studio.|
This sets which bitmap the IDE will use to display an object of this class in the Toolbox or in a form's component tray. (Okay, this isn't exactly a property attribute but it's close.) Unfortunately this attribute is a bit tricky to use. The most straightforward of its overloaded constructors takes a parameter giving the full path to the bitmap file to use. However, because you can't always count on an external bitmap file being present, a more flexible (but more confusing) version takes the type of a class in the assembly containing a bitmap resource plus the name of the resource. To use this version, you must also set the resource's Build Action
property to Embedded Resource
This tells the IDE whether to display an icon for a control or component in the Toolbox (another non-property attribute). This attribute is useful if you want to create a control for your own use but don't want to make it easily available to developers using your library. If you set this attribute to False
, your code can use it but it won't appear in the Toolbox.
shows an Employee class that demonstrates most of these properties. You'll find the class in the downloadable sample code for this article
that you can experiment with to see how the attributes affect the Properties window at design time and the program's PropertyGrid control at run time.
shows a program with a PropertyGrid control displaying the properties for an Employee object. At the bottom you can see the description for the FullName
property specified by a Description attribute. The Manager
property uses a ParenthesizePropertyName
attribute so it's surrounded by parentheses and at the top of its section. Several of the properties use the Category attribute so they appear in the Misc
sections. The LastNameFirst
property is ReadOnly
while the FirstNameLast
property uses the [ReadOnly]
attributeso in the PropertyGrid they look the same. Finally, the FirstName
, and FullName
properties use the RefreshProperties attribute so they all get updated if any of them changes.