Getting and Setting Properties: XPropertySet

It is common for an UNO service to define properties; some are optional and some are required. Many of these objects contain the object property dbg_properties, which is a string containing a list of properties supported by the object. OOo Basic automatically makes these properties available for direct access; other languages may not. The com.sun.star.beans.XPropertySet interface provides methods to get, set, and enumerate the object's properties, as shown in Table 3 .

Table 3: Object methods defined by the interface XPropertySet.

Object Method	Description
getPropertySetInfo()	Return an object supporting the com.sun.star.beans.XPropertySetInfo interface. This object describes the object's properties but may be null.
setPropertyValue( name , value)	Set the value of the named property. A listener may veto this change.
getPropertyValue(name)	Return the value of the named property.
addPropertyChangeListener(name, listener)	Add an XPropertyChangeListener for the named property. An empty name listens for all properties.
removePropertyChangeListener(name, listener)	Remove an XPropertyChangeListener.
addVetoableChangeListener(name, listener)	Add an XVetoableChangeListener for the named property. An empty name listens for all properties.
removeVetoableChangeListener(name, listener)	Removes an XVetoableChangeListener.

In OOo Basic, properties are usually accessed directly. Listing 1 demonstrates two ways to obtain the CharFontName property from a Writer document-these methods return the name of the font style.

Listing 1: Two methods to obtain the name of the font style.

 Print ThisComponent.CharFontName Print CStr(ThisComponent.getPropertyValue("CharFontName")) 

 

Accessing the property directly is the most expedient method while using OOo Basic, but there are advantages to using the methods defined by the XPropertySetInfo interface. Some properties are defined as optional, so not every document contains every property. The XPropertySetInfo interface defines the object method hasPropertyByName(), which can be used to test for the existence of a property before use; errors can still be avoided by using error-handling routines. Another use is to generically enumerate all of the contained properties and possibly their values as shown in Listing 2 . Figure 1 shows the first 10 properties of a Writer document using the macro in Listing 2.

Figure 1: The first 10 properties of ThisComponent.

Listing 2: getPropertyValues is found in the Generic module in this chapter's source code files as SC12.sxw.

 Sub getPropertyValues   Dim vPropInfo  'PropertySetInfo object   Dim vProps     'Array of properties   Dim vProp      'com.sun.star.beans.Property   Dim v          'Value of a single property   Dim i%         'Index variable   Dim s$         'General message string   Dim nCount%   REM Object implements interface com.sun.star.beans.XPropertySetInfo   vPropInfo = ThisComponent.getPropertySetInfo()   REM sequence< Property > vPropInfo.getProperties()   REM Property vPropInfo.getPropertyByName(name)   REM boolean vPropInfo.hasPropertyByName(name)   vProps = vPropInfo.getProperties()   For i = 0 To UBound(vProps)     If nCount = 30 Then       nCount = 0       MsgBox s, 0, "Properties"       s = ""     End If     nCount = nCount + 1     vProp = vProps(i) 'com.sun.star.beans.Property     s = S & vProp.Name & " = "     v = ThisComponent.getPropertyValue(vProp.Name)     If IsNull(v) Then       s = S & "Null"     ElseIf IsEmpty(v) Then       s = S & "Empty"     ElseIf VarType(v) < 9 Then       s = S & CStr(v)     Else       s = S & "Object or Array"     End If     s = S & CHR$(10)   Next   MsgBox s, 0, "Properties" End Sub 

 

Tip  

In case you missed the implications of the macro in Listing 2, it allows you to generically inspect any object that supports the XPropertySet interface. The ability to inspect an object is invaluable when you aren't certain what you can do with an object.