Difference between revisions of "Documentation/DevGuide/FirstSteps/Any"
OOoWikiBot (Talk | contribs) m (Robot: Changing Category:Documentation/Developers Guide/First Steps) |
m (minor formatting) |
||
| Line 7: | Line 7: | ||
[[zh:Zh/Documentation/DevGuide/FirstSteps/Any]] | [[zh:Zh/Documentation/DevGuide/FirstSteps/Any]] | ||
{{DISPLAYTITLE:Any}} | {{DISPLAYTITLE:Any}} | ||
| − | The {{ | + | The {{OOo}} API frequently uses an <code>any</code> type, which is the counterpart of the <code>Variant</code> type known from other environments. The <code>any</code> type holds one arbitrary UNO type. The <code>any</code> type is especially used in generic UNO interfaces. |
Examples for the occurrence of any are the method parameters and return values of the following, frequently used methods: | Examples for the occurrence of any are the method parameters and return values of the following, frequently used methods: | ||
| Line 25: | Line 25: | ||
|} | |} | ||
| − | + | The <code>any</code> type also occurs in the <idl>com.sun.star.beans.PropertyValue</idl> struct. | |
[[Image:PropertyValue.png|none|thumb|200px|PropertyValue]] | [[Image:PropertyValue.png|none|thumb|200px|PropertyValue]] | ||
| − | This <code>struct</code> has two member variables, <code>Name</code> and <code>Value</code>, and is ubiquitous in sets of <code>PropertyValue</code> structs, where every <code>PropertyValue</code> is a name-value pair that describes a property by name and value. If you need to set the value of such a <code>PropertyValue struct</code>, you must assign an <code>any</code> type, and you must be able to interpret the contained <code>any</code>, if you are reading from a <code>PropertyValue</code>. | + | This <code>struct</code> has two member variables, <code>Name</code> and <code>Value</code>, and is ubiquitous in sets of <code>PropertyValue</code> structs, where every <code>PropertyValue</code> is a name-value pair that describes a property by name and value. If you need to set the value of such a <code>PropertyValue struct</code>, you must assign an <code>any</code> type, and you must be able to interpret the contained <code>any</code>, if you are reading from a <code>PropertyValue</code>. How this is done depends on your language. |
In Java, the <code>any</code> type is mapped to <code>java.lang.Object</code>, but there is also a special Java class <code>com.sun.star.uno.Any</code>, mainly used in those cases where a plain <code>Object</code> would be ambiguous. There are two simple rules of thumb to follow: | In Java, the <code>any</code> type is mapped to <code>java.lang.Object</code>, but there is also a special Java class <code>com.sun.star.uno.Any</code>, mainly used in those cases where a plain <code>Object</code> would be ambiguous. There are two simple rules of thumb to follow: | ||
| − | When you are supposed to pass in an any value, always pass in a <code>java.lang.Object</code> or a Java UNO object. | + | : 1. When you are supposed to pass in an <code>any</code> value, always pass in a <code>java.lang.Object</code> or a Java UNO object. |
For instance, if you use <code>setPropertyValue()</code> to set a property that has a non-interface type in the target object, you must pass in a <code>java.lang.Object</code> for the new value. If the new value is of a primitive type in Java, use the corresponding <code>Object</code> type for the primitive type: | For instance, if you use <code>setPropertyValue()</code> to set a property that has a non-interface type in the target object, you must pass in a <code>java.lang.Object</code> for the new value. If the new value is of a primitive type in Java, use the corresponding <code>Object</code> type for the primitive type: | ||
| Line 49: | Line 49: | ||
</source> | </source> | ||
| − | When you ''receive'' an any instance, always use the <code>com.sun.star.uno.AnyConverter</code> to retrieve its value. | + | : 2. When you ''receive'' an <code>any</code> instance, always use the <code>com.sun.star.uno.AnyConverter</code> to retrieve its value. |
The <code>AnyConverter</code> requires a closer look. For instance, if you want to get a property which contains a primitive Java type, you must be aware that <code>getPropertyValue()</code> returns a <code>java.lang.Object</code> containing your primitive type wrapped in an any value. The <code>com.sun.star.uno.AnyConverter</code> is a converter for such objects. Actually it can do more than just conversion, you can find its specification in the Java UNO reference. The following list sums up the conversion functions in the <code>AnyConverter</code>: | The <code>AnyConverter</code> requires a closer look. For instance, if you want to get a property which contains a primitive Java type, you must be aware that <code>getPropertyValue()</code> returns a <code>java.lang.Object</code> containing your primitive type wrapped in an any value. The <code>com.sun.star.uno.AnyConverter</code> is a converter for such objects. Actually it can do more than just conversion, you can find its specification in the Java UNO reference. The following list sums up the conversion functions in the <code>AnyConverter</code>: | ||
| Line 89: | Line 89: | ||
</source> | </source> | ||
| − | In {{ | + | In {{OOo}} Basic, the <code>any</code> type becomes a Variant: |
<source lang="vb"> | <source lang="vb"> | ||
| − | ' | + | 'OpenOffice.org Basic |
Dim cellColor as Variant | Dim cellColor as Variant | ||
cellColor = oCellProps.CharColor | cellColor = oCellProps.CharColor | ||
Revision as of 01:46, 5 October 2008
The Apache OpenOffice API frequently uses an any type, which is the counterpart of the Variant type known from other environments. The any type holds one arbitrary UNO type. The any type is especially used in generic UNO interfaces.
Examples for the occurrence of any are the method parameters and return values of the following, frequently used methods:
| Interface | returning an any type | taking an any type | |
|---|---|---|---|
| XPropertySet | any getPropertyValue(string propertyName) | void setPropertyValue(any value) | |
| XNameContainer | any getByName(string name) | void replaceByName(string name, any element) | void insertByName(string name, any element) |
| XIndexContainer | any getByIndex(long index) | void replaceByIndex(long index, any element) | void insertByIndex(long index, any element) |
| XEnumeration | any nextElement() | - | |
The any type also occurs in the com.sun.star.beans.PropertyValue struct.
This struct has two member variables, Name and Value, and is ubiquitous in sets of PropertyValue structs, where every PropertyValue is a name-value pair that describes a property by name and value. If you need to set the value of such a PropertyValue struct, you must assign an any type, and you must be able to interpret the contained any, if you are reading from a PropertyValue. How this is done depends on your language.
In Java, the any type is mapped to java.lang.Object, but there is also a special Java class com.sun.star.uno.Any, mainly used in those cases where a plain Object would be ambiguous. There are two simple rules of thumb to follow:
- 1. When you are supposed to pass in an
anyvalue, always pass in ajava.lang.Objector a Java UNO object.
For instance, if you use setPropertyValue() to set a property that has a non-interface type in the target object, you must pass in a java.lang.Object for the new value. If the new value is of a primitive type in Java, use the corresponding Object type for the primitive type:
xCellProps.setPropertyValue("CharWeight", new Double(200.0));
Another example would be a PropertyValue struct you want to use for loadComponentFromURL:
com.sun.star.beans.PropertyValue aProperty = new com.sun.star.beans.PropertyValue(); aProperty.Name = "ReadOnly"; aProperty.Value = Boolean.TRUE;
- 2. When you receive an
anyinstance, always use thecom.sun.star.uno.AnyConverterto retrieve its value.
The AnyConverter requires a closer look. For instance, if you want to get a property which contains a primitive Java type, you must be aware that getPropertyValue() returns a java.lang.Object containing your primitive type wrapped in an any value. The com.sun.star.uno.AnyConverter is a converter for such objects. Actually it can do more than just conversion, you can find its specification in the Java UNO reference. The following list sums up the conversion functions in the AnyConverter:
static java.lang.Object toArray(java.lang.Object object) static boolean toBoolean(java.lang.Object object) static byte toByte(java.lang.Object object) static char toChar(java.lang.Object object) static double toDouble(java.lang.Object object) static float toFloat(java.lang.Object object) static int toInt(java.lang.Object object) static long toLong(java.lang.Object object) static java.lang.Object toObject(Class clazz, java.lang.Object object) static java.lang.Object toObject(Type type, java.lang.Object object) static short toShort(java.lang.Object object) static java.lang.String toString(java.lang.Object object) static Type toType(java.lang.Object object) static int toUnsignedInt(java.lang.Object object) static long toUnsignedLong(java.lang.Object object) static short toUnsignedShort(java.lang.Object object)
Its usage is straightforward:
import com.sun.star.uno.AnyConverter; long cellColor = AnyConverter.toLong(xCellProps.getPropertyValue("CharColor"));
For convenience, for interface types you can directly use UnoRuntime.queryInterface() without first calling AnyConverter.getObject():
import com.sun.star.uno.AnyConverter;import com.sun.star.uno.UnoRuntime; Object ranges = xSpreadsheet.getPropertyValue("NamedRanges"); XNamedRanges ranges1 = (XNamedRanges) UnoRuntime.queryInterface( XNamedRanges.class, AnyConverter.toObject(XNamedRanges.class, r)); XNamedRanges ranges2 = (XNamedRanges) UnoRuntime.queryInterface( XNamedRanges.class, r);
In Apache OpenOffice Basic, the any type becomes a Variant:
'OpenOffice.org Basic Dim cellColor as Variant cellColor = oCellProps.CharColor
In C++, there are special operators for the any type:
//C++ has >>= and <<= for Any (the pointed brackets are always left) sal_Int32 cellColor; Any any; any = rCellProps->getPropertyValue(OUString::createFromAscii( "CharColor" )); // extract the value from any any >>= cellColor;
| Content on this page is licensed under the Public Documentation License (PDL). |
