Storing properties using the PropertyBag object

PropertyBag is a new object introduced with Visual Basic 5. This object is of use exclusively for creating controls and ActiveX documents.

The PropertyBag object is a mechanism by which any of your control’s properties set within the Visual Basic Integrated Development Environment (IDE) can be stored. All controls have to store their properties somewhere. If you open a Visual Basic form file in a text editor such as Notepad, you’ll see at the start of the form file a whole raft of text that you wouldn’t normally see within the Visual Basic development environment. This text describes the form, its settings, and the controls and their settings contained within it. This is where PropertyBag stores the property settings of your control, with any binary information being stored in the equivalent FRX file.

This object is passed to your control during the ReadProperties and WriteProperties events. The ReadProperties event occurs immediately after a control’s Initialize event, usually when its parent form is loaded within the run-time or the design-time environment. This event is an opportunity for you to retrieve all of your stored property settings and apply them. You can do this by using the ReadProperty method of the PropertyBag object. This is illustrated in the following ReadProperties event from the DateEdit example control found on the book’s companion CD in the CHAP15 folder.

Private Sub UserControl_ReadProperties(PropBag As PropertyBag)

    '
    ' Load property values from storage.
    '
    Set m_MouseIcon = PropBag.ReadProperty("MouseIcon", Nothing)
    Set Font = PropBag.ReadProperty("Font", Ambient.Font)
    txtDateEdit.ForeColor = PropBag.ReadProperty("ForeColor", _
        &H80000008)
    txtDateEdit.FontName = PropBag.ReadProperty("FontName", _
        "MS Sans Serif")
    txtDateEdit.FontSize = PropBag.ReadProperty("FontSize", 8.25)
    txtDateEdit.FontBold = PropBag.ReadProperty("FontBold", 0)
    txtDateEdit.FontItalic = PropBag.ReadProperty("FontItalic", 0)
    §
    '
    ' Convert any Null dates to empty strings.
    '
    If IsNull(m_MinDate) Then m_MinDate = ""
    If IsNull(m_MaxDate) Then m_MaxDate = ""

End Sub

The ReadProperty method has two arguments: the first is the name of the property you want to read; and the second, optional, argument is the default value of that property. The ReadProperty method will search the PropertyBag object for your property. If it finds it, the value stored will be returned; otherwise, the default value you supplied will be returned. If no default value was supplied and no value was retrieved from PropertyBag, nothing will be returned and the variable or the object you were assigning the property to will remain unchanged.

Similarly, you can make your properties persistent by using the WriteProperties event. This event occurs less frequently, usually when the client form is unloaded or after a property has been changed within the IDE. Run-time property changes are obviously not stored in this way. You would not want them to be persistent.

The WriteProperty method has three arguments: the first is the name of the property you want to store; the second is the data value to be stored; and the third is optional, the default value for the property. This method will store your data value and the associated name you supply unless your data value matches the default value. If you specified a data value that matches the default value, no value is stored, but when you use ReadProperty to find this entry in PropertyBag, the default value will be returned. If you don’t specify a default value in your call to WriteProperty, the data value will always be stored.

The following code is from the WriteProperties event of the DateEdit control. It illustrates the use of PropertyBag’s WriteProperty method.

Private Sub UserControl_WriteProperties(PropBag As PropertyBag)

    '
    ' Write property values to storage.
    '
    Call PropBag.WriteProperty("ForeColor", txtDateEdit.ForeColor, _
        &H80000008)
    Call PropBag.WriteProperty("Enabled", m_Enabled, m_def_Enabled)
    Call PropBag.WriteProperty("FontName", txtDateEdit.FontName, _
        "")
    Call PropBag.WriteProperty("FontSize", txtDateEdit.FontSize, 0)
    Call PropBag.WriteProperty("FontBold", txtDateEdit.FontBold, 0)
    Call PropBag.WriteProperty("FontItalic", _
        txtDateEdit.FontItalic, 0)
    §

End Sub