The Environment

Although direct control using UNO services provides the most control and versatility, some operations are much easier to perform using the dispatcher; sometimes a dispatcher is the only way to accomplish a task. For example, the dispatcher is the best solution for handling the clipboard. Even the macro recorder performs almost all tasks using a dispatcher.

Three things are required to accomplish tasks using a dispatcher: (1) the command to dispatch, (2) arguments that control the dispatch, and (3) an object capable of performing the dispatch (a dispatch provider, which is usually a frame). Each document has a controller that, loosely speaking, acts as the interface between the outside world and the document. For example, use the current controller to select text, find the current cursor location, or determine which sheet is active in a spreadsheet. The current controller can also return the frame of the document, which supports the dispatch command. OOo 1.1.0 introduces a dispatch helper service that greatly simplifies the use of dispatches (see Listing 2 ).

Listing 2: The DispatchHelper service greatly simplifies executing dispatches.

oDispHelper = createUnoService("com.sun.star.frame.DispatchHelper")

The dispatch helper implements the function executeDispatch, which implements most of the functionality required to perform a dispatch. Table 1 contains a list of the arguments supported by the executeDispatch method.

Listing 3: NewUndo is found in the Module1 module in this chapter's source code files as SC10.sxw.

Sub NewUndo
  Dim oDispHelper as object
  Dim oProvider As Object
  oProvider = ThisComponent.CurrentController.Frame
  oDispHelper = createUnoService("com.sun.star.frame.DispatchHelper")
  oDispHelper.executeDispatch(oProvider,".uno:Undo", "", , Array())
End Sub

While executing a dispatch, as discussed here, you cannot dispatch a command to a frame based on its name -either leave the target frame empty or enter "_self". It is also, therefore, not important to use anything other than zero, or omit the argument completely, for the search flag. Attempting to specify another frame results in a run-time error (it seems silly to me that the arguments exist if they are not usable).

The dispatch commands have both a name and a number, called a "slot." A dispatch can be made based on this slot number (see Listing 4 ). The Tools library contains a subroutine called DispatchSlot, which performs a dispatch based on a slot number alone. The macro recorder included with OOo 1.1.0 produces macros that accomplish all tasks with a dispatcher that uses slots. One of the lead developers on OOo indicated that the slot numbers are more likely to change between OOo versions than the dispatch names .

Listing 4: Dispatch to a numeric slot.

'Include this library to use the DispatchSlot command.
GlobalScope.BasicLibraries.LoadLibrary("Tools")
DispatchSlot(5301) 'Load the About dialog, same as ".uno:About"

Some dispatch commands require arguments. The examples in Listing 5 perform a dispatch with arguments. The GoToCell command needs to know which cell to go to. This macro moves the current cursor to the cell B3 in a spreadsheet document.

Listing 5: Dispatch commands can use arguments.

Dim args2(0) as new com.sun.star.beans.PropertyValue
args2(0).Name = "ToPoint"
args2(0).Value = "$B"     ' position to B3
Dim oDispHelper as object
Dim oProvider As Object
oProvider = ThisComponent.CurrentController.Frame
oDispHelper = createUnoService("com.sun.star.frame.DispatchHelper")
oDispHelper.executeDispatch(oProvider, ".uno:GoToCell", "", 0, args2())