libreOffice API是用于访问libreOffice的编程接口。可以使用libreOffice API创建、打开、修改和打印libreOffice文档。
LibreOffice API支持Basic、Java、C/C++、Javascript、Python语言。
这是通过一种称为通用网络对象 (Universal Network Objects, UNO) 的技术实现的,该技术可以为各种编程语言提供接口。
https://api.libreoffice.org/docs/idl/ref/index.html
一、uno概念
(一)类型
uno类型使用一种称为UNOIDL(UNO接口定义语言)的语言定义,这种语言与CORBA IDL或MIDL类似。
1.简单类型
UNO类型 | 说明 |
---|---|
void | 空类型,仅在any中用作方法返回类型。 |
boolean | 可以是true或false。 |
byte | 有符号的8位整数类型(范围从 -128到127,包括上下限)。 |
short | 有符号的16位整数类型(范围从 -32768到32767,包括上下限)。 |
unsigned short | 无符号的16位整数类型(已不再使用)。 |
long | 有符号的32位整数类型(范围从 -2147483648到2147483647,包括上下限)。 |
unsigned long | 无符号的32位整数类型(已不再使用)。 |
hyper | 有符号的64位整数类型(范围从 -9223372036854775808到9223372036854775807,包括上下限)。 |
unsigned hyper | 无符号的64位整数类型(已不再使用)。 |
float | IEC 60559单精度浮点类型。 |
double | IEC 60559双精度浮点类型。 |
char | 表示单个的Unicode字符(更确切地说是单个的UTF-16代码单元)。 |
string | 表示Unicode字符串(更确切地说是Unicode标量值的字符串)。 |
type | 说明所有UNO类型的元类型。 |
any | 能够表示其他所有类型值的特殊类型。 |
2.struct 类型
结构体包括一堆数据成员,但不能包括方法。
结构体支持单继承。
struct EventObject{
com::sun::star::uno::XInterface Source;
};
struct PropertyChangeEvent : com::sun::star::lang::EventObject {
string PropertyName;
boolean Further;
long PropertyHandle;
any OldValue;
any NewValue;
};
3.sequence
序列就是一个动态数组。就像c++的vector
sequence< com::sun::star::uno::XInterface >
sequence< string > getNamesOfIndex( sequence< long > indexes );
4.interface类型
接口就是个抽象类。接口是一系列方法的声明,一个接口只有方法的声明没有方法的实现,因此这些方法可以在不同的类实现,而这些实现可以是不同的行为。
严格说来,UNO服务不支持方法,方法只在接口中,而服务继承了接口。
因为不同的服务会继承相同接口,所以如果您熟悉某个接口,便可以迅速了解不同服务。
按照约定,所有接口名称都以字母X开头,以将接口类型与其他类型区分开来。所有接口类型最终都必须继承com.sun.star.uno.XInterface根接口
interface XInterface {
any queryInterface( [in] type aType );
[oneway] void acquire();
[oneway] void release();
};
interface XInputStream: com::sun::star::uno::XInterface {
long readBytes( [out] sequence<byte> aData, [in] long nBytesToRead )
raises( com::sun::star::io::NotConnectedException, com::sun::star::io::BufferSizeExceededException, com::sun::star::io::IOException);
...
};
方法
就是接口的成员函数
Document.Save()
5.service
接口定义了方法;结构定义了数据;服务将它们组合在一起。
服务相当于类,不知道为啥非得叫服务。
通过服务,可以创建对象实例。
com.sun.star.frame.Desktop类似于一种对象类型,但在UNO术语中,将其称为“服务”而不是“类型”。按照UNO术语,Obj是支持com.sun.star.frame.Desktop服务的对象。因此,libreOffice Basic中使用的“服务”术语与其他编程语言中使用的“类型”和“类”术语相对应。
但存在一个主要区别:uno可以同时支持多种服务。例如,上面提到的obj对象不仅支持com.sun.star.frame.Desktop服务,还可以包括用于加载文档和结束程序的其他服务。
服务包括新式服务和旧式服务。
新式服务是通过仅支持一个多继承接口,该多继承接口再继承其他接口实现的
旧式服务是直接支持多个单继承接口实现的
新式服务
service SomeService: XSomeInterface;
interface XSomeInterface
{
interface XInterface1;
interface XInterface2;
interface XInterface3;
...
};
旧式服务
service SomeService{
interface XInterface1;
interface XInterface2;
interface XInterface3;
...
};
旧式服务可以包括其他旧式服务。如下例
service Paragraph
{
service com::sun::star::text::TextContent;
[optional] service com::sun::star::text::TextTable;
[optional] service com::sun::star::style::ParagraphProperties;
[optional] service com::sun::star::style::CharacterProperties;
[optional] service com::sun::star::style::CharacterPropertiesAsian;
[optional] service com::sun::star::style::CharacterPropertiesComplex;
...
};
如果上面示例中的所有旧式服务都使用多继承接口类型代替,则结构类似:
service Paragraph: XParagraph;
interface XParagraph
{
interface XTextContent;
[optional] interface XTextTable;
...
};
从用户的角度来看,无论对象提供一项服务或者多项服务,是新式还是旧式服务,由于方法仅由接口提供,因此,用户无需关心如何实现。
属性
属性是服务中的数据
(1)真实属性
就是服务的数据成员
Document.Title = "Basic Programmer's Guide"
Document.Filename = "basguide.odt"
(2)模拟属性
模拟属性就是通过get和set方法模拟的。
所以其实有两种方式访问属性:
通过Position属性直接访问。
通过getPosition和setPosition间接访问
旧式服务可直接列出支持的属性。
下面的旧式服务引用了一个接口和三个可选属性。属性可以是任何类型:
service TextContent{
interface com::sun::star::text::XTextContent;
[optional, property] com::sun::star::text::TextContentAnchorType AnchorType;
[optional, readonly, property] sequence<com::sun::star::text::TextContentAnchorType> AnchorTypes;
[optional, property] com::sun::star::text::WrapTextMode TextWrap;
};
6.预定义值
预定义值有两种不同的数据类型:常数和枚举。
const
const 定义有效UNO IDL类型的命名值。值取决于指定的类型,可以是常值(整数、浮点数或字符)、另一个const类型的标识符或包含以下运算符的算术项:+、-、*、/、~、&、|、%、^、 <<、>>。
由于可以在 const 中广泛选择类型和值,因此,const 有时用于生成对合并的值进行编码的位矢量。
const short ID = 23;
const boolean ERROR = true;
const double PI = 3.1415;
通常情况下,const定义是常数组的一部分。
constants
constants 类型定义的是包含多个 const 值的一个命名组。constants 组中的 const 用组名称加上 const 名称表示。在下面的UNO IDL示例中,ImageAlign.RIGHT 指的是值2:
constants ImageAlign {
const short LEFT = 0;
const short TOP = 1;
const short RIGHT = 2;
const short BOTTOM = 3;
};
enum
enum 类型与C++ 中的枚举类型相当。它包含一个已排序列表,列表中有一个或多个标识符,代表 enum 类型的各个值。默认情况下,值按顺序编号,以0开头,每增加一个新值就增加1。如果给某个 enum 值指定了一个值,则没有预定义值的所有后续 enum 值都以此指定值为基准来获得值。
// com.sun.star.uno.TypeClass
enum TypeClass {
VOID,
CHAR,
BOOLEAN,
BYTE,
SHORT,
...
};
enum Error {
SYSTEM = 10, // value 10
RUNTIME, // value 11
FATAL, // value 12
USER = 30, // value 30
SOFT // value 31
};
7.module
模块是命名空间,与C++ 中的命名空间或Java中的包类似
模块将服务、接口等类型组合在一起。形成良好的组织结构。
所以完整的类型名称由以下部分组成:com.sun.star是共同的模块名称,然后是特定模块名称,最后是实际的类型名称。
例如,服务Desktop的完整名称为:com.sun.star.frame.Desktop
接口XTextContent的完整名称为:com.sun.star.text.XTextContent
模块 com.sun.star.uno 包含接口 XInterface,IDL写法如下:
module com {module sun {module star {module uno {
interface XInterface {
...
};};};};};
(二)对象
广义的对象就是各种类型的实例。
狭义的对象只是服务的实例。
二、libreoffice basic语言绑定
语言绑定就是如何使用某种语言调用uno。
语言绑定有时称为UNO运行时环境 ( URE)。
uno支持c++、java、python、libreoffice basic语言绑定。
我们现在使用libreoffice basic语言,所以下面要讲解libreoffice basic绑定。
主要是下面这些
BasicLibraries | ccess Basic libraries stored in a document. |
CreateObject(obj_type) |
Able to create any standard type, more flexible than CreateUnoStruct and CreateUnoService. |
CreateUnoDialog() | Create an existing dialog. |
CreateUnoListener() | Create a listener. |
CreateUnoService() | Create a Universal Network Object Service. |
CreateUnoStruct() | Create a Universal Network Object Structure. |
CreateUnoValue() | Create a Universal Network Object value. |
DialogLibraries | Access dialog libraries stored in a document. |
EqualUNOObjects() | Determine if two UNO objects reference the same instance. |
FindObject() | Find a named object; do not use. |
FindPropertyObject() | Find object property based on name; do not use. |
GetDefaultContext() | Get a copy of the default context. |
GetProcessServiceManager() | Get service manager. |
GlobalScope | Application-level libraries. |
HasUnoInterfaces() | Does an object support specified interfaces? |
IsUnoStruct() | Is this variable a Universal Network Object? |
StarDesktop |
Special variable representing the desktop object. |
ThisComponent | Special variable representing the current document. |
(一)类型
Basic和UNO使用不同的类型系统,有必要映射这两种类型系统。
下面讲basic定义和使用各种类型变量
(1)简单类型
UNO | Basic |
---|---|
void | 内部类型 |
boolean | Boolean |
byte | Integer |
short | Integer |
unsigned short | 内部类型 |
long | Long |
unsigned long | 内部类型 |
hyper | 内部类型 |
unsigned hyper | 内部类型 |
float | Single |
double | Double |
char | 内部类型 |
string | String |
type | com.sun.star.reflection.XIdlClass |
any | Variant |
Basic类型系统并不严格。与C++ 和Java不同,Basic不要求声明变量,未声明的变量为Variant。
在未指定类型的情况下,声明的所有变量都为 Variant 类型。可以将任意Basic类型的值指定给类型为 Variant 的变量。
为了方便,尽量使用Variant类型,而且不必声明变量。
因为Basic会自动转换到uno类型。
当Basic不知道目标uno类型时,尤其是类型为any时。在这种情况下,Basic会机械地将Basic类型转换成上表中所示的UNO类型。Basic提供的唯一机制是自动向下转换数值:
Long和Integer值通常转换为尽可能短的整数类型:
- 如果 -128 <= Value <= 127, 转换为byte
- 如果 -32768 <= Value <= 32767, 转换为short
如果Single/Double值不带小数位,则以同样的方式转换为整数。
(2)结构
可以通过Dim As New创建结构实例
' Instantiate a Property struct
Dim aProperty As New com.sun.star.beans.Property
' Instantiate an array of Locale structs
Dim Locales(10) As New com.sun.star.lang.Locale
也可以使用CreateUnoStruct函数创建UNO结构实例
Dim aProp
aProp = CreateUnoStruct("com.sun.star.beans.PropertyValue")
aProp.Name = "FirstName" 'Set the Name property
aProp.Value = "Andrew" 'Set the Value property
函数CreateUnoStruct过去是创建UNO结构的唯一方法。自从引入“Dim As New”语法,它很少使用了。
CreateObject函数比CreateUnoStruct更通用。它能够创建所有类型的实例。这包括用户定义的类型。
Dim aProp
aProp = CreateObject("com.sun.star.beans.PropertyValue")
aProp.Name = "FirstName" 'Set the Name property
aProp.Value = "Paterton" 'Set the Value property
创建用户定义类型实例
Type PersonType
FirstName As String
LastName As String
End Type
Sub ExampleCreateNewType
Dim Person As PersonType
Person.FirstName = "Andrew"
Person.LastName = "Pitonyak"
PrintPerson(Person)
Dim Me As Object
Me = CreateObject("PersonType")
Me.FirstName = "Andy"
Me.LastName = "Pitonyak"
PrintPerson(Me)
End Sub
Sub PrintPerson(x)
Print "Person = " & x.FirstName & " " & x.LastName
End Sub
对于用户定义的类型,“Dim As New”和“Dim As”都可以使用。但是,对于UNO结构, 你必须使用Dim As New
CreateObject与CreateUnoStruct有相同的参数,但它适用于所有支持的类型, 而CreateUnoStruct仅适用于UNO结构。所以尽量使用CreateObject。
可以使用 . 运算符访问结构成员。
结构支持Dbg_Properties属性。不支持属性Dbg_SupportedInterfaces和Dbg_Methods:
' Instantiate a Locale struct
Dim aLocale As New com.sun.star.lang.Locale
' Display properties
MsgBox aLocale.Dbg_Properties
' Access“Language”property
aLocale.Language = "en"
服务实例与结构实例不同。服务实例使用引用传递,而结构实例使用值传递。
在以下示例中,oExample是一个服务实例,具有属性MyObject和MyStruct。
- MyObject是个服务,有一个属性ObjectName。
- MyStruct是个结构,有一个属性StructName。
oExample.MyObject.ObjectName和oExample.MyStruct.StructName都应该修改。
' Accessing the object
Dim oObject
oObject = oExample.MyObject
oObject.ObjectName = “Tim” ' Ok!
' or shorter
oExample.MyObject.ObjectName = “Tim” ' Ok!
' Accessing the struct
Dim aStruct
aStruct = oExample.MyStruct ' aStruct is a copy of oExample.MyStruct!
aStruct.StructName = “Tim” ' Affects only the property of the copy!
' If the code ended here, oExample.MyStruct wouldn't be modified!
oExample.MyStruct = aStruct ' Copy back the complete struct! Now it's ok!
' Here the other variant does NOT work at all, because
' only a temporary copy of the struct is modified!
oExample.MyStruct.StructName = “Tim” ' WRONG! oExample.MyStruct is not modified!
测试对象是否为一个结构
使用IsUnoStruct检查对象是否为UNO结构
Dim aProperty As New com.sun.star.beans.Property
bIsStruct = IsUnoStruct( aProperty )
MsgBox bIsStruct ' Displays True because aProperty is a struct
bIsStruct = IsUnoStruct( 42 )
MsgBox bIsStruct ' Displays False because 42 is NO struct
(3)序列和数组映射
Basic中,与序列相对应的是数组。数组是Basic语言的标准元素。
当UNO需要一个序列时,Basic程序员可以使用一个相应的数组。在以下示例中,oSequenceContainer是一个对象,其具有一个类型为sequence<short> 的属性TheSequence。要将一个长度为10、值为0, 1, 2, ...9的序列指定给该属性,可以使用以下代码:
Dim i%, a%( 9 ) ' Maximum index 9 -> 10 elements
for i% = 0 to 9 ' this loop initializes the array
a%(i%) = i%
next i%
oSequenceContainer.TheSequence = a%()
' If“TheSequence”is based on XPropertySet alternatively
oSequenceContainer.setPropertyValue( “TheSequence”, a%() )
Basic程序员在编程时,需要了解不同的索引语义。在以下示例中,程序员传送包含一个元素的序 列,但实际上传送了两个元素:
' Pass a sequence of length 1 to the TheSequence property:
Dim a%( 1 ) ' WRONG: The array has 2 elements, not only 1!
a%( 0 ) = 3 ' Only Element 0 is initialized,
' Element 1 remains 0 as initialized by Dim
' Now a sequence with two values (3,0) is passed what
' may result in an error or an unexpected behavior!
oSequenceContainer.setPropertyValue( “TheSequence”, a%() )
将Basic数组作为一个整体用于参数或用于属性访问时,在Basic代码中数组后面应始终跟有 '()',否则,某些情况下可能会发生错误。 |
使用一个称为Array()的Basic函数,通过一步就可以创建、初始化数组并将它指定给Variant变量,这非常有用,尤其是对于小型序列:
Dim a ' should be declared as Variant
a = Array( 1, 2, 3 )
' is the same as
Dim a(2)
a( 0 ) = 1
a( 1 ) = 2
a( 2 ) = 3
有时,有必要将空序列传送到UNO接口。在Basic中,可以通过在Dim命令中忽略索引来声明空序列:
Dim a%() ' empty array/sequence of type Integer
Dim b$() ' empty array/sequence of String
UNO返回的序列在Basic中也表示为数组,但不必事先声明这些数组。应该将用于接受序列的变量声明为Variant。要访问UNO返回的数组,需要LBound() 和UBound() 获得元素索引。
函数LBound() 返回下限索引,而UBound() 返回上限索引。以下代码示意了一个循环,该循环将遍历所返回序列的所有元素:
Dim aResultArray ' should be declared as Variant
aResultArray = oSequenceContainer.TheSequence
dim i%, iFrom%, iTo%
iFrom% = LBound( aResultArray() )
iTo% = UBound( aResultArray() )
for i% = iFrom% to iTo% ' this loop displays all array elements
msgbox aResultArray(i%)
next i%
UNO返回序列的索引通常从0开始。一般仅使用UBound(),这时上面的示例可以简化为:
Dim aResultArray ' should be declared as Variant
aResultArray = oSequenceContainer.TheSequence
Dim i%, iTo%
iTo% = UBound( aResultArray() )
For i% = 0 To iTo% ' this loop displays all array elements
MsgBox aResultArray(i%)
Next i%
序列/数组的元素数目非常容易计算:
u% = UBound( aResultArray() )
ElementCount% = u% + 1
对于空数组/序列,UBound返回 -1。这样,随后按如下所示计算元素数目时,UBound的语义就可以保持一致:
ElementCount% = u% + 1' = -1 + 1 = 0
UNO序列与Basic数组之间的映射前提二者都使用一个基于零的索引系统。为了避免出现问题,不要使用语法Dim a ( IndexMin to IndexMin ) 或Basic命令Option Base 1。这二者使所有Basic数组的索引都不是从0开始。 |
UNO还支持包含序列的序列。在Basic中,这对应于包含数组的数组。不要将包含序列的序列与多维数组相混淆。在多维数组中,所有子数组始终具有相同数目的元素,而在包含序列的序列中,每个序列可以具有不同的大小。示例:
Dim aArrayOfArrays ' should be declared as Variant
aArrayOfArrays = oExample.ShortSequences ' returns a sequence of sequences of short
Dim i%, NumberOfSequences%
Dim j%, NumberOfElements%
Dim aElementArray
NumberOfSequences% = UBound( aArrayOfArrays() ) + 1
For i% = 0 to NumberOfSequences% - 1' loop over all sequences
aElementArray = aArrayOfArrays( i% )
NumberOfElements% = UBound( aElementArray() ) + 1
For j% = 0 to NumberOfElements% - 1 ' loop over all elements
MsgBox aElementArray( j% )
Next j%
Next i%
要在Basic中创建一个包含数组的数组,可以将子数组作为主数组的元素::
' Declare master array
Dim aArrayOfArrays( 2 )
' Declare sub arrays
Dim aArray0( 3 )
Dim aArray1( 2 )
Dim aArray2( 0 )
' Initialise sub arrays
aArray0( 0 ) = 0
aArray0( 1 ) = 1
aArray0( 2 ) = 2
aArray0( 3 ) = 3
aArray1( 0 ) = 42
aArray1( 1 ) = 0
aArray1( 2 ) = -42
aArray2( 0 ) = 1
' Assign sub arrays to the master array
aArrayOfArrays( 0 ) = aArray0()
aArrayOfArrays( 1 ) = aArray1()
aArrayOfArrays( 2 ) = aArray2()
' Assign the master array to the array property
oExample.ShortSequences = aArrayOfArrays()
在这种情况下,运行时函数Array() 非常有用。这样,示例代码就可以变得更加简练:
' Declare master array
Dim aArrayOfArrays( 2 )
' Create and assign sub arrays
aArrayOfArrays( 0 ) = Array( 0, 1, 2, 3 )
aArrayOfArrays( 1 ) = Array( 42, 0, -42 )
aArrayOfArrays( 2 ) = Array( 1 )
' Assign the master array to the array property
oExample.ShortSequences = aArrayOfArrays()
如果嵌套使用Array(),就可以编写更简练的代码,但会使得人们难以理解将要生成的数组:
' Declare master array variable as variant
Dim aArrayOfArrays
' Create and assign master array and sub arrays
aArrayOfArrays = Array( Array( 0, 1, 2, 3 ), Array( 42, 0, -42 ), Array( 1 ) )
' Assign the master array to the array property
oExample.ShortSequences = aArrayOfArrays()
对于更高阶次的序列,也可以进行相应处理。
(4)常数和枚举映射
使用符合命名规则的名称对枚举类型的值进行寻址。以下示例假定oExample和oExample2支持 com.sun.star.beans.XPropertySet,并包含一个枚举类型为 com.sun.star.beans.PropertyState 的属性Status:
Dim EnumValue
EnumValue = com.sun.star.beans.PropertyState.DEFAULT_VALUE
MsgBox EnumValue ' displays 1
eExample.Status = com.sun.star.beans.PropertyState.DEFAULT_VALUE
Basic不支持枚举类型。在Basic中,来自UNO的枚举值被转换成Long值。只要Basic知道某个属性或某个接口方法参数是否需要一个枚举类型,就在内部将Long值转换为适当的枚举类型。当接口访问方法需要一个Any:
Dim EnumValue
EnumValue = oExample.Status ' EnumValue is of type Long
' Accessing the property implicitly
oExample2.Status = EnumValue ' Ok! EnumValue is converted to the right enum type
' Accessing the property explicitly using XPropertySet methods
oExample2.setPropertyValue( "Status", EnumValue ) ' WRONG! Will probably fail!
显式访问会失败,因为EnumValue是作为Any类型的参数传递到setPropertyValue(),因此,Basic不知道实际需要一个PropertyState类型的值。还有一个问题,在Basic中,com.sun.star.beans.PropertyState 的类型为Long。此问题在 com.sun.star.beans.XPropertySet 接口的实现中得以解决。对于枚举类型,使用Basic属性语法Object.Property来访问隐式属性优于使用类型Any来调用普通方法。如果仅存在需要Any类型的enum变量的普通接口方法,则没有适用于Basic的解决方案。
常数组用于在IDL中指定一组常数值。在Basic中,可以使用其全限定名称访问这些常数。以下代码显示了 com.sun.star.beans.PropertyConcept 中的一些常数:
MsgBox com.sun.star.beans.PropertyConcept.DANGEROUS ' Displays 1
MsgBox com.sun.star.beans.PropertyConcept.PROPERTYSET ' Displays 2
可以将常数组或枚举指定给对象。如果需要访问多个枚举或常数值,使用此方法可以缩短代码:
Dim oPropConcept
oPropConcept = com.sun.star.beans.PropertyConcept
msgbox oPropConcept.DANGEROUS ' Displays 1
msgbox oPropConcept.PROPERTYSET ' Displays 2
(5)接口
Basic将UNO接口映射成Basic对象方法
在Java和C++中,调用接口中的一个方法之前,需要获取接口。
在Basic中,可以直接调用该对象支持的任何接口的任何方法,而无需提前查询相应的接口。
使用的是 '.' 运算符:
' Basic
oExample = getExampleObjectFromSomewhere()
oExample.doNothing()' Calls method doNothing of XFoo1
oExample.doSomething()' Calls method doSomething of XFoo2
oExample.doSomethingElse(42)' Calls method doSomethingElse of XFoo2
此外,如果UNO对象的get和set方法符合以下模式,则Basic将它们映射为Basic对象属性:
SomeType getSomeProperty()
void setSomeProperty(SomeType aValue)
在此模式中,Basic提供了一个类型为SomeType、名称为SomeProperty的属性。
x = oExample.getIt() ' Calls getIt method of XFoo3
' is the same as
x = oExample.It ' Read property It represented by XFoo3
oExample.setIt( x ) ' Calls setIt method of XFoo3
' is the same as
oExample.It = x ' Modify property It represented by XFoo3
如果只有get方法,而没有set方法,则属性被视为只读。
x = oExample.getMore() ' Calls getMore method of XFoo1
y = oExample.getLess() ' Calls getLess method of XFoo1
' is the same as
x = oExample.More ' Read property More represented by XFoo1
y = oExample.Less ' Read property Less represented by XFoo1
' but
oExample.More = x ' Runtime error "Property is read only"
oExample.Less = y ' Runtime error "Property is read only"
可以直接访问com.sun.star.beans.XPropertySet提供的属性。
也可以使用com.sun.star.beans.XPropertySet中的方法访问属性。
x = oExample2.Value1
y = oExample2.Value2
z = oExample2.Value3
' is the same as
x = oExample2.getPropertyValue( "Value1" )
y = oExample2.getPropertyValue( "Value2" )
z = oExample2.getPropertyValue( "Value3" )
' and
oExample2.Value1 = x
oExample2.Value2 = y
oExample2.Value3 = z
' is the same as
oExample2.setPropertyValue( "Value1", x )
oExample2.setPropertyValue( "Value2", y )
oExample2.setPropertyValue( "Value3", z )
检查接口
尽管Basic不像C++ 和Java那样支持queryInterface概念,但有一个函数HasUnoInterfaces() 用于进行此项检测。
第一个参数HasUnoInterfaces() 需要的是应该接受测试的对象。接着可以将一个或多个全限定的接口名称参数传送到该函数。如果对象支持所有这些接口,则函数返回True,否则返回False。
oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
IfaceName1$ = "com.sun.star.uno.XInterface"
IfaceName2$ = "com.sun.star.ucb.XSimpleFileAccess2"
IfaceName3$ = "com.sun.star.container.XPropertySet"
bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$ )
MsgBox bSuccess ' Displays True because XInterface is supported
bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$ )
MsgBox bSuccess ' Displays True because XInterface
' and XSimpleFileAccess2 are supported
bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName3$ )
MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$, IfaceName3$ )
MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
(6)服务
每个UNO对象都是服务的实例化。
uno对象映射为basic的variant类型,而不是object类型,因为object类型为纯粹basic对象。
有两种方法获得对象:
a.创建新对象
服务管理器com.sun.star.lang.ServiceManager,按服务名称实例化服务。
服务管理器的接口com.sun.star.lang.XMultiServiceFactory
它提供三个方法:createInstance()、createInstanceWithArguments() 和getAvailableServiceNames()。
使用GetProcessServiceManager()获取服务管理器
createInstance() 创建一个服务实例
oServiceMgr = GetProcessServiceManager()
oSimpleFileAccess = oServiceMgr.createInstance( "com.sun.star.ucb.SimpleFileAccess" )
createInstanceWithArguments() 使用参数创建一个服务实例。可能有些服务必须使用参数来实例化。
GetProcessServiceManager() 的优势是:使用服务管理器实例化服务时,可以接收附加信息和传入的参数。
Dim args(1)
args(0) = "Important information"
args(1) = "Even more important information"
oService = oServiceMgr.createInstanceWithArguments("com.sun.star.nowhere.ServiceThatNeedsInitialization", args() )
getAvailableServiceNames() 返回支持的所有服务名称。
sServices = GetProcessServiceManager().getAvailableServiceNames()
Print sServices
CreateUnoService函数是创建UNO服务实例的快捷方式,它本质上还是使用服务管理器创建实例。
oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
此调用实例化 com.sun.star.ucb.SimpleFileAccess 服务。为确保函数成功,可以使用IsNull函数检查返回的对象:
oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
bError = IsNull( oSimpleFileAccess )' bError is set to False
oNoService = CreateUnoService( "com.sun.star.nowhere.ThisServiceDoesNotExist" )
bError = IsNull( oNoService )' bError is set to True
CreateUnoServiceWithArguments实例化UNO服务,包括补充的可选参数。
dds = CreateUnoServiceWithArguments("com.sun.star.security.DocumentDigitalSignatures", Array("1.2", True))
插入到文档中的对象必须由该文档创建。例如,电子表格文档的绘图对象只能在这种文档中使用。
电子表格创建绘图对象:
RectangleShape = Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")
文本文档创建段落样式:
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")
b.获得现有对象
上下文是一个名称-值对的集合,您可以使用它来通过名称获取这些对象。默认上下文可通过函数GetDefaultContext获得。
MsgBox Join(GetDefaultContext().getElementNames(), CHR$(10))
libreoffice basic提供了一些全局对象,可以快捷使用
StarDesktop
StarDesktop对象代表LibreOffice应用程序。
Dim doc As Object, docProperties()
docURL = ConvertToURL("C:\My Documents\example.odt")
Rem com.sun.star.frame.Desktop
doc = StarDesktop.LoadComponentFromURL(docURL, "_blank", 0, docProperties)
GlobalScope
To manage personal or shared library containers (Application Macros or My Macros) from within a document, use the GlobalScope specifier.
要从文档中管理个人或共享库容器(应用程序宏或我的宏),请使用GlobalScope
' 调用文档库 Standard 中的 Dialog1
oDlgDesc = DialogLibraries.Standard.Dialog1
' 调用应用程序库 Library1 中的 Dialog2
oDlgDesc = GlobalScope.DialogLibraries.Library1.Dialog2
可以从活动文档中使用以下对象。
BasicLibraries对象
DialogLibraries对象
ThisComponent对象
ThisComponent表示宏中的当前文档。它寻找活动组件,其属性可以读取和设置,并且可以调用其方法。ThisComponent提供的属性和方法取决于文档类型。
ThisDatabaseDocument对象
ThisDatabaseDocument寻找活动的文档,该文档的属性可以读取和设置,并且可以调用其方法。
ThisDatabaseDocument返回一个类型为 com.sun.star.sdb.XOfficeDatabaseDocument 的对象。
使用名字访问下级对象
XNameAccess和XNameContainer接口用于包含下级对象的对象,可以使用名字访问下级对象
XNameAccess访问各个元素;而XNameContainer用于插入、修改和删除元素。
com.sun.star.container.XNameAccess 接口
1)getByName 方法
Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")
2)getElementNames 方法
返回所有元素的名称。
Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames
For I=LBound(SheetNames) To UBound(SheetNames)
MsgBox SheetNames(I)
Next I
3)hasByName 方法
是否存在特定名称的下级对象。
Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
MsgBox " Sheet1 available"
Else
MsgBox "Sheet1 not available"
End If
com.sun.star.container.XNameContainer 接口
XNameContainer 接口用于插入、删除和修改对象中的下级对象。负责完成这些操作的函数为insertByName、removeByName、replaceByName。
该示例调用一个文本文档,该文档包含一个 StyleFamilies 对象,该对象包含段落样式 (ParagraphStyles)。
StyleFamilies = Textdoc.StyleFamilies
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")
ParagraphStyles.insertByName("NewStyle", NewStyle)
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)
ParagraphStyles.removeByName("OldStyle")
insertByName 行在 ParagraphStyles 对象中的插入NewStyle样式。
replaceByName 行将 ChangingStyle对象更改为NewStyle。
removeByName 调用将 OldStyle对象从ParagraphStyles中删除。
使用索引访问下级对象
XIndexAccess和XIndexContainer接口用于包含下级对象并可使用索引访问下级对象的对象。
XIndexAccess提供了用于访问单个对象的方法。XIndexContainer 提供了用于插入和删除对象的方法。
com.sun.star.container.XIndexAccess 接口
XIndexAccess 提供了 getByIndex 和 getCount 方法。getByIndex 通过索引获得对象。getCount 返回对象的数目。
Sheets = Spreadsheet.Sheets
For I = 0 to Sheets.getCount() - 1
Sheet = Sheets.getByIndex(I)
' Editing sheet
Next I
该示例说明了一个循环,此循环遍历获得所有工作表。在使用索引时,请注意 getCount 返回元素的数目。不过,getByIndex 中的元素是从0开始编号的。因此,循环的计数变量是从0到 getCount()-1。
com.sun.star.container.XIndexContainer 接口
XIndexContainer 接口提供了 insertByIndex 和 removeByIndex 函数。这些参数的结构与 XNameContainer 中相应函数的结构相同。
对下级对象的遍历访问
在某些情况下,对象包含一个下级对象列表,但无法通过名称或索引访问这些下级对象。此时,应使用 XEnumeration 和 XenumerationAccess 接口。它们提供了一种机制来遍历某个对象的所有下级元素,而无需进行寻址。
com.sun.star.container.XEnumeration 和com.sun.star.container.XenumerationAccess 接口
对象必须提供 XEnumerationAccess 接口,该接口仅包含 createEnumeration 方法。此方法返回一个辅助对象,而该对象又提供了包含 hasMoreElements 和 nextElement 方法的 XEnumeration 接口。可通过这些方法来访问下级对象。
以下示例将遍历文本的所有段落:
ParagraphEnumeration = Textdoc.Text.createEnumeration
While ParagraphEnumeration.hasMoreElements()
Paragraph = ParagraphEnumeration.nextElement()
Wend
该示例首先创建了一个 ParagraphEnumeration 辅助对象。然后,借助此对象通过循环逐步返回文本的各个段落。在 hasMoreElements 方法返回 False 值(表示已到达文本末尾)时,将会立即终止循环。
检查对象
可以获取UNO对象的信息。
要查明两个对象是否引用同一个UNO对象,可以使用函数EqualUnoObjects()。在Basic中,不能对对象类型的参数应用比较运算符 =,例如If Obj1 = Obj2 Then会导致运行时错误。
oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
oSimpleFileAccess2 = oSimpleFileAccess
bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess2 )
MsgBox bIdentical ' Displays True
oSimpleFileAccess3 = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess3 )
MsgBox bIdentical ' Displays False
Dbg_Properties和Dbg_Methods中使用的表示法是uno类型名称。可以忽略Sbx前缀。其他名称与一般Basic类型表示法对应。SbxEMPTY与Variant的类型相同。
DBG_properties
返回一个字符串,包括对象的所有属性
DBG_methods
返回一个字符串,包括对象的所有方法
DBG_supportedInterfaces
返回一个字符串,包括对象的所有接口
示例
Obj = createUnoService("com.sun.star.frame.Desktop")
MsgBox Obj.DBG_Properties
MsgBox Obj.DBG_methods
MsgBox Obj.DBG_supportedInterfaces
请注意,在使用DBG_properties时,返回理论上可以支持的所有属性。但不保证对象可以使用这些属性。因此,在使用属性之前,必须使用IsEmpty函数检查该属性是否确实可用。
supportsService方法
可以使用supportsService方法来确定对象是否支持特定服务。
例如,TextElement对象是否支持com.sun.star.text.Paragraph服务。
Ok = TextElement.supportsService("com.sun.star.text.Paragraph")
getsupportedservicenames方法
获取所有支持的服务
msgbox join(TextElement.getsupportedservicenames, chr(10))文章来源:https://www.toymoban.com/news/detail-434505.html
工具 - 开发工具,能查看对象的服务,接口,方法,属性。
全局方法
CreateUnoDialog函数
创建一个基本Uno对象,该对象表示宏运行时的对话框。
CreateUnoListener函数
创建监听器实例。
CreateUnoValue函数
返回一个对象,该对象表示一个涉及Uno类型系统的精确类型值。
文章来源地址https://www.toymoban.com/news/detail-434505.html
到了这里,关于libreoffice api的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!