FileProperty class

A FileProperty represents one Windows shell property attached to a file — its system name, localized name, unique ID, and current value.

FileProperty objects are not created directly. They are returned as items from the FileProperties collection, which is obtained by calling FilePropertyExplorer.OpenFile or FilePropertyExplorer.BrowseAndOpenFile.

Dim Props As FileProperties
Set Props = FilePropertyExplorer.OpenFile("C:\Photos\image.jpg")

Dim Prop As FileProperty
Set Prop = Props.Item(1)

Debug.Print Prop.Name       ' e.g. "System.ItemFolderNameDisplay"
Debug.Print Prop.ValueDesc  ' e.g. "Photos"

Properties

ID

A unique identifier string for the shell property.

Syntax: object.ID As String (read-only)

The identifier consists of a GUID identifying the property schema, a slash, and an integer identifying the property index within that schema. It identifies one property unambiguously: no two properties of a file have the same ID.

Pass the ID to FileProperties.Item to get the property back. That call raises an error for some properties; see the note on Item.

Name

The system identity name of the property.

Syntax: object.Name As String (read-only)

Returns a system name such as "System.ItemFolderNameDisplay". This name is safe to use as an identity field even on non-English systems. For the localized name, use NameDesc.

A property that has no system name returns an empty string. Use ID to identify such a property.

NameDesc

The localized name of the property.

Syntax: object.NameDesc As String (read-only)

Returns a localized version of the name. It is not always available: for some properties it is an empty string. Use Name for a locale-independent identifier.

Value

The current value of the shell property as a Variant.

Syntax: object.Value [ = value ]

Reading this property returns the value of the property as exposed by the operating system. The type of the returned Variant depends on the property. A property that has no value for the file returns Empty. A multi-value property can return an array.

Assigning a value writes the property into the file. The file must have been opened with write support, which requires Windows Vista or newer.

Note 1.7.1.0

Assigning a property that is not writable raises run-time error -2147352567 (Exception occurred), not Permission denied (error 70). An assignment to a property of a collection opened without write support raises the same error.

Note

Multi-value properties can return a Variant array. Check IsArray(Prop.Value) before using the result as a scalar.

For a string representation of the value in localized form, use ValueDesc.

ValueDesc

The current value of the property as a localized string.

Syntax: object.ValueDesc As String (read-only)

Returns the property value in localized form, combined into a single string. Multi-value properties that can return an array from Value are already combined into one string here. A property that has no value returns an empty string.

Use this property when displaying values to an end user. Use Value when the typed value is needed for computation or comparison.

VCOMObject

Holds the native-code COM object created internally by the Virtual-COM library.

Syntax: object.VCOMObject As Object

Example

This example opens a file and prints the system name, localized description, and value for each shell property.

Sub PrintFileProperties(ByVal FilePath As String)
    Dim Props As FileProperties
    Set Props = FilePropertyExplorer.OpenFile(FilePath)

    Dim i As Long
    For i = 0 To Props.Count - 1
        Dim Prop As FileProperty
        Set Prop = Props.Item(i)
        Debug.Print Prop.Name & " (" & Prop.NameDesc & "): " & Prop.ValueDesc
    Next i
End Sub

See Also