public class PropertySet extends ComponentBase
convertPropertyValue
,
setPropertyValueNoBroadcast
and
getPropertyValue(Property)
one can determine how
property values are stored.
When using the supplied implementations of this class then the member variables which
hold property values have to be declared in the class which inherits last in the inheriting
chain and they have to be publicProperties have to be registered by one of the registerProperty methods. They take among other arguments an Object named id which has to be a String that represents the name of the member variable. The registering has to occur in the constructor of the inheriting class. It is no allowed to add or change properties later on.
Example:
public class Foo extends PropertySet { protected int intProp; public Foo() { registerProperty("PropertyA", 0, new Type(int.class), (short)0, "intProp"); } }
Modifier and Type | Field and Description |
---|---|
protected MultiTypeInterfaceContainer |
aBoundLC |
protected MultiTypeInterfaceContainer |
aVetoableLC |
protected XPropertySetInfo |
propertySetInfo |
bDisposed, bInDispose, listenerContainer
_mapImplementationIds, _mapTypes
Constructor and Description |
---|
PropertySet() |
Modifier and Type | Method and Description |
---|---|
void |
addPropertiesChangeListener(java.lang.String[] propNames,
XPropertiesChangeListener listener) |
void |
addPropertyChangeListener(java.lang.String str,
XPropertyChangeListener xPropertyChangeListener) |
void |
addVetoableChangeListener(java.lang.String str,
com.sun.star.beans.XVetoableChangeListener xVetoableChangeListener) |
protected void |
assignPropertyId(Property prop,
java.lang.Object id)
Assigns an identifyer object to a Property object so that the identifyer
can be obtained by
getPropertyId later on. |
protected boolean |
convertPropertyValue(Property property,
java.lang.Object[] newVal,
java.lang.Object[] curVal,
java.lang.Object setVal)
Converts a value in a way so that it is appropriate for storing as a property value, that is
setPropertyValueNoBroadcast can process the value without any further
conversion. |
protected void |
fire(Property[] properties,
java.lang.Object[] newValues,
java.lang.Object[] oldValues,
boolean bVetoable)
This method fires events to XPropertyChangeListener,XVetoableChangeListener and
XPropertiesChangeListener event sinks.
|
void |
firePropertiesChangeEvent(java.lang.String[] propNames,
XPropertiesChangeListener listener) |
java.lang.Object |
getFastPropertyValue(int nHandle) |
protected Property[] |
getProperties()
Returns an array of all Property objects or an array of length null if there
are no properties.
|
protected Property |
getProperty(java.lang.String propertyName)
Returns the Property object for a given property name or null if that property does
not exists (i.e.
|
protected Property |
getPropertyByHandle(int nHandle)
Returns the Property object with a handle (Property.Handle) as specified by the argument
nHandle.
|
protected java.lang.Object |
getPropertyId(Property prop)
Returns the identifyer object for a certain Property.
|
com.sun.star.beans.XPropertySetInfo |
getPropertySetInfo() |
protected java.lang.Object |
getPropertyValue(Property property)
Retrieves the value of a property.
|
java.lang.Object |
getPropertyValue(java.lang.String name) |
java.lang.Object[] |
getPropertyValues(java.lang.String[] propNames)
If a value for a property could not be retrieved then the respective element in the returned
array has the value null.
|
protected void |
initMappings()
Initializes data structures used for mappings of property names to property object,
property handles to property objects and property objects to id objects.
|
protected void |
postDisposing()
Makes sure that listeners which are kept in aBoundLC (XPropertyChangeListener) and aVetoableLC
(XVetoableChangeListener) receive a disposing call.
|
protected void |
putProperty(Property prop)
Stores a Property object so that it can be retrieved subsequently by
getProperty(String) ,getProperties() ,getPropertyByHandle(int) . |
protected void |
registerProperty(Property prop,
java.lang.Object id)
Registers a property with this helper class and associates the argument id with it.
|
protected void |
registerProperty(java.lang.String name,
int handle,
Type type,
short attributes,
java.lang.Object id)
Registers a property with this helper class and associates the argument id with it.
|
protected void |
registerProperty(java.lang.String propertyName,
short attributes)
Registers a property with this class.
|
protected void |
registerProperty(java.lang.String propertyName,
java.lang.String memberName,
short attributes)
Registers a property with this class.
|
protected void |
registerProperty(java.lang.String name,
Type type,
short attributes,
java.lang.Object id)
Registers a property with this class and associates the argument id with it.
|
void |
removePropertiesChangeListener(XPropertiesChangeListener xPropertiesChangeListener) |
void |
removePropertyChangeListener(java.lang.String propName,
XPropertyChangeListener listener) |
void |
removeVetoableChangeListener(java.lang.String propName,
XVetoableChangeListener listener) |
void |
setFastPropertyValue(int nHandle,
java.lang.Object aValue) |
protected void |
setPropertyValue(Property prop,
java.lang.Object value)
Sets the value of a property.
|
void |
setPropertyValue(java.lang.String name,
java.lang.Object value)
Sets the value of a property.
|
protected void |
setPropertyValueNoBroadcast(Property property,
java.lang.Object newVal)
Sets the value of a property.
|
void |
setPropertyValues(java.lang.String[] propNames,
java.lang.Object[] values)
If the array of property names contains an unknown property then it will be ignored.
|
addEventListener, dispose, finalize, preDisposing, removeEventListener
getImplementationId, getTypes, queryAdapter
protected XPropertySetInfo propertySetInfo
protected MultiTypeInterfaceContainer aBoundLC
protected MultiTypeInterfaceContainer aVetoableLC
protected void registerProperty(Property prop, java.lang.Object id)
convertPropertyValue
,
setPropertyValueNoBroadcast
and getPropertyValue
These methods expect id to be a java.lang.String which represents the name of a member variable
which holds the property value.
Only properties which are registered can be accessed. Registration has to occur during
initialization of the inheriting class (i.e. within the contructor).prop
- The property to be registered.id
- Identifies the properties storage.getPropertyId(Property)
protected void registerProperty(java.lang.String name, int handle, Type type, short attributes, java.lang.Object id)
registerProperty(Property, Object)
. The first four
arguments are used to construct a Property object.
Registration has to occur during
initialization of the inheriting class (i.e. within the contructor)name
- The property's name (Property.Name).handle
- The property's handle (Property.Handle).type
- The property's type (Property.Type).attributes
- The property's attributes (Property.Attributes).id
- Identifies the property's storage.protected void registerProperty(java.lang.String name, Type type, short attributes, java.lang.Object id)
registerProperty(Property, Object)
. The first three
arguments are used to construct a Property object. The value for the Property.Handle
is generated and does not have to be specified here. Use this method for registering
a property if you do not care about the Property's handles.
Registration has to occur during
initialization of the inheriting class (i.e. within the contructor).name
- The property's name (Property.Name).type
- The property's type (Property.Type).attributes
- The property's attributes (Property.Attributes).id
- Identifies the property's storage.protected void registerProperty(java.lang.String propertyName, java.lang.String memberName, short attributes)
propertyName
- The name of the property.memberName
- The name of the member variable that holds the value of the property.attributes
- The property attributes.protected void registerProperty(java.lang.String propertyName, short attributes)
propertyName
- The name of the property and the member variable that holds the property's value.attributes
- The property attributes.registerProperty(String, String, short)
protected Property getProperty(java.lang.String propertyName)
initMappings()
, getProperties()
and
putProperty(Property)
.propertyName
- The name of the property (Property.Name)protected Property getPropertyByHandle(int nHandle)
initMappings()
, putProperty(Property)
.nHandle
- The handle of the property (Property.Handle).protected Property[] getProperties()
initMappings()
, getProperty(String)
and
putProperty(Property)
.protected void putProperty(Property prop)
getProperty(String)
,getProperties()
,getPropertyByHandle(int)
.
Override this method if you want to implement your own mapping from handles
to Property objects and names to Property objects. Then you also need to override initMappings()
,
getProperty(String)
,getProperties()
,getPropertyByHandle(int)
.prop
- The Property object that is to be stored.protected void assignPropertyId(Property prop, java.lang.Object id)
getPropertyId
later on. The identifyer
is used to specify a certain storage for the property's value. If you do not
override setPropertyValueNoBroadcast
or getPropertyValue(Property)
then the argument id has to be a java.lang.String that equals the name of
the member variable that holds the Property's value.
Override this method if you want to implement your own mapping from Property objects to ids or
if you need ids of a type other then java.lang.String.
Then you also need to override initMappings
and getPropertyId
.prop
- The Property object that is being assigned an id.id
- The object which identifies the storage used for the property's value.registerProperty(Property, Object)
protected java.lang.Object getPropertyId(Property prop)
assignPropertyId
.
Override this method if you want to implement your own mapping from Property objects to ids.
Then you also need to override initMappings
and assignPropertyId
.prop
- The property for which the id is to be retrieved.registerProperty(Property, Object)
protected void initMappings()
putProperty
,getProperty
, getPropertyByHandle(int)
,
assignPropertyId
and getPropertyId
.protected void postDisposing()
postDisposing
in class ComponentBase
public void addPropertyChangeListener(java.lang.String str, XPropertyChangeListener xPropertyChangeListener) throws UnknownPropertyException, WrappedTargetException
UnknownPropertyException
WrappedTargetException
public void addVetoableChangeListener(java.lang.String str, com.sun.star.beans.XVetoableChangeListener xVetoableChangeListener) throws com.sun.star.beans.UnknownPropertyException, com.sun.star.lang.WrappedTargetException
com.sun.star.beans.UnknownPropertyException
com.sun.star.lang.WrappedTargetException
public com.sun.star.beans.XPropertySetInfo getPropertySetInfo()
public java.lang.Object getPropertyValue(java.lang.String name) throws UnknownPropertyException, WrappedTargetException
UnknownPropertyException
WrappedTargetException
public void removePropertyChangeListener(java.lang.String propName, XPropertyChangeListener listener) throws UnknownPropertyException, WrappedTargetException
UnknownPropertyException
WrappedTargetException
public void removeVetoableChangeListener(java.lang.String propName, XVetoableChangeListener listener) throws UnknownPropertyException, WrappedTargetException
UnknownPropertyException
WrappedTargetException
public void setPropertyValue(java.lang.String name, java.lang.Object value) throws UnknownPropertyException, PropertyVetoException, com.sun.star.lang.IllegalArgumentException, WrappedTargetException
name
- The name of the property.value
- The new value of the property.
*UnknownPropertyException
PropertyVetoException
com.sun.star.lang.IllegalArgumentException
WrappedTargetException
protected void setPropertyValue(Property prop, java.lang.Object value) throws UnknownPropertyException, PropertyVetoException, com.sun.star.lang.IllegalArgumentException, WrappedTargetException
prop
- The property whose value is to be set.value
- The new value for the property.UnknownPropertyException
PropertyVetoException
com.sun.star.lang.IllegalArgumentException
WrappedTargetException
protected boolean convertPropertyValue(Property property, java.lang.Object[] newVal, java.lang.Object[] curVal, java.lang.Object setVal) throws com.sun.star.lang.IllegalArgumentException, WrappedTargetException, UnknownPropertyException
setPropertyValueNoBroadcast
can process the value without any further
conversion. This implementation presumes that
the values are stored in member variables of the furthest inheriting class. For example,
class A inherits this class then members of class A
can hold property values. If there is a class B which inherits A then only members of B can hold
property values. The variables must be public. A property must have been registered (e.g. by
registerProperty(Property, Object)
in order for this method to work. The identifyer argument (type Object)
used in the registerProperty methods must
be a java.lang.String, which is, the name of the member variable that holds the property value.
If one opts to store values differently then one may override
this method, as well as setPropertyValueNoBroadcast
and
getPropertyValue(Property)
.
This method is always called as a result of a call to one of the setter methods, such as
XPropertySet.setPropertyValue
,
XFastPropertySet.setFastPropertyValue
and XMultiPropertySet.setPropertyValues
.
If this method fails, that is, it returns false or throws an exception, then no listeners are notified and the
property value, that was intended to be changed, remains untouched.setPropertyValueNoBroadcast
which is called subsequent to convertPropertyValue.
This method converts values by help of the com.sun.star.uno.AnyConverter which only does a few widening conversions on integer types and floating point types. For example, there is the property PropA with a Type equivalent to int.class and the value of the property is to be stored in a member variable of type int with name intProp. Then setPropertyValue is called:
set.setPropertyValue( "PropA", new Byte( (byte)111));At some point setPropertyValue will call convertPropertyValue and pass in the Byte object. Since we allow that Byte values can be used with the property and know that the value is to be stored in intProp (type int) we convert the Byte object into an Integer object which is then returned in the out-parameter newVal. This conversion is actually performed by the AnyConverter. Later the setPropertyValueNoBroadcast is called with that Integer object and the int value can be easily extracted from the object and be assigned to the member intProp.
The method handles Any arguments the same as Object arguments. That is, the setVal argument can
be a java.lang.Boolean or a com.sun.star.uno.Any containing a java.lang.Boolean. Likewise, a member
containing a property value can be a com.sun.star.uno.Any or an java.lang.Object.
Then, no conversion is necessary, since they can hold all possible values. However, if
the member is an Object and setVal is an Any then the object contained in the any is assigned to
the member. The extra type information which exists as Type object in the Any will get lost. If this is not
intended then use an Any variable rather then an Object.
If a member is an Object or Any and the argument setVal is an Object, other than String or array,
then it is presumed to be an UNO object and queried for XInterface. If successful, the out-param newVal
returns the XInterface.
If a member is an UNO interface, then setVal is queried for this interface and the result is returned.
If setVal is null then newVal will be null too after return.
If a property value is stored using a primitive type the the out-parameters curVal and newVal contain the respective wrapper class (e.g.java.lang.Byte, etc.). curVal is used in calls to the XVetoableChangeListener and XPropertyChangeListener.
property
- - in-param property for which the data is to be converted.newVal
- - out-param which contains the converted value on return.curVal
- - out-param the current value of the property. It is used in calls to the
XVetoableChangeListener and XPropertyChangeListener.setVal
- - in-param. The value that is to be converted so that it matches Property and the internally used
dataformat for that property.com.sun.star.lang.IllegalArgumentException
- The value provided is unfit for the property.com.sun.star.lang.WrappedTargetException
- - An exception occurred during the conversion, that is to be made known
to the caller.WrappedTargetException
UnknownPropertyException
protected void setPropertyValueNoBroadcast(Property property, java.lang.Object newVal) throws WrappedTargetException
convertPropertyValue
Notification of property listeners
does not occur in this method. By overriding this method one can take full control about how property values
are stored. But then, the convertPropertyValue
and
getPropertyValue(Property)
must be overridden too.
A Property with the MAYBEVOID attribute set, is stored as null value. Therefore the member variable must be
an Object in order to make use of the property attribute. An exception is Any. The Any variable can be initially null, but
once it is set the reference will not become null again. If the value is to be set to
void then a new Any will be stored
with a valid type but without a value (i.e. Any.getObject returns null).
If a property has the READONLY attribute set, and one of the setter methods, such as setPropertyValue, has been
called, then this method is not going to be called.property
- the property for which the new value is setnewVal
- the new value for the property.com.sun.star.lang.WrappedTargetException
- An exception, which has to be made known to the caller,
occurred during the setting of the value.WrappedTargetException
protected java.lang.Object getPropertyValue(Property property)
convertPropertyValue
) and that the
variables are public. The property must have
been registered, for example by registerProperty(Property, Object)
. The identifyer Object argument
must have been a java.lang.String which was the name of the member variable holding the property value.
When properties are to be stored differently one has to override this method as well as
convertPropertyValue(Property, java.lang.Object[], java.lang.Object[], java.lang.Object)
and setPropertyValueNoBroadcast(Property, java.lang.Object)
. property
- The property for which the value is to be retrieved.protected void fire(Property[] properties, java.lang.Object[] newValues, java.lang.Object[] oldValues, boolean bVetoable) throws PropertyVetoException
properties
- Properties which will be or have been affected.newValues
- the new values of the properties.oldValues
- the old values of the properties.bVetoable
- true means fire to VetoableChangeListener, false means fire to
XPropertyChangedListener and XMultiPropertyChangedListener.PropertyVetoException
public void setFastPropertyValue(int nHandle, java.lang.Object aValue) throws UnknownPropertyException, PropertyVetoException, com.sun.star.lang.IllegalArgumentException, WrappedTargetException
UnknownPropertyException
PropertyVetoException
com.sun.star.lang.IllegalArgumentException
WrappedTargetException
public java.lang.Object getFastPropertyValue(int nHandle) throws UnknownPropertyException, WrappedTargetException
UnknownPropertyException
WrappedTargetException
public void addPropertiesChangeListener(java.lang.String[] propNames, XPropertiesChangeListener listener)
public void firePropertiesChangeEvent(java.lang.String[] propNames, XPropertiesChangeListener listener)
public java.lang.Object[] getPropertyValues(java.lang.String[] propNames)
public void removePropertiesChangeListener(XPropertiesChangeListener xPropertiesChangeListener)
public void setPropertyValues(java.lang.String[] propNames, java.lang.Object[] values) throws PropertyVetoException, com.sun.star.lang.IllegalArgumentException, com.sun.star.lang.WrappedTargetException
PropertyVetoException
com.sun.star.lang.IllegalArgumentException
com.sun.star.lang.WrappedTargetException