Visual Basic 6 Black Book
(Publisher: The Coriolis Group)
Author(s): Steven Holzner
ISBN: 1576102831
Publication Date: 08/01/98

Making ActiveX Control Properties Persistent (PropertyBag Object)

There’s a way of storing property settings in ActiveX controls that uses the PropertyBag object. For example, if you want the property settings the user makes in your control at design time to apply when the program runs, you must make the properties persistent. A persistent property is one whose value is stored and restored as needed.

Let’s see an example. Here, we’ll make the Operand1 and Operand2 properties of the calculator ActiveX control we’ve developed in the previous few topics persistent. To do that, we first call the Visual Basic PropertyChanged procedure when Operand1 or Operand2 is changed in its Let procedure. You pass the name of the property that’s been changed to PropertyChanged like this:

Public Property Let Operand1(ByVal vNewValue As Variant)
    Text1.Text = vNewValue
     PropertyChanged "Operand1"
End Property

Public Property Let Operand2(ByVal vNewValue As Variant)
    Text2.Text = vNewValue
     PropertyChanged "Operand2"
End Property

When you call PropertyChanged, the control creates a WriteProperties event, and you can write the new settings of properties to the PropertyBag object, which stores them on disk. Here’s how you use WriteProperty:

UserControl.WriteProperty(   propertyname, value [,default])

For example, to write the current settings of the calculator’s operands, we add this code to the WriteProperties event handler:

Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
     PropBag.WriteProperty "Operand1", Text1.Text
     PropBag.WriteProperty "Operand2", Text2.Text
End Sub

When the control needs to read its stored properties, it creates a ReadProperties event, and in that event’s handler, we can use ReadProperty:

UserControl.ReadProperty(   propertyname [, default])

Here’s how we use ReadProperty to read stored properties:

Private Sub UserControl_ReadProperties(PropBag As PropertyBag)
    Text1.Text = PropBag.ReadProperty("Operand1")
    Text2.Text = PropBag.ReadProperty("Operand2")
End Sub

Now the Operand1 and Operand2 properties are persistent. The code for this example, activexcalculatorcontrol.ctl version 2, appears in Listing 20.2.

Listing 20.2 activexcalculatorcontrol.ctl version 2

VERSION 6.00
Begin VB.UserControl CalculatorControl
   ClientHeight    =   3600
   ClientLeft      =   0
   ClientTop       =   0
   ClientWidth     =   4500
   ScaleHeight     =   3600
   ScaleWidth      =   4500
   Begin VB.TextBox Text2
      Height          =   495
      Left            =   1680
      TabIndex        =   4
      Top             =   1200
      Width           =   1215
   End
   Begin VB.CommandButton Command1
      Caption         =   "="
      Height          =   495
      Left            =   1680
      TabIndex        =   3
      Top             =   1920
      Width           =   1215
   End
   Begin VB.TextBox Text3
      Height          =   495
      Left            =   1680
      TabIndex        =   1
      Top             =   2640
      Width           =   1215
   End
   Begin VB.TextBox Text1
      Height          =   495
      Left            =   1680
      TabIndex        =   0
      Top             =   300
      Width           =   1215
   End
   Begin VB.Label Label1
      Caption         =   "+"
      Height          =   255
      Left            =   2160
      TabIndex        =   2
      Top             =   840
      Width           =   375
   End
End
Attribute VB_Name = "CalculatorControl"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = True
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = True
Private Sub Command1_Click()
    Text3.Text = Str(Val(Text1.Text) + Val(Text2.Text))
End Sub

Public Property Get Operand1() As Variant
    Operand1 = Text1.Text
End Property

Public Property Let Operand1(ByVal vNewValue As Variant)
    Text1.Text = vNewValue
    PropertyChanged "Operand1"
End Property

Public Property Get Operand2() As Variant
    Operand2 = Text2.Text
End Property

Public Property Let Operand2(ByVal vNewValue As Variant)
    Text2.Text = vNewValue
    PropertyChanged "Operand2"
End Property
Private Sub UserControl_ReadProperties(PropBag As PropertyBag)
    Text1.Text = PropBag.ReadProperty("Operand1")
    Text2.Text = PropBag.ReadProperty("Operand2")
End Sub

Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
    PropBag.WriteProperty "Operand1", Text1.Text
    PropBag.WriteProperty "Operand2", Text2.Text
End Sub

Besides the WriteProperties and ReadProperties events, user controls also have Initialize events that occur when the control is opened at design time and Terminate events that occur when you switch to runtime from design time (in other words, the design time—instance of the control is terminated).

Here’s the order of events that occur when you switch from design time to runtime:

•  WriteProperties

•  Terminate

•  ReadProperties

And here’s the order of events that occur when you switch from runtime to design time:

•  Initialize

•  ReadProperties

Adding A Method To An ActiveX Control

In the previous topic, we saw how to add a property to an ActiveX control—but how do you add a method? You add a method to an ActiveX control in much the same way you add a property—with the Tool menu’s Add Procedure dialog box.

Let’s see an example. In this case, we’ll add a new method to the calculator ActiveX control that we’ve developed in the previous few topics: the Calculate method. When the control’s Calculate method is called, we can add the values in the top two text boxes in the calculator and display the result in the bottom text box (just like clicking the equal (=) button in the calculator).

Open the calculator ActiveX project in Visual Basic now and open the code window as well. Next, select the Add Procedure item in the Tools menu, opening the Add Procedure dialog box, as shown in Figure 20.15. Give this new method the name Calculate.

Figure 20.15  The Add Procedure dialog box.

Select the entry labeled Sub to make our new method a Sub procedure, and make sure the entry labeled Public in the Scope box is selected (making this method available outside the ActiveX control to container programs). Then click on OK to close the Add Procedure dialog box.