Difference between revisions of "Documentation/DevGuide/FirstSteps/Any"
(FINAL VERSION FOR L10N) |
|||
(16 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
− | {{ | + | {{Documentation/DevGuide/FirstStepsTOC |
+ | |FirstSteps2b=block | ||
+ | |ShowPrevNext=block | ||
+ | |PrevPage=Documentation/DevGuide/FirstSteps/Struct | ||
+ | |NextPage=Documentation/DevGuide/FirstSteps/Sequence | ||
+ | }} | ||
+ | {{Documentation/DevGuideLanguages|Documentation/DevGuide/FirstSteps/{{SUBPAGENAME}}}} | ||
{{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 18: | Line 24: | ||
|- | |- | ||
|} | |} | ||
− | |||
− | + | The <code>any</code> type also occurs in the <idl>com.sun.star.beans.PropertyValue</idl> struct. | |
− | 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>. | + | [[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>. 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: | ||
+ | <source lang="java"> | ||
xCellProps.setPropertyValue("CharWeight", new Double(200.0)); | xCellProps.setPropertyValue("CharWeight", new Double(200.0)); | ||
+ | </source> | ||
Another example would be a <code>PropertyValue</code> struct you want to use for <code>loadComponentFromURL</code>: | Another example would be a <code>PropertyValue</code> struct you want to use for <code>loadComponentFromURL</code>: | ||
+ | <source lang="java"> | ||
com.sun.star.beans.PropertyValue aProperty = new com.sun.star.beans.PropertyValue(); | com.sun.star.beans.PropertyValue aProperty = new com.sun.star.beans.PropertyValue(); | ||
aProperty.Name = "ReadOnly"; | aProperty.Name = "ReadOnly"; | ||
aProperty.Value = Boolean.TRUE; | aProperty.Value = Boolean.TRUE; | ||
+ | </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>: | ||
+ | <source lang="java"> | ||
static java.lang.Object toArray(java.lang.Object object) | static java.lang.Object toArray(java.lang.Object object) | ||
static boolean toBoolean(java.lang.Object object) | static boolean toBoolean(java.lang.Object object) | ||
Line 58: | Line 70: | ||
static long toUnsignedLong(java.lang.Object object) | static long toUnsignedLong(java.lang.Object object) | ||
static short toUnsignedShort(java.lang.Object object) | static short toUnsignedShort(java.lang.Object object) | ||
+ | </source> | ||
Its usage is straightforward: | Its usage is straightforward: | ||
+ | <source lang="java"> | ||
import com.sun.star.uno.AnyConverter; | import com.sun.star.uno.AnyConverter; | ||
long cellColor = AnyConverter.toLong(xCellProps.getPropertyValue("CharColor")); | long cellColor = AnyConverter.toLong(xCellProps.getPropertyValue("CharColor")); | ||
+ | </source> | ||
For convenience, for interface types you can directly use <code>UnoRuntime.queryInterface()</code> without first calling <code>AnyConverter.getObject()</code>: | For convenience, for interface types you can directly use <code>UnoRuntime.queryInterface()</code> without first calling <code>AnyConverter.getObject()</code>: | ||
+ | <source lang="java"> | ||
import com.sun.star.uno.AnyConverter;import com.sun.star.uno.UnoRuntime; | import com.sun.star.uno.AnyConverter;import com.sun.star.uno.UnoRuntime; | ||
Object ranges = xSpreadsheet.getPropertyValue("NamedRanges"); | Object ranges = xSpreadsheet.getPropertyValue("NamedRanges"); | ||
Line 71: | Line 87: | ||
XNamedRanges.class, AnyConverter.toObject(XNamedRanges.class, r)); | XNamedRanges.class, AnyConverter.toObject(XNamedRanges.class, r)); | ||
XNamedRanges ranges2 = (XNamedRanges) UnoRuntime.queryInterface( XNamedRanges.class, r); | XNamedRanges ranges2 = (XNamedRanges) UnoRuntime.queryInterface( XNamedRanges.class, r); | ||
+ | </source> | ||
− | In {{ | + | In {{OOo}} Basic, the <code>any</code> type becomes a Variant: |
− | ' | + | <source lang="vb"> |
+ | 'OpenOffice.org Basic | ||
Dim cellColor as Variant | Dim cellColor as Variant | ||
cellColor = oCellProps.CharColor | cellColor = oCellProps.CharColor | ||
+ | </source> | ||
In C++, there are special operators for the <code>any</code> type: | In C++, there are special operators for the <code>any</code> type: | ||
+ | <source lang="cpp"> | ||
//C++ has >>= and <<= for Any (the pointed brackets are always left) | //C++ has >>= and <<= for Any (the pointed brackets are always left) | ||
sal_Int32 cellColor; | sal_Int32 cellColor; | ||
Line 86: | Line 106: | ||
// extract the value from any | // extract the value from any | ||
any >>= cellColor; | any >>= cellColor; | ||
+ | </source> | ||
{{PDL1}} | {{PDL1}} | ||
− | [[Category: | + | |
+ | [[Category:Documentation/Developer's Guide/First Steps]] |
Revision as of 09:17, 18 May 2009
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
any
value, always pass in ajava.lang.Object
or 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
any
instance, always use thecom.sun.star.uno.AnyConverter
to 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). |