Programming Visual Basic .NET by Dave Grundgeiger

Get full access to Programming Visual Basic .NET and 60K+ other titles, with a free 10-day trial of O'Reilly.

There are also live events, courses curated by job role, and more.

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:

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, .

Indicates whether a property is typically usable for data binding. Specify to indicate that the property can be used for data binding or 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.

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

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, . 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:

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

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

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

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

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

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

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

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

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

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

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

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 .

Indicates the name of the event that is to be considered the default event of a component. For example, . 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.

Indicates the name of the property that is to be considered the default property of a component. For example, . 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.

Indicates the default value of a property. For example, . 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.

Provides a description for the code element. For example, . The IDE uses this description in tool tips and IntelliSense.

Identifies the class that acts as the designer for a component. For example, . 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.

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

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

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

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.

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:

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

The property should always be visible within the editor.

The property should never be shown within the editor.

Indicates whether a type declaration defines a state that can change after an object of that type is constructed. Specify to indicate that an object of the given type is immutable. Specify 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.

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

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

Indicates the license provider for a component.

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

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

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 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 is the same as omitting the attribute altogether.

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

Indicates whether the property name should be parenthesized in the Properties window. Specify to indicate that the property name should appear within parentheses. Specify to indicate that the property name should not appear within parentheses. Omitting the attribute is the same as specifying .

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.

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

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

Indicates whether a property is read-only at design time. Specify to indicate that the property is read-only at design time. Specify 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 .

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

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

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.

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.

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

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

Get Programming Visual Basic .NET now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.