Xray tool description

Provided by fr.OpenOffice.org Project

Table of Contents

1 Introduction	3

1.1 Document changes	3

1.2 XRay tool evolution since version 5.1	3

2 Installation	4

3 Tool usage	4

3.1 Start	4

3.1.1 Manual load of XrayTool library	5

3.1.2 Automatic load of XrayTool library	6

3.2 Display panels	7

3.2.1 Displaying Properties	8

3.2.2 Displaying Methods	10

3.2.3 Extended display	11

3.2.4 Displaying Services	13

3.2.5 Displaying Interfaces	14

3.3 Cascading analysis	15

3.4 Single values and arrays	17

3.5 API Documentation	19

3.5.1 Xray configuration for API documentation use	19

3.5.2 Configuring the SDK address	20

3.5.3 Configuring the browser call	20

3.5.4 Displaying documentation about an object	20

4 Using Xray with other programming languages	21

4.1 From a Python script within OpenOffice.org	21

4.2 From a BeanShell script within OpenOffice.org	21

4.3 From a Javascript script within OpenOffice.org	22

4.4 Through COM, under MS‑Windows	23

4.4.1 From VBA	23

4.4.2 From Delphi	24

5 Credits	26

6 Licences	27

6.1 Documentation	27

6.2 Macro libraries	27

Introduction

The most annoying aspect for a programmer familiar with VBA is that OpenOffice.org’s IDE does not have auto-completion (i.e. automatically propose methods or properties names while typing). This is due to OpenOffice.org’s different design concept. It does not have predefined objects, all necessary Uno objects are instantiated when needed. It is not possible to know statically (at compile time) the properties and methods available in a Uno object variable. You can only find them at runtime, and this is what does Xray macro.

Xray is a tool for the programmer of Basic macros using OpenOffice API. Its purpose is to display the properties, methods, services, interfaces which are provided by an object variable.

Xray can display in a web browser the official API documentation about a property, method, service, interface of an object.

Xray can recursively analyse the current object, if a property contains an API object or if a method returns an API object.

Xray can run on versions 1.1.x and 2.x of OpenOffice.org. This is the reason why it is available in an sxw document instead of odt.

Warning

Xray can help but it is not an alternative to reading the existing documentation (Sun Programmer’s Guide, and in the SDK the Developer’s Guide and the IDL description).

Document changes

This document describes version 5.2 of Xray tool and shows installation over a version 2.0 of OpenOffice.org.

A new chapter is added describing how to call Xray from other programming languages.

Snapshots (Gif format, 300DPI) were done with Screenshot Captor.

XRay tool evolution since version 5.1

Many details improve presentation and ease of use.

Installation is simplified.

Xray can now display :

a value of type Hyper, identified as INT64,

a value of type Char,

a multi-dimension Basic array,

interface attributes indication and documentation

the name and value of each PropertyValue array element,

<empty> or <null> indication if the property does not have a value,

for a property containing an enumeration value, the corresponding qualified name.

Cascading analysis may be triggered by a double-click on the property or method line.

Key Ctrl-F1 may be used to access the API documentation on an object.

Installation

Click on this button to run the installation macro. After confirmation, it will suppress any existing installation of Xray and instal this version.

It is advised to read carefully the description of Xray in the next chapters.

If you want to uninstall Xray libraries from your OpenOffice installation, click here :

Tool usage

Xray does not change anything to the IDE. It is a sub-program that you have to run from your code.

Start

In the macro you are debugging you have to (temporarily) insert a call to Xray macro. Most of the snapshots displayed at chapter 3.2 were done on a Writer document by running this simple macro :

Sub Main

Xray ThisComponent

End Sub

In this other macro example the object MySheet from a Calc document will be displayed :

Document = ThisComponent

AllSheets = Document.getSheets()

MySheet = AllSheets.getByIndex(0)

Xray MySheet

Remark

If the line of code containing Xray raises an exception this is because the library is not loaded. Read sections 3.1.1 and 3.1.2.

Manual load of XrayTool library

In order that the main macro Xray be recognized it is mandatory that XrayTool library be loaded. This library is in « My Macros » (or in « soffice » with OpenOffice.org version 1). If the panel is like here, library XrayTool is not loaded.

To load XrayTool library, just double-click on its name. The branch of its modules unfolds :

Automatic load of XrayTool library

If you want to avoid manual loading at each OpenOffice startup, install this macro in My Macros.Standard (or in soffice.Standard with OpenOffice.org version 1) :

Sub LoadingLibraries

BasicLibraries.LoadLibrary("XrayTool")

End Sub

Assign it to « Start Application » event. Make sure that the« Save in » box at bottom displays the correct indication.

You may use this macro to load other application libraries.

Display panels

When your macro runs, a panel will display information about your object. You may display :

its properties (initial display),

its methods,

its services,

its interfaces.

See full description in the following pages.

Displaying Properties

The property names are on the first column.

The type of each property is shown on the second column. When the type is written after [] the property contains an array (an API sequence) where each element is of the shown type. The indication struct means that the property is a Uno structure. The indication object is used for the other API objects.

The third column displays the property contents when this is possible. Special case :

indication <empty> or <null> means that the property has no value in this context ; an empty array is shown as <empty> ;

a string content is displayed between double-quotes, except if direct display is not possible (e.g. too long text) where indication <...> is shown instead, which means that Xray can be queried to see the complete string ;

no value is shown for a type object, struct, or an array ; but you may request an Xray on that element as further described.

The fourth column provides additional information :

may be void ;

read-only ;

write-only ;

pseudo-prop : the property Xxxx is in fact calling methods getXxxx and setXxxx, for reading and writing respectively.

By default properties are displayed in the order provided by introspection. You may display in alphabetical order by clicking the checkbox “ A ... Z ”.

Displaying Methods

The method names are on the first column. The second column lists the method parameters, using Basic syntax. The name of each argument is provided by the object introspection. The type of each argument is displayed as in the Properties panel. A method like hasLocation or initNew has no arguments : ( ).

If the method returns a value its type is shown in the third column, after AS. Otherwise nothing appears in this column.

By default methods are displayed in the order provided by introspection. You may display in alphabetical order by clicking the checkbox “ A ... Z ”.

Extended display

The checkbox “ Details ” gives an extended display of the properties and methods.

Each element designated as struct or object in the classical display is now replaced by its exact API reference.

The column at far right of properties shows other information obtained through object introspection, and when needed the API name of an enumeration value.

For each method the name of the API interface wich supports it is added at far right.

There is much information and it is more difficult to read. It may be useful to widen the panel with the buttons at right. You may push F2 key to higlight the current line and use the horizontal scrollbar.

The configuration panel (click button “ Configuration ”) allows you to set the default display : normal or detailed, natural order or alphabetical order, enlarged main panel.

Displaying Services

Each list is displayed in alphabetical order.

Available services are those that may be invoked with createInstance() method.

Displaying Interfaces

Interfaces names are listed in alphabetical order.

Cascading analysis

In the “ Properties ” panel you may request analysis of one of the properties by pointing at the line (with a mouse click) and then clicking on the button “ Xray on the property/method ”

In the “ Methods ” panel you may as well request analysis of the value returned by a method, so long as it does not use any argument. Example :

A quicker method is to double-click on the line to be analysed.

This way you may analyse various objets included in the original object, then objects within objects, and so on.

If the resulting type is a simple one its current value will be displayed (see further down).

If you want to analyse a method with arguments you have to close Xray, return in the IDE, and modify the call of Xray by using appropriate arguments, example :

xray MySheet.getCellByPosition(3,5)

In order to go back on an already analyzed object, click on the drop-down list under “ Displayed object ” and choose one of the entries.

The button at right of the drop-down list takes you back to the original object.

Single values and arrays

Xray displays any data, it is not limited to objects from OpenOffice.org API.

When the element under study is a single value its type and value are displayed.

For a type Integer or Long the value is displayed as decimal and hexadecimal.

The text of a String is displayed in full without formatting. Use the scrollbars if needed.

When the element is an array the analysis is limited to its first dimension. The upper and lower index values ot the array are displayed. The value for each array element is displayed, one line for each. If the element is a String its content is displayed only if it one single line.

An API « sequence » is shown in Basic as an array. Some API sequences are made of structures or objects. If the element of a sequence is an object with property (or pseudo-property) Name and possibly Value their contents is displayed (see next page).

Xray can display any array, and indicates if there are sub-arrays. This example was created using the Basic function Array :

Sub Main

Dim v

v = Array(Array(8,5,45), true, Array("a", "b", "z", "hh"), "Hello !", pi)

xray v

End Sub

API Documentation

Xray may display in your browser the API documentation about :

a property,

a method,

a service,

an interface.

Xray configuration for API documentation use

You should have installed locally or on your local network at least the API part of the SDK. You just have to decompress the archive, which creates a tree of folders with files.

Note for non-english users : SDK documentation is available only in english.

The SDK is available at the website http://api.openoffice.org/ if you follow the link download the SDK which, in principle, directs to the most recent version.Several versions of the SDK are available on the FTP servers : 1.0.2, 1.1.0, 2.0.4. Version 2.0.4 of the SDK weighs approximately 38 Mbytes.

Before your first use, click on the “ Configuration ” button on Xray panel. You get this :

Configuring the SDK address

Search for the directory which is the root of the SDK. For example if you have installed the SDK 2.0.4 on C: disk with Windows operating system this directory is :

C:\OpenOffice.org_2.0_SDK

Configuring the browser call

Indicate the path to a browser. You may store the addresses of 3 different browsers. If the browser call does not work, try again after checking the option box « Click here ... ».

Displaying documentation about an object

Point at the line of the property, method, service or interface you want to see the documentation. Then click the button “ SDK documentation ”, or push key Ctrl-F1.

When requesting documentation display it may happen that several pages deal about the same subject (such as for an object supporting both services XpropertySet and XMultiPropertySet). In this case Xray displays in your browser the list of pages found, with links. It may also happen that there is no page available. Either it is an internal detail purposedly undocumented, or the documentation is lacking for this point.

Using Xray with other programming languages

From OpenOffice.org version 2.0 the API offers a new method to call a script. Any programming language able to use the API may call a script written in one of the script languages supported by OpenOffice.org.

So, using this method it is possible to call Xray because it is no more than a Basic script.

The reader is expected to know how to program the API with the languages used here. Pay attention to instructions spanning over more than one line.

From a Python script within OpenOffice.org

Here is the contents of a file which must be stored in the folder user/Scripts/python/ (or in a folder Scripts/python/ within a document). Remember that lines must end with Unix-style Line-Feed.

import uno

from com.sun.star.uno import RuntimeException as _rtex

def xray(myObject):

try:

sm = uno.getComponentContext().ServiceManager

mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", uno.getComponentContext())

scriptPro = mspf.createScriptProvider("")

xScript = scriptPro.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application")

xScript.invoke((myObject,), (), ())

return

except:

raise _rtex("\nBasic library Xray is not installed", uno.getComponentContext())

# ___________ example of use _______________

def demoXray():

""" example : using xray in a Writer document """

xTextDoc = XSCRIPTCONTEXT.getDocument()

xText = xTextDoc.Text

xray(xText)

xray("Demo is finished")

g_exportedScripts = demoXray,

From a BeanShell script within OpenOffice.org

Here is the contents of a module in a BeanShell library of a document (or in My Macros).

import com.sun.star.uno.UnoRuntime;

import com.sun.star.uno.XComponentContext;

import com.sun.star.frame.XDesktop;

import com.sun.star.frame.XModel;

// ____________ declaration of BeanShell xray routine _______________

import com.sun.star.script.provider.XScriptProviderFactory;

import com.sun.star.script.provider.XScriptProvider;

void xray(ObjX) {

xCompCont = XSCRIPTCONTEXT.getComponentContext();

sm = xCompCont.getServiceManager();

mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", xCompCont);

xspf = UnoRuntime.queryInterface(XScriptProviderFactory.class, mspf);

scriptPro = xspf.createScriptProvider("");

xsp = UnoRuntime.queryInterface(XScriptProvider.class, scriptPro);

Xscript = xsp.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application");

args = new Object [1];

short [ ] [ ] a;

Object [ ][ ] b;

args[0] = ObjX;

Xscript.invoke(args, a, b);

}

// ____________ end of BeanShell xray routine _____________________

import com.sun.star.text.XTextDocument;

import com.sun.star.text.XText;

oDoc = XSCRIPTCONTEXT.getDocument();

xTextDoc = (XTextDocument) UnoRuntime.queryInterface(XTextDocument.class,oDoc);

xText = xTextDoc.getText();

xray(xText);

xray("Demo is finished");

// BeanShell OpenOffice.org scripts should always return 0

return 0;

From a Javascript script within OpenOffice.org

Here is the contents of a module in a Javascript library of a document (or in My Macros).

importClass(Packages.com.sun.star.uno.UnoRuntime);

importClass(Packages.com.sun.star.text.XTextDocument);

importClass(Packages.com.sun.star.text.XText);

importClass(Packages.com.sun.star.lang.XServiceInfo);

// ____________ declaration of JavaScript xray routine _______________

importClass (Packages.com.sun.star.script.provider.XScriptProviderFactory);

importClass (Packages.com.sun.star.script.provider.XScriptProvider);

function xray(ObjX) {

var xCompCont = XSCRIPTCONTEXT.getComponentContext();

var sm = xCompCont.getServiceManager();

var mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", xCompCont);

var xspf = UnoRuntime.queryInterface(XScriptProviderFactory, mspf);

var scriptPro = xspf.createScriptProvider("");

var xsp = UnoRuntime.queryInterface(XScriptProvider, scriptPro);

var Xscript = xsp.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application");

var args = new Array(1);

args[0] = ObjX;

var a = new Array( new Array() );

var b = new Array( new Array() );

Xscript.invoke(args, a, b);

};

// ____________ end of JavaScript xray routine _____________________

oDoc = XSCRIPTCONTEXT.getDocument();

xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc);

xText = xTextDoc.getText();

xray(xText);

xray("Demo is finished");

Through COM, under MS‑Windows

Most of the modern languages available under MS‑Windows can handle OpenOffice.org API by using COM. So that you may call the Xray Basic script in a way similar to previous examples.

From VBA

This VBA code creates a new Writer document and calls Xray with the document object as argument. It was tested from Word 2002.

Option Explicit

Sub Main()

Dim sm As Object, DeskTop As Object, oDoc As Object

Dim args()

Set sm = CreateObject("com.sun.star.ServiceManager")

Set DeskTop = sm.createInstance("com.sun.star.frame.Desktop")

Set oDoc = DeskTop.loadComponentFromURL("private:factory/swriter", "_blank", 0, args)

xray oDoc

oDoc.Close True

End Sub

Sub xray(myObject As Object)

Dim sm As Object, mspf As Object, scriptPro As Object, xScript As Object

Dim noargs1() As Variant, noargs2() As Variant, arg1(0) As Variant

Set sm = CreateObject("com.sun.star.ServiceManager")

Set mspf = sm.createInstance("com.sun.star.script.provider.MasterScriptProviderFactory")

Set scriptPro = mspf.createScriptProvider("")

Set xScript = scriptPro.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application")

Set arg1(0) = myObject

xScript.Invoke arg1, noargs1, noargs2

End Sub

From Delphi

This Delphi code creates a new Writer document and calls Xray with the document object as argument. It was tested from Delphi 7.

Uses ComObj;

procedure xray(myObject: Variant);

var

ooo, mspf, scriptPro, xScript, arg, noargs1, noargs2: Variant;

begin

ooo:= CreateOleObject('com.sun.star.ServiceManager');

mspf:= ooo.createInstance('com.sun.star.script.provider.MasterScriptProviderFactory');

scriptPro:= mspf.createScriptProvider('');

xScript:= scriptPro.getScript('vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application');

arg:= VarArrayCreate([0,0], varVariant);

arg[0]:= myObject;

noargs1:= VarArrayCreate([0, -1], varVariant);

noargs2:= VarArrayCreate([0, -1], varVariant);

xScript.invoke( arg, noargs1, noargs2);

end;

procedure Main;

var

ooo, Desktop, oDoc, args: Variant;

begin

ooo:= CreateOleObject('com.sun.star.ServiceManager');

Desktop:= ooo.createInstance('com.sun.star.frame.Desktop');

args:= VarArrayCreate([0, -1], varVariant);

oDoc:= Desktop.loadComponentFromURL('private:factory/swriter', '_blank', 0, args);

xray(oDoc);

oDoc.close(True);

end;

An alternative solution, much simpler, is to use the ressources of Delphi_OOo tool available at the site OooMacros. Its unit OooXray is a Delphi-native equivalent of Xray macro, done with help of COM and the display facilities of Delphi 7. Unit OooTools simplifies the API calls. Another plus is that it runs on 1.1.x and 2.0.x versions of OpenOffice.org.

The same example boils down to this :

Uses ComObj, OOoTools, OooXray;

procedure Main;

Var

oDoc: Variant;

Begin

ConnectOpenOffice;

oDoc:= StarDesktop.LoadComponentFromURL('private:factory/swriter', '_blank', 0, dummyArray);

Xray(oDoc);

oDoc.close(True);

End;

Credits

Author : Bernard Marcelly

Thanks to : Laurent Godard for his idea of dynamic module and for his useful remarks.

Integrated by :

Last modified : November, 24, 2006

Contacts : OpenOffice.org Documentation project http://fr.openoffice.org

Translation :

This document exists in version 5.1 or more recent :

Language	Translator	Web Site
English	Bernard Marcelly	http://ooomacros.org/
Portuguese (Brazil)	Noelson Alves Duarte	http://www.openoffice.org.br/
Czech	Vladimír Graf	http://members.chello.cz/ladinek/ooo/tools/index.html
French	Bernard Marcelly	http://fr.openoffice.org/Documentation/How-to/indexht-programmation.html

Licences

Documentation

Appendix

Public Documentation License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at http://www.openoffice.org/licenses/PDL.html.

The Original Documentation is : Description de l’outil Xray

The Initial Writer of the Original Documentation is Bernard Marcelly

Copyright (C) 2003-2006. All Rights Reserved. (Initial Writer contact(s): marcelly@club-internet.fr )

Contributor(s): ______________________________________.

Portions created by ______ are Copyright (C)_________[Insert year(s)].

All Rights Reserved. (Contributor contact(s):________________[Insert hyperlink/alias]).

NOTE: The text of this Appendix may differ slightly from the text of the notices in the files of the Original Documentation. You should use the text of this Appendix rather than the text found in the Original Documentation for Your Modifications.

Macro libraries

General information on LGPL is available on this Web site.

The library Xray included in this document constitutes a tool which displays information on an OpenOffice API object. Copyright (C) 2003-2006 Bernard Marcelly

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

fr.OpenOffice.org

- Back to Table of Contents	27/27

API Basic Xray

Bernard M.

2003-11-01T23:04:18