Xray tool description

Provided By
the OpenOffice.org Documentation Project

Table of Contents

1 Introduction	3

1.1 Document changes	3

1.2 XRay tool evolution since version 3.1	3

2 Installation	4

3 Tool usage	5

3.1 Start	5

3.2 Display panels	5

3.3 Cascading analysis	11

3.4 Single values and arrays	12

3.5 API Documentation	15

3.6 Closing an OpenOffice document	17

4 Credits	18

5 Licences	19

5.1 Documentation	19

5.2 Macro libraries	19

Introduction

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.

When a property or method is itself an API object, this in turn can be analysed by Xray.

Document changes

This document describes version 4.0 of Xray tool.

XRay tool evolution since version 3.1

Xray no more uses Dbg_ properties specific to OOoBasic but uses directly Introspection and Reflection services, which provide much more information (too much, it was necessary to select).

Column order was changed, informations were added, the recursive call was simplified, and many more details updated.
Read again this document to have an overview of the modifications.

Note : XrayDin library was not modified, you may keep version 3.1.

Installation

Open the Writer document you are reading ( Xray tool description).

Use the Macro Organizer to append a new library (refer to on-line help).

Choose Application / Document : soffice.

Click on “ Append... ” button and choose this document ( Xray tool description).

Check Xray and XrayDin, do not check Standard,

If you have a previous version check “ Replace existing libraries ”

Click OK.

Tool usage

Start

The main macro Xray must be known to OpenOffice. The first time after start of OpenOffice you must use the Macro Dialog box to develop the soffice branch and double-click on the Xray library.

The purpose is to load Xray library. Now you can open in the IDE the macro you are working on, and make it call Xray.

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

Document = ThisComponent

Sheets = Document.Sheets()

MySheet = Sheets.getByIndex(0)

Xray.Xray MySheet

Note : if the line of code containing XRay is ignored when running the macro this is because you have forgotten to load the library. Redo what is explained with the images above.

Automatic load of Xray library

If you want to avoid manual loading at each OpenOffice startup, install this macro in soffice.Standard and trigger it at OpenOffice startup :

Sub LoadingLibraries

BasicLibraries.LoadLibrary("Xray")

End Sub

The same macro can also load other libraries from soffice.

Display panels

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

By a simple click you may display at your choice :

its properties,

its methods,

its services,

its interfaces.

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 :

for a string, indication <null> means that the string has zero length ;

a non-null string is displayed as <...> ;

indication <empty> means that the contents is not available in this context ;

no value is shown for a type string, 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 button « Properties A-Z ».

Displaying Methods

Here again, you may display methods in alphabetical order by clicking the button « Methods A-Z ».

You may widen or shrink the panel width to have a better view of long lines.

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.

Displaying Services

Each list is displayed in alphabetical order.

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

Displaying Interfaces

The names of the interfaces 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 :

This way you may analyse various objets included in the original object, as well as objets within objects within objects, etc.

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.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.

Single values and arrays

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 ; if the upper index is less than the lower index, this means that the array is empty. The value for each array element is displayed, one line for each. Of course in the case of an array of String the result may be difficult to read.

Some API arrays are made of “ Property ” or “ PropertyValue ” structures. In this case the name of each property is shown.

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

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.

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

The SDK is available at the website http://api.openoffice.org/ and more precisely at the page http://www.openoffice.org/dev_docs/source/sdk/ .
The version OpenOffice.org SDK 1.1 available at the date of this document weighs 40.5 Moctets for Windows, 27.9 Moctets for Linux and 29.2 Moctets for Solaris.

Xray uses the documentation directories and displays an error message when it does not find them.

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 API documentation tree. For example if you have installed the SDK on C: disk with Windows operating system this directory is :

C:\OpenOffice.org1.1_SDK

Configuring the browser call

If your web browser displays an html file when you double-click on it you should be able to use the option “ Use your default Browser ”. However this does not always work due to the configuration of the Operating System.

If the call to the default browser does not work, or if you elect to choose another browser, indicate the address of its executable file using one of the file search buttons. You may set up to 3 browsers. Next, select the browser to use with a click on the button at left.

If the call to the brower fails you may check “ Use method n.2 ”. This may work in your case.

Displaying documentation about an object

Point at the line where the property, method, service or interface is, for which you want to see the documentation.

Then click the button “ SDK documentation ”.

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 no page fits, as for example for property Dbg_SupportedInterfaces. This is due to current lacks in the SDK.

Closing an OpenOffice document

On OpenOffice versions prior to 1.1.1 it is not possible to close any OpenOffice document while a macro is running. This is the case when Xray panel is displayed. Remember this if you have several OpenOffice documents open !

This limitation is suppressed with version 1.1.1.

Credits

Author : Bernard Marcelly

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

Integrated by :

Last modified : October, 26, 2004

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

Translation :

English : Bernard Marcelly - October, 26, 2004

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-2004. 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 libraries Xray and XrayDin included in this document constitute a tool which displays information on an OpenOffice API object. Copyright (C) 2003-2004 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

OpenOffice.org Documentation Project How-To

http://fr.openoffice.org	19

Xray Tool

API Basic Xray

Bernard M.

2003-11-01T23:04:18