Eclipse Platform
Release 3.1

org.eclipse.swt.ole.win32
Class Variant

java.lang.Object
  extended byorg.eclipse.swt.ole.win32.Variant

public final class Variant
extends Object

A Variant is a generic OLE mechanism for passing data of different types via a common interface.

It is used within the OleAutomation object for getting a property, setting a property or invoking a method on an OLE Control or OLE Document.


Field Summary
static int sizeof
          A variant always takes up 16 bytes, no matter what you store in it.
 
Constructor Summary
Variant()
          Create an empty Variant object with type VT_EMPTY.
Variant(boolean val)
          Create a Variant object which represents a Java boolean as a VT_BOOL.
Variant(float val)
          Create a Variant object which represents a Java float as a VT_R4.
Variant(org.eclipse.swt.internal.ole.win32.IDispatch idispatch)
          Create a Variant object which represents an IDispatch interface as a VT_Dispatch.
Variant(int val)
          Create a Variant object which represents a Java int as a VT_I4.
Variant(int ptr, short byRefType)
          Create a Variant object which contains a reference to the data being transferred.
Variant(org.eclipse.swt.internal.ole.win32.IUnknown unknown)
          Create a Variant object which represents an IUnknown interface as a VT_UNKNOWN.
Variant(OleAutomation automation)
          Create a Variant object which represents an IDispatch interface as a VT_Dispatch.
Variant(short val)
          Create a Variant object which represents a Java short as a VT_I2.
Variant(String string)
          Create a Variant object which represents a Java String as a VT_BSTR.
 
Method Summary
 void dispose()
          Calling dispose will release resources associated with this Variant.
 OleAutomation getAutomation()
          Returns the OleAutomation object represented by this Variant.
 boolean getBoolean()
          Returns the Java boolean represented by this Variant.
 int getByRef()
          Returns a pointer to the referenced data represented by this Variant.
 org.eclipse.swt.internal.ole.win32.IDispatch getDispatch()
          Returns the IDispatch object represented by this Variant.
 float getFloat()
          Returns the Java float represented by this Variant.
 int getInt()
          Returns the Java int represented by this Variant.
 short getShort()
          Returns the Java short represented by this Variant.
 String getString()
          Returns the Java String represented by this Variant.
 short getType()
          Returns the type of the variant type.
 org.eclipse.swt.internal.ole.win32.IUnknown getUnknown()
          Returns the IUnknown object represented by this Variant.
 void setByRef(boolean val)
          Update the by reference value of this variant with a new boolean value.
 void setByRef(float val)
          Update the by reference value of this variant with a new float value.
 void setByRef(int val)
          Update the by reference value of this variant with a new integer value.
 void setByRef(short val)
          Update the by reference value of this variant with a new short value.
 String toString()
          Returns a string containing a concise, human-readable description of the receiver.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

sizeof

public static final int sizeof
A variant always takes up 16 bytes, no matter what you store in it. Objects, strings, and arrays are not physically stored in the Variant; in these cases, four bytes of the Variant are used to hold either an object reference, or a pointer to the string or array. The actual data are stored elsewhere.

See Also:
Constant Field Values
Constructor Detail

Variant

public Variant()
Create an empty Variant object with type VT_EMPTY.

Since:
2.0

Variant

public Variant(float val)
Create a Variant object which represents a Java float as a VT_R4.

Parameters:
val - the Java float value that this Variant represents

Variant

public Variant(int val)
Create a Variant object which represents a Java int as a VT_I4.

Parameters:
val - the Java int value that this Variant represents

Variant

public Variant(int ptr,
               short byRefType)
Create a Variant object which contains a reference to the data being transferred.

When creating a VT_BYREF Variant, you must give the full Variant type including VT_BYREF such as

short byRefType = OLE.VT_BSTR | OLE.VT_BYREF
.

Parameters:
ptr - a pointer to the data being transferred.
byRefType - the type of the data being transferred such as OLE.VT_BSTR | OLE.VT_BYREF

Variant

public Variant(OleAutomation automation)
Create a Variant object which represents an IDispatch interface as a VT_Dispatch.

Parameters:
automation - the OleAutomation object that this Variant represents

Variant

public Variant(org.eclipse.swt.internal.ole.win32.IDispatch idispatch)
Create a Variant object which represents an IDispatch interface as a VT_Dispatch.

The caller is expected to have appropriately invoked unknown.AddRef() before creating this Variant.

Parameters:
idispatch - the IDispatch object that this Variant represents
Since:
2.0

Variant

public Variant(org.eclipse.swt.internal.ole.win32.IUnknown unknown)
Create a Variant object which represents an IUnknown interface as a VT_UNKNOWN.

The caller is expected to have appropriately invoked unknown.AddRef() before creating this Variant.

Parameters:
unknown - the IUnknown object that this Variant represents

Variant

public Variant(String string)
Create a Variant object which represents a Java String as a VT_BSTR.

Parameters:
string - the Java String value that this Variant represents

Variant

public Variant(short val)
Create a Variant object which represents a Java short as a VT_I2.

Parameters:
val - the Java short value that this Variant represents

Variant

public Variant(boolean val)
Create a Variant object which represents a Java boolean as a VT_BOOL.

Parameters:
val - the Java boolean value that this Variant represents
Method Detail

dispose

public void dispose()
Calling dispose will release resources associated with this Variant. If the resource is an IDispatch or IUnknown interface, Release will be called. If the resource is a ByRef pointer, nothing is released.

Since:
2.1

getAutomation

public OleAutomation getAutomation()
Returns the OleAutomation object represented by this Variant.

If this Variant does not contain an OleAutomation object, an attempt is made to coerce the Variant type into an OleAutomation object. If this fails, an error is thrown. Note that OleAutomation objects must be disposed when no longer needed.

Returns:
the OleAutomation object represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an OleAutomation object

getDispatch

public org.eclipse.swt.internal.ole.win32.IDispatch getDispatch()
Returns the IDispatch object represented by this Variant.

If this Variant does not contain an IDispatch object, an attempt is made to coerce the Variant type into an IDIspatch object. If this fails, an error is thrown.

Returns:
the IDispatch object represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an IDispatch object
Since:
2.0

getBoolean

public boolean getBoolean()
Returns the Java boolean represented by this Variant.

If this Variant does not contain a Java boolean, an attempt is made to coerce the Variant type into a Java boolean. If this fails, an error is thrown.

Returns:
the Java boolean represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a boolean

getByRef

public int getByRef()
Returns a pointer to the referenced data represented by this Variant.

If this Variant does not contain a reference to data, zero is returned.

Returns:
a pointer to the referenced data represented by this Variant or 0

getFloat

public float getFloat()
Returns the Java float represented by this Variant.

If this Variant does not contain a Java float, an attempt is made to coerce the Variant type into a Java float. If this fails, an error is thrown.

Returns:
the Java float represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a float

getInt

public int getInt()
Returns the Java int represented by this Variant.

If this Variant does not contain a Java int, an attempt is made to coerce the Variant type into a Java int. If this fails, an error is thrown.

Returns:
the Java int represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a int

getShort

public short getShort()
Returns the Java short represented by this Variant.

If this Variant does not contain a Java short, an attempt is made to coerce the Variant type into a Java short. If this fails, an error is thrown.

Returns:
the Java short represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a short

getString

public String getString()
Returns the Java String represented by this Variant.

If this Variant does not contain a Java String, an attempt is made to coerce the Variant type into a Java String. If this fails, an error is thrown.

Returns:
the Java String represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a String

getType

public short getType()
Returns the type of the variant type. This will be an OLE.VT_* value or a bitwise combination of OLE.VT_* values as in the case of OLE.VT_BSTR | OLE.VT_BYREF.

Returns:
the type of the variant data
Since:
2.0

getUnknown

public org.eclipse.swt.internal.ole.win32.IUnknown getUnknown()
Returns the IUnknown object represented by this Variant.

If this Variant does not contain an IUnknown object, an attempt is made to coerce the Variant type into an IUnknown object. If this fails, an error is thrown.

Returns:
the IUnknown object represented by this Variant
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an IUnknown object

setByRef

public void setByRef(boolean val)
Update the by reference value of this variant with a new boolean value.

Parameters:
val - the new boolean value
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_BOOL) object
Since:
2.1

setByRef

public void setByRef(float val)
Update the by reference value of this variant with a new float value.

Parameters:
val - the new float value
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_R4) object
Since:
2.1

setByRef

public void setByRef(int val)
Update the by reference value of this variant with a new integer value.

Parameters:
val - the new integer value
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_I4) object
Since:
2.1

setByRef

public void setByRef(short val)
Update the by reference value of this variant with a new short value.

Parameters:
val - the new short value
Throws:
SWTException -
  • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_I2) object
Since:
2.1

toString

public String toString()
Returns a string containing a concise, human-readable description of the receiver.

Returns:
a string representation of the event

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.