Difference between revisions of "Object Inspector"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Calling from a Basic Macro)
(update repo link to post-graduation location)
(42 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== '''The new Object Inspector''' ==
+
The Object Inspector is an OpenOffice.org extension created to help the developer to inspect arbitrary UNO-Objects.  
The Object Inspector is an OpenOffice.org extension that is to help the developer to inspect arbitrary Uno-Objects. As Uno provides a service-oriented API with abstract service descriptions exporting defined interfaces the capabilities of a Uno Object does not open up to the developer at design time mainly due to several „deficiencies“. The Object Inspector is still under development.
+
UNO provides a service-oriented API with abstract service descriptions exporting defined interfaces. The capabilities of a UNO Object do not open up to the developer at design time, mainly due to several "deficiencies".  
 +
Please note that the Object Inspector is still under development.
  
== '''The Problem''' ==
+
== The Problem ==
  
Generic interfaces like „XPropertySet“ or „XIndexAcess“ do not define their exact return value. Service descriptions that export these interfaces mostly do not contain such information either.
+
Generic interfaces like [http://api.openoffice.org/docs/common/ref/com/sun/star/beans/XPropertySet.html XPropertySet] or [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XIndexAccess.html XIndexAccess] do not define their exact return value. Service descriptions that export these interfaces mostly do not contain such information either.
  
It is not always clear at design time which services a Uno-object actually supports.
+
It is not always clear at design time which services a UNO object actually supports.
  
Documentation bugs. As service descriptions do not always show up all actually exported interfaces or properties there may be a certain difference between the theoretical and the practical capabilities of a Uno object.
+
Documentation bugs: as service descriptions do not always show up all actually exported interfaces or properties, there may be a certain difference between the theoretical and the practical capabilities of a UNO object.
  
== '''The Solution''' ==
+
== The Solution ==
The conclusion is that it has be be inspected during runtime what respective capabilities a Uno-Object actually has. The new Object Inspector is an OpenOffice extension that has been evolved from the ancient instance inspector that is part of the OpenOffice.org SDK. It displays the total capabilities of  a „living Uno-object“ such as all supported services, exported interfaces, and their respective methods and properties in a treeview window.
+
  
 +
The conclusion is that a runtime inspection is necessary to determine what respective capabilities a UNO object actually has.
 +
The Object Inspector is an OpenOffice.org extension that has been evolved from the ancient instance inspector that is part of the OpenOffice.org SDK. It displays the total capabilities of a "living UNO-object" such as all supported services, exported interfaces, and their respective methods and properties in a TreeView window.
  
== '''Usage''' ==
+
== Usage ==
The object inspector may be installed using the package manager (menu „Tools/Options“) by adding the package from [http://api.openoffice.org/Projects/ObjectInspector/Inspector.oxt] . Together with the new package a new toolbar is added from which the object inspector may be started. The object inspector consists of a menu-controlled resizable dialog with a tab control. Each pane of the tab control contains a split pane whose upper component is occupied by a treeview control embedded in a tab pane (see Illustration 1: Object Inspector). The treeview control is to inspected an arbitrary Uno-object. The bottom component of the split control contains a text control used to display the SourceCode needed to create the Uno-Objects represented by nodes of the treeview control. The initial Uno-Object is the document of the currently active frame. The Uno-object of this document is represented by the root node of the treelist control. Expanding this node will create subnodes referencing all subordinate objects, properties, methods and other values of the root object. All this information is presented in various facettes:
+
The Object Inspector may be installed using the package manager (menu "Tools/Options") by adding the package from [http://api.openoffice.org/Projects/ObjectInspector/Inspector.oxt Inspector.oxt] .  
Methods of Uno-objects  are presented as subnodes under a „Method node“. All methods are listed under this node, no matter what their parental interfaces are. Expanding nodes that denote a method of a Uno-object will invoke the method and if necessary a dialog with an input mask for the method parameters will appear. Note that currently only methods with either no parameters or primitive parameters may be invoked.
+
  
Properties of Uno-objects are presented as subnodes under a „Properties“ node.  
+
Together with the new package a new toolbar is added from which the object inspector may be started.
 +
The initial UNO object is the document of the active frame. The UNO object of this document is represented by the root node of the treelist control. Expanding this node will create subnodes referencing all subordinate objects, properties, methods and other values of the root object. All this information is presented in various facets:
  
„Interface“ nodes offer a view to all methods by arranging them under their respective interface.
+
Methods of UNO objects are presented as subnodes below a "Method" node. All methods are listed below this node, no matter what their parental interfaces are.
  
„Service“ nodes offer a view to all supported services of a Uno-object and their respectively exported interfaces and properties.
+
Properties of UNO objects are presented as subnodes below a "Properties" node.  
"Container" nodes may be expanded to retrieve information about Elements. This node is only applicable when the Uno-objects also depicts a container that exports interfaces like "com.sun.star.container.XIndexAccess"
+
  
Expanding any arbitrary subnode will inspect the Uno-object that is represented by the node in the same way as described above. Subnodes that describe methods will invoke this method at the Uno-object. If parameters have to be supplied these have to be delivered by the user in a special dialog that opens up when the node is expanded.
+
"Interface" nodes offer a view to all methods by arranging them under their respective interface.
  
The menubar consists of several menus:
+
"Service" nodes offer a view to all supported services of a UNO object and their respectively exported interfaces and properties.
  
* A „File“ menu to remove tab panes and to quit the object inspector.
+
Expanding any arbitrary subnode will inspect the UNO object that is represented by the node in the same way as described above.
  
* An „Inspect“ menu in order to determine the Uno-objects to be inspected. Clicking on such a menu item will open a new tab pane for a certain Uno-object. Offered Uno-objects are derived from the following items in this menu:
+
=== Screenshots ===
**Empty documents of all given application. text document, empty spreadsheet, empty presentation, empty drawing. Selecting one of these menu entries opens a new tabpane and loads an empty hidden application document.
+
**Menu entries for each available so-called T-Docs („transient documents“). T-Docs describe the currently opened documents. The object inspector is started with the currently active document as the to-be inspected Uno-object.
+
**The currently selected object. This menu entry references the Uno-object of the currently selected node.  This option is explicitly helpful in vast object hierarchies where the user can easily loose track.
+
**The global service manager, that can be used to instantiate a great variety of services.
+
  
* A„View“ menu: Developers may prefer different views on the respective Uno-Objects depending on the momentary situation and the used programming language. For example StarBasic developers are naturally not very interested what interfaces a Uno object supports as they use the methods directly. On the other hand in StarBasic many „getter“ and  „setter“ methods are implemented as properties and should optionally turn up underneath the „Properties“ node. This menu and its underlying functionality has not yet been implementd nor has it been specified.
+
[[Image:ObjectInspector.png|600px]]
  
* An „Options“menu to be used to set all kind of options. In its current state it is possible to choose the to-be-generated sourcecode language and set the path to a local SDK-installation with contained idl-files (interface and service description files).
+
=== Calling from a Basic Macro ===
  
* A „Help“ menu to aquire help about Uno-objects behind selected nodes. Also via shortcut F1 the browser will open a help document about the used interface or service of a Uno-object , that is referenced by a selected node.
 
A context menu can be applied on selected nodes and offers some functions to
 
1) inspect the object behind the selected node in a new tabpane
 
2) add the source code needed to retrieve the Uno-object behind the node to the bottom component of the split pane.
 
3) get Help to the referred API functionality like via the "Help" menu
 
 
== '''Filtering''' ==
 
 
As can be see in Illustration 1: Object Inspector a filter can assist a determined search for subnodes. It also helps to keep the overview especially in large hierarchies.
 
 
[[Image:ObjectInspector.PNG]]
 
 
Illustration 1 Object Inspector
 
 
=='''Calling from a Basic Macro''' ==
 
 
The Object Inspector may be instantiated within a Basic script as can be seen in the following examplary script, where the current document is inspected:
 
The Object Inspector may be instantiated within a Basic script as can be seen in the following examplary script, where the current document is inspected:
  
<code>[cpp]
+
<source lang="oobas">
 
Sub Main
 
Sub Main
 
oInspector = createUnoService("org.openoffice.InstanceInspector")
 
oInspector = createUnoService("org.openoffice.InstanceInspector")
 
oInspector.inspect(ThisComponent, "My Document")
 
oInspector.inspect(ThisComponent, "My Document")
 
End Sub
 
End Sub
</code>
+
</source>
  
== '''Source-code generation''' ==
+
=== Sourcecode generation ===
  
 +
The Object Inspector is also able to generate Sourcecode snippets that show how to:
  
The Object inspector now is also capable to generate Source Code that is needed to create the Object or primitve value returned of the current selected node.  Starting from the root object, denoted as „_oEntryObject“, all needed variables are declared and defined automatically as well as import statements (for C++ include statements) and the invoked methods or called properties. The sourcecode is inserted into the bottom component of the split pane. Supported sourcecode languages are C++, Java and OpenOffice.org Basic as selectabe in the menu "Options". Several rules must be observed for the sourcecode generation:
+
* query an interface (if necessary in the selected language)
The sourcecode generation is invoked from a context menu that may be raise above a selected node. New sourcecode is always appended to already existing sourcecode considering that variables may already have been declared and defined beforehand.
+
* invoke a method
The sourcecode generator internally keeps a list of create Uno-Objects and will not create duplicate variables when a reference to a Uno-Object has already been created beforehand. So it may be that no sourcecode is appended because the uno-object behind a selected noded is already defined within the generated sourcecode in an earlier context, which admittedly can be confusing.
+
* retrieve a property value
  
== '''IDL help''' ==
+
Currently there are code generators for Java, C++, Python and Basic. The resulting code is not perfect, but ''should'' compile well. See [[ObjectInspectorComparison|Object Inspector Comparison]].
The user may retrieve help about selected nodes from the idl files of the respective interface and service descriptions. As a new feature the Object inspector also offers to provide the path to a local SDK installation when no internet connection is available. To do so follow the menu "Options/SDK-Path" and select the path to the local SDK-installation in the raised folder picker. The path to the SDK-installation is stored persistently.
+
 
 +
=== IDL help ===
 +
<font color="red">Currently broken</font>
 +
 
 +
The user may retrieve help about selected nodes from the IDL files of the respective interface and service descriptions.
 +
 
 +
== Development ==
 +
 
 +
=== Source code ===
 +
 
 +
You will find the Object Inspector source code within the OpenOffice.org Subversion Repository:
 +
 
 +
  svn co svn://svn.apache.org/repos/asf/openoffice/trunk/main/odk/examples/java/Inspector/
 +
 
 +
The checked in source contains a complete NetBeans project, so that one can immediately start hacking around. Feel free to commit bugfixes and changes or contact cli(at)openoffice.org if you like to take over the project.
 +
 
 +
=== Known issues ===
  
== '''Known Issues''' ==
 
 
The Object inspector is still under development and the following list points to some known unresolved defects.
 
The Object inspector is still under development and the following list points to some known unresolved defects.
*The sourcecode generator ignores nodes that do not contain instantiated objects. This is relevant for method nodes: If for some reason an invoked method node delivers a "null" object the source code generator will completey ignore this node.
 
*Sourcecode generation below "PropertySetInfo" nodes fail.
 
*As the depiction of node images of the treeview control caused problem this feature has been deactivated temporarily.
 
*Setting the filter sometimes lead to ArrayIndexOutOfBoundsException.
 
*Parameter descriptions of methods node are in the notation of the currently set programming language and not in "Idl" which is not consistant. What makes it worse is that it's not changed when the programming language is changed.
 
*When the Idl help document is opened an anchor that represents the method or property name of the selected node should be set (see Sourcecode in class UnoNode; Method openIdlDescription).
 
*invoking "getTypes()" creates the following sourcecode: "Type aTypes = xTypeProvider.getTypes();" Return variable should be sequence.
 
*The taborder in the „Method-Parameters-Dialog“ does not yet define a cycle. The first focus is not set and when the last control gains the focus the next focus component is not defined.
 
*SourceCode generation below container nodes is not yet implemented and will currently raise an exception.
 
  
== '''Future Enhancements''' ==
+
* Filtering is slow and uncomfortable as nodes are collapsing and need to be expanded manually
 +
* IDL help is not working (including context sensitive help)
 +
* C++ code not properly generated (it was better with previous version). [[Programming_OOoWriter#Going_further_with_Inspector|Read more here]] particularly [[Programming_OOoWriter#Java_Inspector_2| Java Inspector 2]] section.
 +
 
 +
=== Future Enhancements ===
 +
 
 
* Invocation of methods with complex parameters should be implemented. It should be implemented in several steps
 
* Invocation of methods with complex parameters should be implemented. It should be implemented in several steps
**Implementation of Array parameters with primitive elements. It would be suitable to provide a textfield for this where the elements have to be added comma-separated.
+
** Implementation of Array parameters with primitive elements.
**Implementation of structs.For each member an own textfield may be provided.
+
** Implementation of structs.
** Implementation of an input mask to refere to Uno-Objects as method parameters. The reference of the Uno-Objects could be retrieved from the treeviewcontrol and the treepath of a node that represents this Uno-object. This reference must then be added to the method parameter's dialog's respective textfield. It must be considered that this dialog may no longer be modal then and that probably this object also has to be retrieved by invocation of methods (probably with complex parameters).
+
** Implementation of an input mask to refer to UNO-Objects as method parameters.
 
**Consider multidimensional arrays as method parameters and for return values.
 
**Consider multidimensional arrays as method parameters and for return values.
*For some method parameters it would be helpful to provide a listbox with all possible values. For example to invoke the method "createInstance(String _sServiceName) a listbox with the return value of "getAvailableServiceNames()" could be offered. Both methods are always provided at the same Uno-Object. Other similar usecases are existent.
+
 
*At some time the whole user interface of the object inspector should be ported to Uno. The user interface has been implemented with Java.Swing, because of some missing functionality in Uno. Yet meanwhile treeview controls may be implemented by Uno, too. Tab controls and menus in Uno dialogs are unfortunately not yet available.
+
* An additional UNO GUI should be created, so that the extension integrates well in OOo and NetBeans. The existing model can be easily adapted to another GUI, hopefully.
*Interfaces that are exported by an Uno-Object although not being exported by any of the suported services should be distinguished from the other interfaces. There should be displayed some kind of alert as their usage is potentially hazardous, because it is merely based on an implementation detail.
+
 
*Implementation of different views on the inspected Uno-objects is missing and should be specified.as already being mentioned above in the description of the „View“ menu
+
* Interfaces that are exported by an UNO object although not being exported by any of the supported services should be distinguished from the other interfaces. There should be displayed some kind of alert as their usage is potentially hazardous, because it is merely based on an implementation detail.
 +
 
 +
* Add a "Container" meta node that can be expanded to retrieve information about Elements. This node is only applicable when the UNO object also depicts a container that exports interfaces like XIndexAccess.
  
 
== See Also ==
 
== See Also ==
* [http://api.openoffice.org/Projects/ObjectInspector/Inspector.oxt] Object Inspector binary file
+
* [http://api.openoffice.org/servlets/ProjectDocumentList?folderID=636&expandFolder=636&folderID=0 Object Inspector binary file]
 +
* [[ObjectInspectorComparison|Object Inspector Comparison]]
 
* [[Constructing_Helpers#Reflection_Helper|C++ Reflection Helper]]
 
* [[Constructing_Helpers#Reflection_Helper|C++ Reflection Helper]]
* Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool] and a [[Extensions_development_basic#X-Ray_tool|XRay tool description]] in this wiki.
+
* Bernard Marcelly's [[Extensions_development_basic#Xray_tool|XRay tool description]] in this wiki.
 +
* [http://extensions.services.openoffice.org/project/MRI MRI an Object Inspector] written on Python from the Extension Website.
 
* [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces| Core Reflection Service]]
 
* [[IDL_Files_and_Cpp#Core_reflection_service__and_its_Interfaces| Core Reflection Service]]
* [[IDL_Files_and_Cpp#Using_Java_Inspector|Using Java Inspector]] (C++ and OOoBasic)
+
* [[IDL_Files_and_Cpp#Using_Java_Inspector|Using Java Inspector]] (C++ and AOOBasic)
 
+
* Using [[Programming_OOoWriter#Going_further_with_Inspector|the new object inspector]] with AOOWriter
[[Category:Development]]
+
[[Category:API]]
 
+
 
[[Category:Extensions]]
 
[[Category:Extensions]]
Current CWS Name: [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Id=4285&Path=SRC680%2Fsdkinspector  sdkinspector]
 

Revision as of 10:12, 25 March 2014

The Object Inspector is an OpenOffice.org extension created to help the developer to inspect arbitrary UNO-Objects. UNO provides a service-oriented API with abstract service descriptions exporting defined interfaces. The capabilities of a UNO Object do not open up to the developer at design time, mainly due to several "deficiencies". Please note that the Object Inspector is still under development.

The Problem

Generic interfaces like XPropertySet or XIndexAccess do not define their exact return value. Service descriptions that export these interfaces mostly do not contain such information either.

It is not always clear at design time which services a UNO object actually supports.

Documentation bugs: as service descriptions do not always show up all actually exported interfaces or properties, there may be a certain difference between the theoretical and the practical capabilities of a UNO object.

The Solution

The conclusion is that a runtime inspection is necessary to determine what respective capabilities a UNO object actually has. The Object Inspector is an OpenOffice.org extension that has been evolved from the ancient instance inspector that is part of the OpenOffice.org SDK. It displays the total capabilities of a "living UNO-object" such as all supported services, exported interfaces, and their respective methods and properties in a TreeView window.

Usage

The Object Inspector may be installed using the package manager (menu "Tools/Options") by adding the package from Inspector.oxt .

Together with the new package a new toolbar is added from which the object inspector may be started. The initial UNO object is the document of the active frame. The UNO object of this document is represented by the root node of the treelist control. Expanding this node will create subnodes referencing all subordinate objects, properties, methods and other values of the root object. All this information is presented in various facets:

Methods of UNO objects are presented as subnodes below a "Method" node. All methods are listed below this node, no matter what their parental interfaces are.

Properties of UNO objects are presented as subnodes below a "Properties" node.

"Interface" nodes offer a view to all methods by arranging them under their respective interface.

"Service" nodes offer a view to all supported services of a UNO object and their respectively exported interfaces and properties.

Expanding any arbitrary subnode will inspect the UNO object that is represented by the node in the same way as described above.

Screenshots

ObjectInspector.png

Calling from a Basic Macro

The Object Inspector may be instantiated within a Basic script as can be seen in the following examplary script, where the current document is inspected:

Sub Main
	oInspector = createUnoService("org.openoffice.InstanceInspector")
	oInspector.inspect(ThisComponent, "My Document")
End Sub

Sourcecode generation

The Object Inspector is also able to generate Sourcecode snippets that show how to:

  • query an interface (if necessary in the selected language)
  • invoke a method
  • retrieve a property value

Currently there are code generators for Java, C++, Python and Basic. The resulting code is not perfect, but should compile well. See Object Inspector Comparison.

IDL help

Currently broken

The user may retrieve help about selected nodes from the IDL files of the respective interface and service descriptions.

Development

Source code

You will find the Object Inspector source code within the OpenOffice.org Subversion Repository:

 svn co svn://svn.apache.org/repos/asf/openoffice/trunk/main/odk/examples/java/Inspector/

The checked in source contains a complete NetBeans project, so that one can immediately start hacking around. Feel free to commit bugfixes and changes or contact cli(at)openoffice.org if you like to take over the project.

Known issues

The Object inspector is still under development and the following list points to some known unresolved defects.

  • Filtering is slow and uncomfortable as nodes are collapsing and need to be expanded manually
  • IDL help is not working (including context sensitive help)
  • C++ code not properly generated (it was better with previous version). Read more here particularly Java Inspector 2 section.

Future Enhancements

  • Invocation of methods with complex parameters should be implemented. It should be implemented in several steps
    • Implementation of Array parameters with primitive elements.
    • Implementation of structs.
    • Implementation of an input mask to refer to UNO-Objects as method parameters.
    • Consider multidimensional arrays as method parameters and for return values.
  • An additional UNO GUI should be created, so that the extension integrates well in OOo and NetBeans. The existing model can be easily adapted to another GUI, hopefully.
  • Interfaces that are exported by an UNO object although not being exported by any of the supported services should be distinguished from the other interfaces. There should be displayed some kind of alert as their usage is potentially hazardous, because it is merely based on an implementation detail.
  • Add a "Container" meta node that can be expanded to retrieve information about Elements. This node is only applicable when the UNO object also depicts a container that exports interfaces like XIndexAccess.

See Also

Personal tools