Programming Visual Basic .NET

Component Attributes

As explained in Chapter 2, attributes can be added to code elements to provide additional information about those elements. The System.ComponentModel namespace defines several attributes for use in component, control, and form declarations. These attributes don’t affect component behavior. Rather, they provide information that is used or displayed by the Visual Studio .NET IDE. The following is a description of each attribute:

AmbientValueAttribute

For ambient properties, specifies the property value that will mean “get this property’s actual value from wherever ambient values come from for this property.” Ambient properties are properties able to get their values from another source. For example, the BackColor property of a Label control can be set either to a specific Color value or to the special value Color.Empty, which causes the Label’s background color to be the same as the background color of the form on which it is placed.

Putting this attribute on a property definition isn’t what causes the property to behave as an ambient property: the control itself must be written such that when the special value is written to the property, the control gets the actual value from the appropriate location. This attribute simply provides the Windows Forms Designer with a way to discover what the special value is.

When specifying this attribute, pass the special value to the attribute’s constructor. For example, <AmbientValue(0)>.

BindableAttribute

Indicates whether a property is typically usable for data binding. Specify <Bindable(True)> to indicate that the property can be used for data binding or <Bindable(False)> to indicate that the property typically is not used for data binding. This attribute affects how a property is displayed in the IDE, but does not affect whether a property can be bound at runtime. By default, properties are considered not bindable.

BrowsableAttribute

Indicates whether a property should be viewable in the IDE’s Properties window. Specify <Browsable(True)> to indicate that the property should appear in the Properties window or <Browsable(False)> to indicate that it should not. By default, properties are considered browsable.

CategoryAttribute

Indicates the category to which a property or event belongs (“Appearance,” “Behavior,” etc.). The IDE uses this attribute to sort the properties and events in the Properties window. Specify the category name as a string argument to the attribute. For example, <Category("Appearance")>. The argument can be any string. If it is not one of the standard strings, the Properties window will add a new group for it. The standard strings are:

Action

Used for events that indicate a user action, such as the Click event.

Appearance

Used for properties that affect the appearance of a component, such as the BackColor property.

Behavior

Used for properties that affect the behavior of a component, such as the AllowDrop property.

Data

Used for properties that relate to data, such as the DecimalPlaces property of the NumericUpDown control.

Design

Used for properties that relate to the design-time appearance or behavior of a component.

DragDrop

Used for properties and events that relate to drag and drop. No Windows Forms components have any properties or events marked with this category.

Focus

Used for properties and events that relate to input focus, such as the CanFocus property and the GotFocus event.

Format

Used for properties and events that relate to formats. No Windows Forms components have any properties or events marked with this category.

Key

Used for events that relate to keyboard input, such as the KeyPress event.

Layout

Used for properties and events that relate to the visual layout of a component, such as the Height property and the Resize event.

Mouse

Used for events that relate to mouse input, such as the MouseMove event.

WindowStyle

Used for properties and events that relate to the window style of top-level forms. No Windows Forms components have any properties or events marked with this category.

If no CategoryAttribute is specified, the property is considered to have a category of Misc.

DefaultEventAttribute

Indicates the name of the event that is to be considered the default event of a component. For example, <DefaultEvent("Click")>. When a component is double-clicked in the Windows Forms Designer, the designer switches to code view and displays the event handler for the default event. This attribute can be used only on class declarations.

DefaultPropertyAttribute

Indicates the name of the property that is to be considered the default property of a component. For example, <DefaultProperty("Text")>. This attribute can be used only on class declarations. The default property is the property that the Windows Forms Designer highlights in the Properties window when a component is clicked in design view.

Tip

Don’t confuse this usage of the term default property with the usage associated with the Default modifier of a property declaration. The two concepts are unrelated. Refer to Chapter 2 for details on the Default modifier.

DefaultValueAttribute

Indicates the default value of a property. For example, <DefaultValue(0)>. If the IDE is used to set a property value to something other than the default value, the code generator will generate the appropriate assignment statement in code. However, if the IDE is used to set a property to the default value, no assignment statement is generated.

DescriptionAttribute

Provides a description for the code element. For example, <Description("The text contained in the control.")>. The IDE uses this description in tool tips and IntelliSense.

DesignerAttribute

Identifies the class that acts as the designer for a component. For example, <Designer("MyNamespace.MyClass")>. The designer class must implement the IDesigner interface. This attribute can be used only on class declarations and is needed only if the built-in designer isn’t sufficient. Creating custom designers is not discussed in this book.

DesignerCategoryAttribute

Used with custom designers to specify the category to which the class designer belongs.

DesignerSerializationVisibilityAttribute

Used with custom designers to specify how a property on a component is saved by the designer.

DesignOnlyAttribute

Indicates when a property can be set. Specify <DesignOnly(True)> to indicate that the property can be set at design time only or <DesignOnly(False)> to indicate that the property can be set at both design time and runtime (the default).

EditorAttribute

Identifies the “editor” to use in the IDE to allow the user to set the values of properties that have the type on which the EditorAttribute attribute appears. In this way, a component can declare new types and can declare properties having those types, yet still allow the user to set the values of the properties at design time. Creating custom type editors is not discussed in this book.

EditorBrowsableAttribute

Indicates whether a property is viewable in an editor. The argument to the attribute’s constructor must be one of the values defined by the EditorBrowsableState enumeration (defined in the System.ComponentModel namespace). The values of this enumeration are:

Advanced

Only advanced users should see the property. It is up to the editor to determine when it’s appropriate to display advanced properties.

Always

The property should always be visible within the editor.

Never

The property should never be shown within the editor.

ImmutableObjectAttribute

Indicates whether a type declaration defines a state that can change after an object of that type is constructed. Specify <ImmutableObject(True)> to indicate that an object of the given type is immutable. Specify <ImmutableObject(False)> to indicate that an object of the given type is not immutable. The IDE uses this information to determine whether to render a property as read-only.

InheritanceAttribute

Used to document an inheritance hierarchy that can be read using the IInheritanceService interface. This facility is not discussed in this book.

InstallerTypeAttribute

Used on type declarations to specify the installer for the type. Installers are not discussed in this book.

LicenseProviderAttribute

Indicates the license provider for a component.

ListBindableAttribute

Indicates whether a property can be used as a data source. (A data source is any object that exposes the IList interface.) Specify <ListBindable(True)> to indicate that the property can be used as a data source. Specify <ListBindable(False)> to indicate that the property can’t be used as a data source.

LocalizableAttribute

Indicates whether a property’s value should be localized when the application is localized. Specify <Localizable(True)> to indicate that the property’s value should be localized. Specify <Localizable(False)> or omit the LocalizableAttribute attribute to indicate that the property’s value should not be localized. The values of properties declared with <Localizable(True)> are stored in a resource file, which can be localized.

MergablePropertyAttribute

Indicates where property attributes can be merged. By default, when two or more components are selected in the Windows Forms Designer, the Properties window typically shows the properties that are common to all of the selected components. If the user changes a value in the Properties window, the value is changed for that property in all of the selected components. Placing <MergableProperty(False)> on a property declaration changes this behavior. Any property declared in this way is omitted from the Properties window when two or more components are selected. Specifying <MergableProperty(True)> is the same as omitting the attribute altogether.

NotifyParentPropertyAttribute

Indicates whether the display of a property’s parent property should be refreshed when the given property changes its value.

ParenthesizePropertyNameAttribute

Indicates whether the property name should be parenthesized in the Properties window. Specify <ParenthesizePropertyName(True)> to indicate that the property name should appear within parentheses. Specify <ParenthesizePropertyName(False)> to indicate that the property name should not appear within parentheses. Omitting the attribute is the same as specifying <ParenthesizePropertyName(False)>.

The only benefit to parenthesizing property names in the property window is that they are sorted to the top of the list. Microsoft has no specific recommendations for when to parenthesize a property name.

PropertyTabAttribute

Specifies a type that implements a custom property tab (or tabs) for a component. This facility is not discussed in this book.

ProvidePropertyAttribute

Used with extender providers —i.e., classes that provide properties for other objects. Extender providers are not discussed in this book.

ReadOnlyAttribute

Indicates whether a property is read-only at design time. Specify <ReadOnly(True)> to indicate that the property is read-only at design time. Specify <ReadOnly(False)> to indicate that the property’s ability to be modified at design time is determined by whether a Set method is defined for the property. Omitting the attribute is the same as specifying <ReadOnly(False)>.

RecommendedAsConfigurableAttribute

Indicates whether a property is configurable. Configurable properties aren’t discussed in this book.

RefreshPropertiesAttribute

Determines how the Properties window is refreshed when the value of the given property changes.

RunInstallerAttribute

Indicates whether an installer should be invoked during installation of the assembly that contains the associated class. This attribute can be used only on class declarations, and the associated class must inherit from the Installer class (defined in the System.Configuration.Install namespace). Installers are not discussed in this book.

ToolboxItemAttribute

Specifies a type that implements a toolbox item related to the declaration on which the attribute is placed. This facility is not discussed in this book.

ToolboxItemFilterAttribute

Specifies a filter string for a toolbox-item filter. This facility is not discussed in this book.

TypeConverterAttribute

Indicates the type converter to be used with the associated item. Type converters are not discussed in this book.