>
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.
See Also
Appendix, "Data Access Object Hierarchy."
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 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