Adding Properties to Controls

See Also

You implement properties of your ActiveX control by adding property procedures to the code module of the UserControl that forms the basis of your control class.

By default, the only properties your control will have are the extender properties provided by the container. You must decide what additional properties your control needs, and add code to save and retrieve the settings of those properties.

Properties for controls differ in two main ways from properties of other objects you create with Visual Basic.

• Property values are displayed in the Properties window and Properties Pages dialog box at design time.
  
  
• Property values are saved to and retrieved from the container's source file, so that they persist from one programming session to the next.

As a result of these differences, implementing properties for controls has more requirements and options than for other kinds of objects.

Implement Control Properties Using Property Procedures

The most important consequence of the differences listed above is that control properties should always be implemented using property procedures instead of public data members. Otherwise, your control will not work correctly in Visual Basic.

Property procedures are required because you must notify Visual Basic whenever a property value changes. You do this by invoking the PropertyChanged method of the UserControl object at the end of every successful Property Let or Property Set, as shown in the following code fragment.

Private mblnMasked As Boolean

Public Property Get Masked() As Boolean
   Masked = mblnMasked
End Property

Public Property Let Masked(ByVal NewValue As Boolean)
   mblnMasked = NewValue
   PropertyChanged "Masked"
End Property

There are two reasons for notifying Visual Basic that a property value has changed:

• If you don't call PropertyChanged, Visual Basic cannot mark control instances as needing to be saved. They will not get WriteProperties events, and developers who use your control will lose any property values they set at design time.
  
  
• Because property values may be displayed in more than one place, the development environment must be informed when a property value changes, so it can synchronize the values shown in the Properties window, the Property Pages dialog box, and so forth.

Run-Time Properties

Properties that are available only at run time don't need to call the PropertyChanged method, unless they can be data-bound. However, they still need to be implemented using property procedures, as explained in the related topic "Creating Design-Time-Only or Run-Time-Only Properties."

For More Information   Authoring controls that can be bound to data sources is discussed in "Binding Your Control to a Data Source," earlier in this chapter.

Showing Properties in the Properties Window

If you create both a Property Get and a Property Let, your property will automatically be displayed in the Properties window. In some cases, you may not want this.

For example, if displaying a property value requires a time-consuming calculation, the developer who uses your control may be annoyed at the length of time it takes to access the Properties window.

On the Property Attributes dialog, accessible from the Tools menu, select the property you wish to suppress. Click the Advanced button, check "Don't show in Property Browser," and then click Apply.

Properties You Don't Need to Implement

Right away, you can avoid a lot of work. The Extender object, which is provided by the container your control is placed on, will supply a number of properties for you. DragIcon, HelpContextID, TabIndex, Top, and Visible are a few of the extender properties supplied by Visual Basic forms.

For More Information   To see all the properties Visual Basic's Extender object provides, search the Language Reference in the index for Extender Object. The Extender object is discussed in "Understanding the Container's Extender Object," earlier in this chapter. An odd exception is the Enabled property, which you must implement so that the Extender object can mask it. See "Allowing Your Control to be Enabled and Disabled," earlier in this chapter.

Other Consequences of the Special Nature of Control Properties

Other property creation requirements and options for controls are discussed in the following related topics.

• Saving the Properties of Your Control   Discusses the mechanism for saving and retrieving property values.
  
  
• Exposing Properties of Constituent Controls   You can save time and code by delegating to the constituent controls you place on the UserControl object.
  
  
• Using Standard Control Property Types   How to use the same property value enumerations other controls use.
  
  
• Creating Design-Time-Only or Run-Time-Only Properties   Making a property unavailable or read-only in different modes.
  
  
• Marking a Property as the Properties Window Default   How to identify property that will be highlighted first for a new control.
  
  
• Grouping Properties by Category   Creating and using property groups in the Properties window.
  
  
• Properties You Should Provide   Explains how to decide what properties your control should provide, and how to use the ActiveX Control Interface Wizard to make it easy.

For More Information   The UserControl object is discussed in "The UserControl Object," earlier in this chapter. General information on creating properties for objects, such as making a property the default for an object, is provided in "Adding Properties and Methods to Classes," in "General Principles of Component Design."