Difference between revisions of "Documentation/DevGuide/FirstSteps/Any"

From Apache OpenOffice Wiki
Jump to: navigation, search
(FINAL VERSION FOR L10N)
(11 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:Any}}
+
{{Documentation/DevGuide/FirstStepsTOC
−
{{Documentation/APIGuide/FirstStepsTOC
+
 
|FirstSteps2b=block
 
|FirstSteps2b=block
 
|ShowPrevNext=block
 
|ShowPrevNext=block
−
|PrevPage=Documentation/APIGuide/FirstSteps/Struct
+
|PrevPage=Documentation/DevGuide/FirstSteps/Struct
−
|NextPage=Documentation/APIGuide/FirstSteps/Sequence
+
|NextPage=Documentation/DevGuide/FirstSteps/Sequence
 
}}
 
}}
−
The {{PRODUCTNAME}} 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.
+
{{Documentation/DevGuideLanguages|Documentation/DevGuide/FirstSteps/{{SUBPAGENAME}}}}
 +
{{DISPLAYTITLE:Any}}
 +
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 24: Line 25:
 
|}
 
|}
  
−
Furthermore, the <code>any</code> type occurs in the [http://api.openoffice.org/docs/common/ref/com/sun/star/beans/PropertyValue.html com.sun.star.beans.PropertyValue] struct.  
+
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>. It depends on your language how this is done.
+
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 64: 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 77: 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 {{PRODUCTNAME}} Basic, the any type becomes a Variant:
+
In {{OOo}} Basic, the <code>any</code> type becomes a Variant:
  
−
   '{{PRODUCTNAME}} Basic
+
  <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 92: Line 106:
 
   // extract the value from any
 
   // extract the value from any
 
   any >>= cellColor;
 
   any >>= cellColor;
 +
  </source>
  
 
{{PDL1}}
 
{{PDL1}}
−
[[Category: First Steps]]
+
 
 +
[[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.

PropertyValue

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 a java.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 the com.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).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/FirstSteps/Any&oldid=127808"
Personal tools
In other languages