Property Object

Description

A Property object represents a built-in or user-defined characteristic of a DAO object.

Remarks

Every DAO object except the Connection and Error objects contains a Properties collection which has Property objects corresponding to built-in properties of that DAO object. The user can also define Property objects and append them to the Properties collection of some DAO objects. These Property objects (which are often just called properties) uniquely characterize that instance of the object.

You can create user-defined properties for the following objects:

Database, Index, QueryDef, and TableDef objects
Field objects in Fields collections of QueryDef and TableDef objects

To add a user-defined property, use the CreateProperty method to create a Property object with a unique Name property setting. Set the Type and Value properties of the new Property object, and then append it to the Properties collection of the appropriate object. The object to which you are adding the user-defined property must already be appended to a collection. Referencing a user-defined Property object that has not yet been appended to a Properties collection will cause an error, as will appending a user-defined Property object to a Properties collection containing a Property object of the same name.

You can delete user-defined properties from the Properties collection, but you can't delete built-in properties.

Note A user-defined Property object is associated only with the specific instance of an object. 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, such as the Password property of a Workspace object, or try to read or write a property in an inappropriate context, such as the Value property setting of a Field object in the Fields collection of a TableDef object, an error occurs.

The Property object also has four built-in properties:

The Name property, a String that uniquely identifies the property.
The Type property, an Integer that specifies the property data type.
The Value property, a Variant that contains the property setting.
The Inherited property, a Boolean that indicates whether the property is inherited from another object. For example, a Field object in a Fields collection of a Recordset object can inherit properties from the underlying TableDef or QueryDef object.

To refer to a built-in Property object in a collection by its ordinal number or by its Name property setting, use any of the following syntax forms:

object.Properties(0)

object.Properties("name")

object.Properties![name]

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

object.name

Note For a user-defined property, you must use the full object.Properties("name") syntax.

With the same syntax forms, you can also refer to the Value property of a Property object. The context of the reference will determine whether you are referring to the Property object itself or the Value property of the Property object.

Properties

Inherited property, Name property, Type property, Value property.

See Also CreateProperty method, Database object.

Specifics (Microsoft Access)

Several types of properties exist in Microsoft Access. Each of these properties can be represented in Visual Basic code by a Property object variable, and each is a member of a Properties collection.

Properties That Apply to Data Access Objects

Built-in properties are defined by the Microsoft Jet database engine for all Data Access Objects (DAO).
User-defined properties can be added to some DAO objects. These DAO 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 DAO 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 DAO 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 Microsoft Access Specifics topic for the TableDef, QueryDef, and Field objects.

Microsoft Access–defined properties that apply to DAO 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!propertyname

In the preceding example, object is a DAO object and propertyname is the name of a Microsoft Access property.

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 by using the CreateProperty method. For example, the Caption property of a Field object is a Microsoft Access–defined property. If you haven't 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 by 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 won't 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 doesn't.

Properties that Apply to Microsoft Access Objects

Like DAO 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 DAO Property objects in that they don't 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.

Sub PropertyX()

    Dim dbsNorthwind As Database
    Dim prpNew As Property
    Dim prpLoop As Property

    Set dbsNorthwind = OpenDatabase("Northwind.mdb")

    With dbsNorthwind
        ' Create and append user-defined property.
        Set prpNew = .CreateProperty()
        prpNew.Name = "UserDefined"
        prpNew.Type = dbText
        prpNew.Value = "This is a user-defined property."
        .Properties.Append prpNew

        ' Enumerate all properties of current database.
        Debug.Print "Properties of " & .Name
        For Each prpLoop In .Properties
            With prpLoop
                Debug.Print "    " & .Name
                Debug.Print "        Type: " & .Type
                Debug.Print "        Value: " & .Value
                Debug.Print "        Inherited: " & _
                    .Inherited
            End With
        Next prpLoop

        ' Delete new property because this is a
        ' demonstration.
        .Properties.Delete "UserDefined"
    End With

End Sub

Example (Microsoft Access)

The following example creates a property that is defined by Microsoft Access, but applies to DAO 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.

You can use the same function to set a user-defined property on a Microsoft Access object or on a DAO object.

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 individual property.

Function SetAccessProperty(obj As Object, strName As String, _
        intType As Integer, varSetting As Variant) As Boolean
    Dim prp As Property
    Const conPropNotFound As Integer = 3270

    On Error GoTo ErrorSetAccessProperty
    ' Explicitly refer to Properties collection.
    obj.Properties(strName) = varSetting
    obj.Properties.Refresh
    SetAccessProperty = True
    
ExitSetAccessProperty:
    Exit Function
    
ErrorSetAccessProperty:
    If Err = conPropNotFound Then
        ' Create property, denote type, and set initial value.
        Set prp = obj.CreateProperty(strName, intType, varSetting)
        ' Append Property object to Properties collection.
        obj.Properties.Append prp
        obj.Properties.Refresh
        SetAccessProperty = True
        Resume ExitSetAccessProperty
    Else
        MsgBox Err & ": " & vbCrLf & Err.Description
        SetAccessProperty = False
        Resume ExitSetAccessProperty
    End If
End Function

You could call the preceding function with a procedure such as the following:

Sub CallPropertySet()
    Dim dbs As Database, tdf As TableDef
    Dim blnReturn As Boolean
    
    ' Return reference to current database.
    Set dbs = CurrentDb
    ' Return reference to Employees table.
    Set tdf = dbs.TableDefs!Employees
    ' Call SetAccessProperty function.
    blnReturn = SetAccessProperty(tdf, _
        "DatasheetFontItalic", dbBoolean, True)
    ' Evaluate return value.
    If blnReturn = True Then
        Debug.Print "Property set successfully."
    Else
        Debug.Print "Property not set successfully."
    End If
End Sub