Design-Time Attributes

Your control does not require design-time attributes to function in a page. However, design-time attributes are essential for your control to function properly in a visual designer. The designer, the property browser, and other design-time elements use the metadata supplied by design-time attributes for the following purposes:

• To display properties and events

• To perform design-time serialization

• To associate classes that implement design-time functionality with a control or with a property type

In the following subsections, we'll group design-time attributes according to their functionality.

Attributes for Displaying Properties and Events

The following attributes are used to display properties and events at design time.

Table A-1. System.ComponentModel.BindableAttribute

Summary	Tells the property browser whether it is meaningful to bind data to the property. Properties marked with Bindable(true) are displayed in the DataBinding dialog box that can be launched from the property browser and used by the page developer to associate data-binding expressions with properties.
Applied to	Properties only
Sample usage	[Bindable(true)]
Parameter type	Boolean
Default value	false
Example	The ContactInfo control in Listing 12-7
Remarks	If a property is not marked with Bindable(true) , a page developer can still associate a data-binding expression with the property by manually entering the expression in the .aspx page.

Table A-2. System.ComponentModel.BrowsableAttribute

Summary	Tells the property browser whether to display the property or event in the property browser.
Applied to	Properties and events
Sample usage	[ Browsable (false)]
Parameter type	Boolean
Default value	true
Example	The PageTracker control in Listing 7-4
Remarks	The property browser displays all public properties and events by default. Apply this attribute only if you want to override the default behavior.

Table A-3. System.ComponentModel.CategoryAttribute  

Summary	Provides a category name under which to display the property or event. This attribute enables the property browser to display properties and events in logical groupings.
Applied to	Properties and events
Sample usage	[Category("Behavior")]
Parameter type	String
Default value	"Default"
Example	The PageTracker control in Listing 7-4
Remarks	This attribute can be localized, as described in Chapter 17, "Localization, Licensing, and Other Miscellany."

Table A-4. System.ComponentModel.DefaultEventAttribute

Summary	Tells the property browser which control event is its default event. This allows the page developer to write event-handling code for the default event by double-clicking the control on the design surface.
Applied to	Events only
Sample usage	[DefaultEvent("Click")]
Parameter type	String
Default value	None
Example	The SimpleButton control in Listing 9-3

Table A-5. System.ComponentModel.DefaultPropertyAttribute

Summary	Tells the property browser which control property is its default property. When the page developer selects the control on the design surface, the property browser highlights that property.
Applied to	Properties only
Sample usage	[DefaultProperty("TrackingMode")]
Parameter type	String
Default value	None
Example	The PageTracker control in Listing 7-4

Table A-6. System.ComponentModel.DescriptionAttribute

Summary	Provides a brief description, which the property browser displays when the user selects the property or event.
Applied to	Properties and events
Sample usage	[Description("The type of tracking to perform")]
Parameter type	String
Default value	None
Example	The PageTracker control in Listing 7-4
Remarks	This attribute can be localized, as described in Chapter 17.

Table A-7. System.ComponentModel.EditorBrowsableAttribute

Summary	Tells the code editor whether to display IntelliSense support for a property, method, or event.
Applied to	Properties, methods , and events
Sample usage	[EditorBrowsable(EditorBrowsableState.Never)]
Parameter type	An EditorBrowsableState enumeration that has the following values: Advanced Browsable only when the developer wants to view advanced members . This setting is used by the Microsoft Visual Basic .NET code editor. Always Always browsable in the code editor. Never Never browsable in the code editor.
Default value	EditorBrowsableState.Always
Example	The HitTracker control in Listing 9-13
Remarks	The code editor displays IntelliSense support by default. Apply this attribute only if you want to override the default behavior.

Attributes for Design-Time Serialization

These attributes tell the designer how to serialize the control and its properties. Serialization is the process of generating HTML in the page corresponding to the changes in the Design view.

Table A-8. System.ComponentModel.DefaultValueAttribute

Summary	Provides a default value for the property.
Applied to	Properties
Sample usage	[DefaultValue(BorderStyle.NotSet)]
Parameter type	Any primitive type, enumeration, or string literal. See this attribute's remarks to provide a default value for a complex property.
Default value	None
Example	The LoginUI control in Listing 8-6
Remarks	You can provide a default value for a complex property if the property type has an associated type converter. In that case, you must use the two-parameter form of the attribute, in which the first parameter specifies the type of the property and the second specifies a string representation of the value ”for example, [DefaultValue(typeof(Color), "Black")] .

Table A-9. System.ComponentModel.DesignerSerializationVisibilityAttribute

Summary	Tells the designer whether to serialize the property or the contents of the property. A complex property has contents ”that is, subproperties or collection items.
Applied to	Properties
Sample usage	[DesignerSerializationVisibility(DesignerSerializationVisibility.Content)]
Parameter type	The DesignerSerializationVisibility enumeration that has the following values: Content Causes the contents of the property (such as its subproperties or collection items) to be serialized. Hidden Hides the property from the serialization mechanism. Visible Serializes the value of the property.
Default value	DesignerSerializationVisibility.Visible
Example	The MapDemo control in Listing 10-6
Remarks	By default, the code generator serializes the value of the property. This attribute allows you either to override the default behavior and exclude a property from the serialization mechanism, or to serialize the contents of the property (such as its subproperties or collection items) instead of the property itself.

Table A-10. System.ComponentModel.NotifyParentPropertyAttribute

Summary	Tells the property browser to bubble change notifications from a subproperty to the parent property or to the control.
Applied to	Complex properties and their subproperties
Sample usage	[NotifyParentProperty(true)]
Parameter type	Boolean
Default value	false
Example	The MapDemo control in Listing 10-6

Table A-11. System.Web.UI.PersistChildrenAttribute  

Summary	Tells the designer whether the nested content within the control's tags corresponds to child controls or to properties.
Applied to	Controls
Sample usage	[PersistChildren(false)]
Parameter type	Boolean
Default value	A value of true implies that the nested content corresponds to children.
Remarks	WebControl is marked with PersistChildren(false) . If your control derives from WebControl , you need to reapply this attribute only if you are implementing a control whose nested content corresponds to child controls.

Table A-12. System.Web.UI.PersistenceModeAttribute

Summary	Tells the designer whether to persist a property on the control's tag or as a nested property.
Applied to	Properties
Sample usage	[PerisistenceMode(PersistenceMode.InnerProperty)]
Parameter type	The PersistenceMode enumeration that has the following values: Attribute Causes the property to be persisted as an attribute on the control's tag. EncodedInnerDefaultProperty Causes the property to be persisted as the only content within the control's tags. The content is HTML encoded. InnerDefaultProperty Causes the property to be persisted as the only content within the control's tags. InnerProperty Causes the property to be persisted, along with any other properties of the control, as nested content within the control's tags.
Default value	PersistenceMode.Attribute
Example	The MapDemo control in Listing 10-6

Table A-13. System.Web.UI.TagPrefixAttribute  

Summary	Tells the designer to generate a Register directive that maps a tag prefix to a namespace and an assembly. The directive is generated in the .aspx page when the page developer drags the control from the toolbox onto the design surface.
Applied to	Assemblies that contain server controls
Sample usage	[assembly:TagPrefix("MSPress.ServerControls", "msp")]
Parameters	The first parameter specifies the namespace name, and the second parameter allows y0ou to specify a tag prefix (analogous to asp ) for the controls in your assembly.
Example	The "Applying TagPrefixAttribute " section in Chapter 5, "Developing a Simple Custom Control."
Remarks	The Register directive is generated only if the page developer drags the control from the toolbox onto the design surface. The directive is not generated if the page developer manually adds the HTML for the control to the page.

Attributes for Associating Classes That Provide Advanced Design-Time Functionality

These attributes enable you to associate classes that provide advanced design-time functionality with your control.

Table A-14. System.ComponentModel.DesignerAttribute

Summary	Associates a designer with a control.
Applied to	Controls
Sample usage	[Designer(typeof(ScrollablePanelDesigner)]
Example	The ScrollablePanel control in Listing 15-4
Remarks	The example shows an early-bound type reference to the designer. Chapter 15, "Design-Time Functionality," describes the syntax for a late-bound type reference, which is needed when the designer and the control reside in different assemblies.

Table A-15. System.ComponentModel.EditorAttribute

Summary	Associates a UI type editor with a type or a property. Also associates a component editor with a control.
Applied to	Classes or properties
Sample usage	[Editor(typeof(MSPress.ServerControls.Design.StringEditor), typeof(UITypeEditor))] or [Editor(typeof(MSPress.ServerControls.Design.MyLabelComponent ­Editor), typeof(ComponentEditor))]
Example	The MyLabel control in Listing 15-6
Remarks	The first argument is the type of the editor, and the second is the base type of the editor. The example shows an early-bound type reference to an editor. Chapter 15 describes the syntax for a late-bound type reference, which is needed when the editor and the type (or control) reside in different assemblies.

Table A-16. System.ComponentModel.TypeConverterAttribute

Summary	Associates a type converter with a type or a property.
Applied to	Classes and properties
Sample usage	[TypeConverter(typeof(MapCircleConverter))]
Example	The MapCircle type in Listing 10-5
Remarks	The example shows an early-bound type reference to a type converter. Chapter 15 describes the syntax for a late-bound type reference, which is needed when the type converter and the type (or control) reside in different assemblies.