Difference between revisions of "Documentation/DevGuide/ProUNO/Basic/Getting Information about UNO Objects"
m (→Inspector tools) |
|||
Line 17: | Line 17: | ||
The first parameter <code>HasUnoInterfaces()</code> expects is the object that should be tested. Parameter(s) of one or more fully qualified interface names can be passed to the function next. The function returns <code>True</code> if all these interfaces are supported by the object, otherwise <code>False</code>. | The first parameter <code>HasUnoInterfaces()</code> expects is the object that should be tested. Parameter(s) of one or more fully qualified interface names can be passed to the function next. The function returns <code>True</code> if all these interfaces are supported by the object, otherwise <code>False</code>. | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Sub Main | Sub Main | ||
Dim oSimpleFileAccess | Dim oSimpleFileAccess | ||
Line 41: | Line 41: | ||
MsgBox bSuccess ' Displays False because XPropertySet is NOT supported | MsgBox bSuccess ' Displays False because XPropertySet is NOT supported | ||
End Sub | End Sub | ||
− | </ | + | </syntaxhighlight> |
=== Testing if an object is a struct during runtime === | === Testing if an object is a struct during runtime === | ||
As described in the section [[Documentation/DevGuide/ProUNO/Basic/Mapping of Structs|Mapping of Structs]] above, structs are handled differently from objects, because they are treated as values. Use the <code>IsUnoStruct()</code> function to check it the UNO Basic object represents an object or a struct. This function expects one parameter and returns <code>True</code> if this parameter is a UNO struct, otherwise <code>False</code>. Example: | As described in the section [[Documentation/DevGuide/ProUNO/Basic/Mapping of Structs|Mapping of Structs]] above, structs are handled differently from objects, because they are treated as values. Use the <code>IsUnoStruct()</code> function to check it the UNO Basic object represents an object or a struct. This function expects one parameter and returns <code>True</code> if this parameter is a UNO struct, otherwise <code>False</code>. Example: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Sub Main | Sub Main | ||
Dim bIsStruct | Dim bIsStruct | ||
Line 60: | Line 60: | ||
MsgBox bIsStruct ' Displays False because 42 is NO struct | MsgBox bIsStruct ' Displays False because 42 is NO struct | ||
End Sub | End Sub | ||
− | </ | + | </syntaxhighlight> |
=== Testing objects for identity during runtime === | === Testing objects for identity during runtime === | ||
To find out if two UNO {{AOo}} Basic objects refer to the same UNO object instance, use the function <code>EqualUnoObjects()</code>. Basic is not able to apply the comparison operator = to arguments of type <tt>object</tt>, for example, <code>If Obj1 = Obj2 Then</code> will produce a runtime error. | To find out if two UNO {{AOo}} Basic objects refer to the same UNO object instance, use the function <code>EqualUnoObjects()</code>. Basic is not able to apply the comparison operator = to arguments of type <tt>object</tt>, for example, <code>If Obj1 = Obj2 Then</code> will produce a runtime error. | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Sub Main | Sub Main | ||
Dim bIdentical | Dim bIdentical | ||
Line 88: | Line 88: | ||
' and so aProperty2 is a copy of aProperty | ' and so aProperty2 is a copy of aProperty | ||
End Sub | End Sub | ||
− | </ | + | </syntaxhighlight> |
Basic hides interfaces behind {{AOo}} Basic objects that could lead to problems when developers are using API structures. It can be difficult to understand the API reference and find the correct method of accessing an object to reach a certain goal. | Basic hides interfaces behind {{AOo}} Basic objects that could lead to problems when developers are using API structures. It can be difficult to understand the API reference and find the correct method of accessing an object to reach a certain goal. | ||
Line 96: | Line 96: | ||
The <code>Dbg_SupportedInterfaces</code> lists all interfaces supported by the object. In the following example, the object returned by the function <code>GetProcessServiceManager()</code> described in the previous section is taken as an example object. | The <code>Dbg_SupportedInterfaces</code> lists all interfaces supported by the object. In the following example, the object returned by the function <code>GetProcessServiceManager()</code> described in the previous section is taken as an example object. | ||
− | < | + | <syntaxhighlight lang="oobas"> |
oServiceManager = GetProcessServiceManager() | oServiceManager = GetProcessServiceManager() | ||
MsgBox oServiceManager.Dbg_SupportedInterfaces | MsgBox oServiceManager.Dbg_SupportedInterfaces | ||
− | </ | + | </syntaxhighlight> |
This call displays a message box: | This call displays a message box: | ||
Line 111: | Line 111: | ||
The <code>Dbg_Properties</code> lists all properties supported by the object through <idl>com.sun.star.beans.XPropertySet</idl> and through get and set methods that could be mapped to Basic object properties: | The <code>Dbg_Properties</code> lists all properties supported by the object through <idl>com.sun.star.beans.XPropertySet</idl> and through get and set methods that could be mapped to Basic object properties: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
oServiceManager = GetProcessServiceManager() | oServiceManager = GetProcessServiceManager() | ||
MsgBox oServiceManager.Dbg_Properties | MsgBox oServiceManager.Dbg_Properties | ||
− | </ | + | </syntaxhighlight> |
This code produces a message box like the following example: | This code produces a message box like the following example: | ||
Line 122: | Line 122: | ||
The <code>Dbg_Methods</code> lists all methods supported by an object. Example: | The <code>Dbg_Methods</code> lists all methods supported by an object. Example: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
oServiceManager = GetProcessServiceManager() | oServiceManager = GetProcessServiceManager() | ||
MsgBox oServiceManager.Dbg_Methods | MsgBox oServiceManager.Dbg_Methods | ||
− | </ | + | </syntaxhighlight> |
This code displays: | This code displays: | ||
Line 135: | Line 135: | ||
=== Inspector tools === | === Inspector tools === | ||
− | Using these <tt>Dbg_</tt> properties is a very crude method to discover the contents of an API objects. Use instead <b>[[Extensions_development_basic#Xray_tool|Xray tool]]</b> or <b>[ | + | Using these <tt>Dbg_</tt> properties is a very crude method to discover the contents of an API objects. Use instead <b>[[Extensions_development_basic#Xray_tool|Xray tool]]</b> or <b>[https://extensions.services.openoffice.org/project/MRI MRI tool]</b>. |
− | The list of elements may be inconveniently long for MsgBox display. Code is available to write all <tt>Dbg_</tt> elements to a new Writer document. See | + | The list of elements may be inconveniently long for MsgBox display. Code is available to write all <tt>Dbg_</tt> elements to a new Writer document. See {{AOo}} Macros > Tools > Debug > WritedbgInfo. The <tt>Tools</tt> library must be loaded to use this routine: |
− | < | + | <syntaxhighlight lang="oobas"> |
GlobalScope.BasicLibraries.LoadLibrary( "Tools" ) | GlobalScope.BasicLibraries.LoadLibrary( "Tools" ) | ||
Call Tools.WritedbgInfo(MyObject) | Call Tools.WritedbgInfo(MyObject) | ||
− | </ | + | </syntaxhighlight> |
{{PDL1}} | {{PDL1}} | ||
[[Category:Documentation/Developer's Guide/Professional UNO]] | [[Category:Documentation/Developer's Guide/Professional UNO]] |
Latest revision as of 13:28, 23 December 2020
The Basic RTL retrieves information about UNO objects. There are functions to evaluate objects during runtime and object properties used to inspect objects during debugging.
Checking for interfaces during runtime
Although Basic does not support the queryInterface concept like C++ and Java, it can be useful to know if a certain interface is supported by a UNO Basic object or not. The function HasUnoInterfaces()
detects this.
The first parameter HasUnoInterfaces()
expects is the object that should be tested. Parameter(s) of one or more fully qualified interface names can be passed to the function next. The function returns True
if all these interfaces are supported by the object, otherwise False
.
Sub Main Dim oSimpleFileAccess oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" ) Dim bSuccess Dim IfaceName1$, IfaceName2$, IfaceName3$ 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 End Sub
Testing if an object is a struct during runtime
As described in the section Mapping of Structs above, structs are handled differently from objects, because they are treated as values. Use the IsUnoStruct()
function to check it the UNO Basic object represents an object or a struct. This function expects one parameter and returns True
if this parameter is a UNO struct, otherwise False
. Example:
Sub Main Dim bIsStruct ' Instantiate a service Dim oSimpleFileAccess oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" ) bIsStruct = IsUnoStruct( oSimpleFileAccess ) MsgBox bIsStruct ' Displays False because oSimpleFileAccess is NO struct ' Instantiate a Property struct 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 End Sub
Testing objects for identity during runtime
To find out if two UNO Apache OpenOffice Basic objects refer to the same UNO object instance, use the function EqualUnoObjects()
. Basic is not able to apply the comparison operator = to arguments of type object, for example, If Obj1 = Obj2 Then
will produce a runtime error.
Sub Main Dim bIdentical Dim oSimpleFileAccess, oSimpleFileAccess2, oSimpleFileAccess3 ' Instantiate a service oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" ) oSimpleFileAccess2 = oSimpleFileAccess ' Copy the object reference bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess2 ) MsgBox bIdentical ' Displays True because the objects are identical ' Instantiate the service a second time oSimpleFileAccess3 = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" ) bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess3 ) MsgBox bIdentical ' Displays False, oSimpleFileAccess3 is another instance bIdentical = EqualUnoObjects( oSimpleFileAccess, 42 ) MsgBox bIdentical ' Displays False, 42 is not even an object ' Instantiate a Property struct Dim aProperty As New com.sun.star.beans.Property Dim aProperty2 aProperty2 = aProperty ' Copy the struct bIdentical = EqualUnoObjects( aProperty, aProperty2 ) MsgBox bIdentical ' Displays False because structs are values ' and so aProperty2 is a copy of aProperty End Sub
Basic hides interfaces behind Apache OpenOffice Basic objects that could lead to problems when developers are using API structures. It can be difficult to understand the API reference and find the correct method of accessing an object to reach a certain goal.
To assist during development and debugging, every UNO object in Apache OpenOffice Basic has special properties that provide information about the object structure. These properties are all prefixed with Dbg_
to emphasize their use for development and debugging purposes. The type of these properties is String
. To display the properties use the MsgBox
function.
Inspecting interfaces during debugging
The Dbg_SupportedInterfaces
lists all interfaces supported by the object. In the following example, the object returned by the function GetProcessServiceManager()
described in the previous section is taken as an example object.
oServiceManager = GetProcessServiceManager() MsgBox oServiceManager.Dbg_SupportedInterfaces
This call displays a message box:
The list contains all interfaces supported by the object. For interfaces that are derived from other interfaces, the super interfaces are indented as shown above for com.sun.star.container.XSet, which is derived from com.sun.star.container.XEnumerationAccess based upon com.sun.star.container.XElementAccess.
If the text "(ERROR: Not really supported!)" is printed behind an interface name, the implementation of the object usually has a bug, because the object pretends to support this interface (per com.sun.star.lang.XTypeProvider, but a query for it fails. For details, see UNO Reflection API). |
Inspecting properties during debugging
The Dbg_Properties
lists all properties supported by the object through com.sun.star.beans.XPropertySet and through get and set methods that could be mapped to Basic object properties:
oServiceManager = GetProcessServiceManager() MsgBox oServiceManager.Dbg_Properties
This code produces a message box like the following example:
Inspecting Methods During Debugging
The Dbg_Methods
lists all methods supported by an object. Example:
oServiceManager = GetProcessServiceManager() MsgBox oServiceManager.Dbg_Methods
This code displays:
The notations used in Dbg_Properties
and Dbg_Methods
refer to internal implementation type names in Basic. The Sbx
prefix can be ignored. The remaining names correspond with the normal Basic type notation. The SbxEMPTY
is the same type as Variant
. Additional information about Basic types is available in the next chapter.
Basic uses the com.sun.star.lang.XTypeProvider interface to detect which interfaces an object supports. Therefore, it is important to support this interface when implementing a component that should be accessible from Basic. For details, see Writing UNO Components. |
Inspector tools
Using these Dbg_ properties is a very crude method to discover the contents of an API objects. Use instead Xray tool or MRI tool.
The list of elements may be inconveniently long for MsgBox display. Code is available to write all Dbg_ elements to a new Writer document. See Apache OpenOffice Macros > Tools > Debug > WritedbgInfo. The Tools library must be loaded to use this routine:
GlobalScope.BasicLibraries.LoadLibrary( "Tools" ) Call Tools.WritedbgInfo(MyObject)
Content on this page is licensed under the Public Documentation License (PDL). |