[Tutorial] Introduction into object inspection with MRI

[rudolfo]

Download and Install

MRI is an extension and can be downloaded from the OpenOffice Extension Site: http://extensions.services.openoffice.o ... roject/MRI. Install it as any other extension with the help of the extension manager. See the online Help (F1) for detailed information:
Common Help Topics -> Configuring OpenOffice.org -> Extension Manager

Note, that the Python UNO-Bridge needs to be installed for the MRI to work. The Python UNO-Bridge is installed by default. So unless you explicitly deselected it during a custom install, your OpenOffice is ready for MRI.

You can start MRI from the Tools -> Add-ons Menu. There you have the choice to either run it without referencing anything (in this case initial target is the current document) or with referencing the current selection. Then the initial target is the object that matches with the selection.

Menu items to start MRI

MRI-menu.png (20.59 KiB) Viewed 16289 times

One thing that you surely want to do when you have opened the MRI dialog for the first time is to go to its options (that's the Tools menu in the MRI window/frame and from that drop down menu the last item "Configuration...") and specify the location of the API documentation (in most cases you should leave the default http://api.openoffice.org/ unless you don't have a permanent internet connection and want to use a SDK that you installed on your local hard drive) and, probably more important, the browser that you want to use to visit the API pages. The path to the browser needs to be in the generic URI form with file:// as protocol specifier in the front. Up to today most of us are still thinking of C:\Program Files\Firefox\firefox.exe or /usr/local/bin/firefox as a path. I don't want to cure you from old habits, even if they are bad habits, so simply click on the [Select] button and navigate to the browser's executable file.

Configuration

MRI-configuration.png (2.42 KiB) Viewed 16289 times

Documentation

MRI comes with an extensive help system that is integrated into the normal OpenOffice online help during its installation. Unfortunately this is often overlooked, because many people simply don't expect an extension to behave in such a nice way. They typically think: "It's an extension for free. There is probably no documentation apart from the Readme file on its website."

MRI built-in help

[rudolfo]

Working with MRI

One of the best and at the same time most irritating things of MRI is that it has a menu option to generate code in different scripting languages. This sounds very promising if only you could figure out where to find this generated code.

MRI Initial window layout

The solution is to hold the mouse pointer above the upper border of the MRI status line. The pointer will change to a symbol that indicates that you can drag a border with it. And that's the whole clue: The initial size of the code window is zero and you just need to increase it a bit.

MRI Code window visible

Whenever you double click on a Method or Property the code window will show some more lines of code (the ones that are needed to get from the initial object to the object of this property or this method). At the same time the middle window with all the properties and methods will change to the properties/methods of the new object. If you double click on a method that requires parameters (as for the above shown goDown) MRI will popup a dialog and ask you for a value for each one of the required parameters.
If you can't guess what a method is doing by its name or if you need more detailed information on a method you can click the big IDL Ref. button and your browser will take you to the right place in the API documentation. In the above case with the goDown selected this would be: http://www.openoffice.org/api/docs/comm ... tml#goDown

If you have got lost in the object hierarchy after clicking on some properties or methods you have always the chance to get back to your initial object (or any other object that you selected on your way) with the dropdown box in the second row.

MRI Details

As you might see in the above image the layout in Windows-7 has some flaws: Instead the 4 choices (Properties, Methods, Interfaces and SupportedServices) the multi-selection shows only the first two of them together with some ugly scrollbars. Ugly or not, the scrollbars ensure that you can also get two these to other (hidden) features.

Edit: This inconsistency is not a problem of Windows 7. It is related with the fact that the monitor that I use together with the Windows 7 OS has a very high pixel density and is still rather small. The standard font was very hard to read and was therefore changed to a larger font. If you continue to use the standard font set you will see all 4 choices of the multiselection. The problem appears only if you have a larger font and the space in the multiselect box is therefore only enough for 2 sections in the larger font but not for all 4.

With the code window MRI can serve as a macro recorder, that records real API functions in contrary to the standard macro recorder of OpenOffice that only records dispatcher calls. But MRI doesn't record what you are doing (your keystrokes and mouse-clicks) in one of the OOo Applications, but your clicks in MRI. This means if you want to create a macro that changes the name of the spreadsheet on which your cursor is you select "MRI <- Selection" and have the current cell as initial Target in MRI. You have to search through the methods and find a getSpreadsheet, that sounds promising to you. After a double click on it you see that the text box at the top of MRI says "com.sun.star.sheet.XSpreadsheet", which is a good sign. So you browse again through the list of methods until you get to 's' and setName. Another double click brings up a dialog where you can type in a new name. You type "aNewName" and you will see a text box dialog saying void (because the method did not return anything), but the name of your spreadsheet tab at the bottom has changed to "aNewName".

A useful feature of MRI is that you can build a diff between two states/snapshots of a property. This is described very well in the built-in help under the section title "Tips":

If you want to change a property of a object but you do not know the name of the property. However you can change it through UI.

This enables you to record GUI operations indirectly. The diff will point you to the property that is changed and that you need to use. But you still have to select this property that you see highlighted in the diff in a second pass in MRI to have it recorded.

Use it from within a macro

The above mentioned builtin online documentation has a detailed section about how to start MRI from macro code: "How to Run MRI". It shows how to do this with most of the languages that are supported by OOo. For the sake of brevity I will show here only how to do it with OOo Basic:

Code: Select all   Expand viewCollapse view

Global oMRI As Object

Sub InitializeMRI()
  Globalscope.BasicLibraries.LoadLibrary("MRILib")
  oMRI = CreateUnoService("mytools.Mri")
End Sub

' and later anywhere in your Subs, Functions ...
Sub SomeSub()
  ...
  oMRI.inspect( theObjectThatYouWantToInspect )
  ...
End Sub

Sub a_onClick_Handler(oEvent As Object)
  Dim oForm As Object

  oMRI.inspect(oEvent.Source)

  oForm = oEvent.Source.Model.getParent()
  oMRI.inspect(oForm)


Before you can use MRI you have to load its Basic wrapper into the GlobalScope of the Basic Libraries. That's done with the first line of InitializeMRI. The next line creates the MRI Uno-Service and puts it into a global variable. This has the advantage that it is available in all subroutines and functions in the same macro file simply by executing InitializeMRI once before you run your other macro code.

There is one caveat and this is that any global variables will be reset if the file where the variable resides is re-compiled. Because you are typically using MRI when developing a new macro, it is quite common that you start MRI in the macro code, click your way around in MRI until you have found the property or method you are looking for, finish the macro and make the appropriate changes in you macro code. You run your code again, maybe with a different initial target for MRI (because you got some steps further) ... and oops you get can an error in the line with oMRI.inspect. The reason is, after your changes to the macro, OOo needed to re-compile the macro file and the global variable oMRI lost its value and was reset to NULL/nothing. In other words most of the times you have to call InitializeMRI before you run your macro. After you forgot this two or three times you are fed up with this and you will put a Call InitializeMRI at the beginning of the Sub you are working on.

Other threads related with MRI

Villeroy lists 8 advantages of MRI compared to Xray: [Solved] Combobox and controls in forms
Hanya who developed MRI on instantiating services: Select complete columns and object model documentation
Arineckaig on using MRI with forms and/or form controls: [Base] Call MRI on forms or form controls from form document
Arineckaig has also written a step by step guide on how to navigate with MRI through the object hierarchy of the UNO objects. This .odt Writer file is uploaded to the forum and can be accessed as:

MRI demo Writer document.odt

(114.31 KiB) Downloaded 1133 times