Mapping of Simple Types

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

In general, the OpenOffice.org Basic type system is not rigid. Unlike C++ and Java, OpenOffice.org Basic does not require the declaration of variables, unless the Option Explicit command is used that forces the declaration. To declare variables, the Dim command is used. Also, a OpenOffice.org Basic type can be optionally specified through the Dim command. The general syntax is:

 Dim VarName [As Type][, VarName [As Type]]...

All variables declared without a specific type have the type Variant. Variables of type Variant can be assigned values of arbitrary Basic types. Undeclared variables are Variant unless type postfixes are used with their names. Postfixes can be used in Dim commands as well. The following table contains a complete list of types supported by Basic and their corresponding postfixes:

Type	Postfix	Range
Boolean		True or False
Integer	%	-32768 to 32767
Long	&	-2147483648 to 2147483647
Single	!	Floating point number negative: -3.402823E38 to -1.401298E-45 positive: 1.401298E-45 to 3.402823E38
Double	#	Double precision floating point number negative: -1.79769313486232E308 to -4.94065645841247E-324 positive: 4.94065645841247E-324 to 1.79769313486232E308
Currency	@	Fixed point number with four decimal places -922,337,203,685,477.5808 to 922,337,203,685,477.5807
Date		01/01/100 to 12/31/9999
Object		Basic Object
String	$	Character string
Variant		arbitrary Basic type

Consider the following Dim examples.

 Dim a, b ' Type of a and b is Variant
 Dim c as Variant ' Type of c is Variant
 
 Dim d as Integer ' Type of d is Integer (16 bit!)
 
 ' The type only refers to the preceding variable
 Dim e, f as Double ' ATTENTION! Type of e is Variant!
 ' Only the type of f is Double
 
 Dim g as String ' Type of g is String
 
 Dim h as Date ' Type of h is Date
 
 ' Usage of Postfixes
 Dim i% ' is the same as
 Dim i as Integer
 
 Dim d# ' is the same as
 Dim d as Double
 
 Dim s$ ' is the same as
 Dim s as String

The correlation below is used to map types from UNO to Basic and vice versa.

UNO	Basic
void	internal type
boolean	Boolean
byte	Integer
short	Integer
unsigned short	internal type
long	Long
unsigned long	internal type
hyper	internal type
unsigned hyper	internal type
float	Single
double	Double
char	internal type
string	String
type	com.sun.star.reflection.XIdlClass
any	Variant

The simple UNO type type is mapped to the com.sun.star.reflection.XIdlClass interface to retrieve type specific information. For further details, refer to UNO Reflection API.

When UNO methods or properties are accessed, and the target UNO type is known, Basic automatically chooses the appropriate types:

 ' The UNO object oExample1 has a property "Count" of type short
 a% = 42
 oExample1.Count = a% ' a% has the right type (Integer)
 
 pi = 3,141593
 oExample1.Count = pi ' pi will be converted to short, so Count will become 3
 
 s$ = "111"
 oExample1.Count = s$ ' s$ will be converted to short, so Count will become 111

Occasionally, OpenOffice.org Basic does not know the required target type, especially if a parameter of an interface method or a property has the type any. In this situation, OpenOffice.org Basic mechanically converts the OpenOffice.org Basic type into the UNO type shown in the table above, although a different type may be expected. The only mechanism provided by OpenOffice.org Basic is an automatic downcast of numeric values:

Long and Integer values are always converted to the shortest possible integer type:

• to byte if -128 <= Value <= 127
• to short if -32768 <= Value <= 32767

The Single/Double values are converted to integers in the same manner if they have no decimal places.

This mechanism is used, because some internal C++ tools used to implement UNO functionality in OpenOffice.org provide an automatic upcast but no downcast. Therefore, it can be successful to pass a byte value to an interface expecting a long value, but not vice versa.

In the following example, oNameCont is an object that supports com.sun.star.container.XNameContainer and contains elements of type short. Assume FirstValue is a valid entry.

 a% = 42
 oNameCount.replaceByName( "FirstValue", a% ) ' Ok, a% is downcasted to type byte
 
 b% = 123456
 oNameCount.replaceByName( "FirstValue", b% ) ' Fails, b% is outside the short range

The method call fails, therefore the implementation should throw the appropriate exception that is converted to a OpenOffice.org Basic error by the OpenOffice.org Basic RTL. It may happen that an implementation also accepts unsuitable types and does not throw an exception. Ensure that the values used are suitable for their UNO target by using numeric values that do not exceed the target range or converting them to the correct Basic type before applying them to UNO.

Always use the type Variant to declare variables for UNO Basic objects, not the type Object. The OpenOffice.org Basic type Object is tailored for pure OpenOffice.org Basic objects and not for UNO OpenOffice.org Basic objects. The Variant variables are best for UNO Basic objects to avoid problems that can result from the OpenOffice.org Basic specific behavior of the type Object:

 Dim oService1 ' Ok
 oService1 = CreateUnoService( "com.sun.star.anywhere.Something" )
 
 Dim oService2 as Object ' NOT recommended
 oService2 = CreateUnoService( "com.sun.star.anywhere.SomethingElse" )

Content on this page is licensed under the Public Documentation License (PDL).