Properties Collection

Description

A Properties collection contains all the Property objects for a specific instance of an object.

Remarks

Every data access object contains a Properties collection, which has certain built-in Property objects. These Property objects (which are often just called properties) uniquely characterize that instance of the object.

In addition to the built-in properties, some objects allow you to create and add your own user-defined properties. To add a user-defined property to an existing instance of an object, first define its characteristics with the CreateProperty method, then add it to the collection with the Append method.

You can use the Delete method to remove user-defined properties from the Properties collection, but you can't remove built-in properties.

Note

A user-defined property (Property object) is associated only with the specific instance of the object whose Properties collection you append it to. The property isn't defined for all instances of objects of the selected type.

You can use the Properties collection of an object to enumerate the object's built-in and user-defined properties. You don't need to know beforehand exactly which properties exist or what their characteristics (Name and Type properties) are to manipulate them. However, if you try to read a write-only property, an error occurs.

You can refer to an existing built-in or user-defined property by its Name property setting using this syntax:

object.Properties("name")

For a built-in property, you can also use this syntax:

object.name

You can also reference properties by their ordinal position. For example, this syntax refers to the first member of the Properties collection:

object.Properties(0)

Note

A user-defined property differs from a built-in property of a data access object in that you must refer to a user-defined property using the full Properties("name") syntax.

Properties

Count Property.

Methods

Append Method, Delete Method, Refresh Method.

Properties that apply to data access objects

Built-in properties are defined by the Microsoft Jet database engine for each data access object.
User-defined properties can be added to some data access objects. These data access objects include Database, Index, QueryDef, and TableDef objects, and Field objects in the Fields collection of a QueryDef or TableDef object.
Some properties defined by Microsoft Access apply to data access objects. These properties can generally be set either in the Microsoft Access window or from Visual Basic. The Jet database engine cannot recognize these properties until corresponding Property objects are specifically created and appended to the Properties collection. The data access objects to which such properties may apply are QueryDef and TableDef objects, and Field objects in the Fields collection of a QueryDef or TableDef object. For lists of these Microsoft Access-defined properties, see the Specifics (Microsoft Access) sections in the topics for the TableDef, QueryDef, and Field objects.

Microsoft Access-defined properties that apply to data access objects differ from properties defined by the Jet database engine in several ways.

To refer to a user-defined property or a property defined by Microsoft Access, you must explicitly refer to the Properties collection. The fastest way to refer to a Microsoft Access property is by the following syntax.

object.Properties!name

You can also use the following, slightly slower syntax.

object.Properties("name")

In contrast, to refer to properties defined by the Jet database engine, you can simply use the object.name syntax.

If you are setting the value of a Microsoft Access-defined property for the first time, you first need to create it using the CreateProperty method. For example, the Caption property of a Field object is a Microsoft Access-defined property. If you have not previously set the Caption property in table Design view, but are setting the property for the first time from Visual Basic code, you must first create that property using the CreateProperty method and append it to the Properties collection before you can set its value.

A Microsoft Access-defined property is automatically appended to the Properties collection the first time it is set in the Microsoft Access window, so if you have already set a property in the user interface, you don't need to create and append the property in code. For example, you can set the Caption property for a table in Datasheet view by clicking Font on the Format menu. This property is then included in the Properties collection of a TableDef object that points to the table.

Until you have set a Microsoft Access-defined property either in table Design view or from Visual Basic code, that property will not appear in the Properties collection. When you set these properties from Visual Basic, you should include error-handling code that checks to see if the property exists in the Properties collection, and creates and appends the property if it does not.

Properties that apply to Microsoft Access objects

Like data access objects, every Microsoft Access object contains a Properties collection, which has built-in Property objects. For example, Property objects that apply to a form are members of the Properties collection of the Form object.

You can also create user-defined properties for Microsoft Access objects. For example, you might create a property called TextType that applies to a text box control.

Property objects in the Properties collections of Form, Report, and Control objects differ from data access Property objects in that they do not have an Inherited property.

You can enumerate the Property objects in the Properties collections of Form, Report, and Control objects. However, the Microsoft Access Application object and the Screen object have Properties collections that can't be enumerated. Additionally, the properties of these objects are read-only.

Example

This example creates a user-defined property for the current database, sets its Type and Value properties, and appends it to the Properties collection of the database. Then the example enumerates all properties in the database.

Function EnumerateProperty () As Integer
    Dim wrkDefault As Workspace, dbsExample As Database
    Dim prpUserDefined As Property, prpEnum As Property
    Dim I As Integer
    ' Get default workspace and current database.
    Set wrkDefault = DBEngine.Workspaces(0)
    Set dbsExample = wrkDefault.OpenDatabase("Northwind.mdb")
    ' Create user-defined property.
    Set prpUserDefined = dbsExample.CreateProperty()
    ' Set properties of new property.
    prpUserDefined.Name = "UserDefinedProperty"
    prpUserDefined.Type = dbText
    prpUserDefined.Value = "This is a user-defined property."
    ' Append property to current database.

    dbsExample.Properties.Append prpUserDefined
    ' Enumerate all properties of current database.
    Debug.Print "Properties of Database "; dbsExample.Name
    For I = 0 To dbsExample.Properties.Count - 1
        Set prpEnum = dbsExample.Properties(I)
        Debug.Print
        Debug.Print " Properties("; I; ")"
        Debug.Print "  Name: "; prpEnum.Name
        Debug.Print "  Type: "; prpEnum.Type
        Debug.Print "  Value: "; prpEnum.Value
        Debug.Print "  Inherited: "; prpEnum.Inherited
    Next I
    Debug.Print
    EnumerateProperty = True
End Function

This example shows how you can set an application-defined property (or any user-defined property that may not yet exist) without causing a run-time error. The example sets an arbitrary property of a Field object. The return value of the function is True if the value was properly set. The return value is False if an unexpected error occurs when the property is set.

Function SetFieldProperty (fldPropVal As Field, strName As String, intType As Integer, varValue As Variant) As Integer
    Const ERR_PROPERTY_NONEXISTENT = 3270
    Dim prpUserDefined As Property
    On Error Resume Next    ' Function handles errors.
    SetFieldProperty = True
    fldPropVal.Properties(strName) = varValue
    If Err <> 0 Then    ' Error occurred when value was set.
        If Err <> ERR_PROPERTY_NONEXISTENT
            On Error GoTo 0
            SetFieldProperty = False
        Else
            ' Create Property object, setting its Name, Type, and Value
            ' properties.
            On Error Resume Next
            Set prpUserDefined = fldPropVal.CreateProperty(strName, _ 
                intType, varValue)
            fldPropVal.Properties.Append prpUserDefined
            If Err <> 0 Then
                SetFieldProperty = False
            End If
            On Error GoTo 0
        End If
    End If
End Function

Example (Microsoft Access)

The following example creates a new user-defined property, sets its initial value, and appends it to the Properties collection of a TableDef object.

Sub CreateNewProperty()
    Dim dbs As Database, tdf As TableDef
    Dim prp As Property
    ' Return Database object pointing to current database.
    Set dbs = CurrentDb
    Set tdf = dbs.TableDefs!Orders
    ' Create new property, denote type, and set initial value.
    Set prp = tdf.CreateProperty("LastSaved", dbText, "New")
    ' Append to Properties collection of TableDef object.
    tdf.Properties.Append prp
End Sub

The next example creates a property that is defined by Microsoft Access, but applies to data access objects. Because the Microsoft Jet database engine cannot recognize properties defined by Microsoft Access, you must create a new Property object and append it to the Properties collection if you are setting the property for the first time.

Note that you must specify the correct constant for the type argument when you create the property. If you're not certain which data type you should use, see the topic for the individual property.

Sub CreateAccessProperty()
    Dim dbs As Database, tdf As TableDef
    Dim prp As Property

    ' Return Database object pointing to current database.
    Set dbs = CurrentDb
    Set tdf = dbs.TableDefs!Orders
    ' Create property, denote type, and set initial value.
    Set prp = tdf.CreateProperty("DatasheetFontItalic", dbBoolean, True)
    ' Append Property object to Properties collection.
    tdf.Properties.Append prp
End Sub