Property pages let you set the design-time properties of an ActiveX control from a tabbed dialog box rather than from the Visual Basic Properties window. You will want to add property pages to controls that have groups of related properties so that you can access them easily, without having to scroll around in the Properties window.
You can also use property pages to display lists of valid settings that are determined at design time. For example, the Blinker control's property page displays a list of the objects on a form for the TargetString property, as shown in Figure 6-7.
Figure 6-7. The Blinker control's property page.
To add a property page to a control project, select the control project in the Project Explorer window, choose Add Property Page from the Project menu, and double-click the Property Page icon. You can name the property page and specify the text to appear on the property page tab when it is being used by setting the Name and Caption properties, respectively, in the Properties window. To connect a property page to a control, first open the control's UserControl window and select the control. In the Properties window, double-click on the PropertyPages property to display the Connect Property Pages dialog box, as shown in Figure 6-8 below. Check the appropriate property page in the Available Property Pages list, and then click OK.
When you connect a property page to an ActiveX control, Visual Basic adds a (Custom) item to the list of design-time properties displayed for that control. Double-clicking on (Custom) displays the control's property page.
As with the UserControl window, the property page window is in design mode when it is open. You can draw controls on the property page and write code to respond to events just as you would on a form. The property page has a built-in SelectedControls collection that you use to get the instance of the control that the property page refers to. Use the property page's SelectionChanged event procedure to initialize the data you display in the controls on a property page.
Figure 6-8. Using the Connect Property Pages dialog box to connect a property page to a control.
The following code sets the initial values for the Interval and TargetObject properties, which are displayed on the Blinker property page in the txtInterval text box and cmbTargetString combo box, respectively.
Private Sub PropertyPage_SelectionChanged()
`Set property page interval to match
`control's setting
txtInterval = SelectedControls(0).Interval
`Build a list of objects for TargetString
Dim frmParent As Form
Dim ctrIndex As Control
Dim strTarget As String
`Get form the control is on
Set frmParent = SelectedControls(0).Parent
strTarget = SelectedControls(0).TargetString
If strTarget <> "" Then
`Add current property setting to
`combo box
cmbTargetString.List(0) = strTarget
End If
If frmParent.Name <> strTarget Then
`Add form name to combo box
cmbTargetString.AddItem frmParent.Name
End If
`Add each of the controls on the form to
`combo box
For Each ctrIndex In frmParent.Controls
`Exclude Blinker control
If TypeName(ctrIndex) <> "Blinker" Or _
ctrIndex.Name = strTarget Then
cmbTargetString.AddItem ctrIndex.Name
End If
Next ctrIndex
`Display current TargetString setting
cmbTargetString.ListIndex = 0
End Sub
NOTE
The SelectedControls collection is not available within the property page's Initialize event.
Notice that SelectedControls(0) returns the currently selected object—in this case, the Blinker control. I had to add a Parent property to the Blinker control so that this property page could get information about the Blinker control's container. The following code shows the Blinker control's Parent property:
`~~~.Parent
Public Property Get Parent() As Object
Set Parent = UserControl.Parent
End Property
You use the property page's ApplyChanges event procedure to write the settings on the property page to the ActiveX control's properties. The following code retrieves the settings from the property page and stores them in the ActiveX control's properties:
Private Sub PropertyPage_ApplyChanges()
`Save settings on the property page
`in the control's properties
SelectedControls(0).Interval = txtInterval.Text
SelectedControls(0).TargetString = _
cmbTargetString.List _
(cmbTargetString.ListIndex)
End Sub
You need to notify the property page if the user changes any of the settings on the property page. The built-in Changed property tells Visual Basic to apply the property changes when the user clicks OK or Apply. The code below sets the Changed property if either setting on the Blinker control's property page changes.
Private Sub txtInterval_Change()
Changed = True
End Sub
Private Sub cmbTargetString_Change()
Changed = True
End Sub
Property pages can be displayed by right-clicking on a control and choosing Properties from the context menu, by double-clicking on the (Custom) property in the Properties window, or by clicking the ellipsis button in the (Custom) property's setting field in the Properties window.
To add an ellipsis button to a property in the Properties window, follow these steps:
Figure 6-9. Using the Procedure Attributes dialog box to associate a property page with a specific property.
To display the Blinker control's property page, shown in Figure 6-10, click the ellipsis button in the TargetString property.
Figure 6-10. The Blinker control's Property Pages dialog box as displayed by clicking the ellipsis button.
When a user displays a Property Pages dialog box by clicking the ellipsis button, the property page should set the focus on the appropriate field. The property page EditProperty event procedure shown here sets the focus on the appropriate control when the user clicks the ellipsis button in the TargetString or Interval property of the Blinker control:
Private Sub PropertyPage_EditProperty(PropertyName As String)
`Set focus on the appropriate control
Select Case PropertyName
Case "TargetString"
cmbTargetString.SetFocus
Case "Interval"
txtInterval.SetFocus
Case Else
End Select
End Sub