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