Dispatch Process

From Apache OpenOffice Wiki
Jump to: navigation, search

This section describes the necessary steps to handle dispatch providers and dispatch objects. The illustration below shows the services and interfaces of the the Dispatch framework.

Dispatch Framework

Getting a Dispatch Object

First, create a command URL that represents the desired functionality ensuring that it is parsed as described above. Tables with possible command URLs for the default office components of OpenOffice.org are located in the appendix.

Request the com.sun.star.frame.XDispatchProvider interface of the frame that contains the office component for a dispatch object for the command URL by calling its queryDispatch() method.

  com::sun::star::frame::XDispatch queryDispatch ( [in] com::sun::star::util::URL URL, 
                       [in] string TargetFrameName, 
                       [in] long SearchFlags )
  sequence< com::sun::star::frame::XDispatch > queryDispatches ( 
                       [in] sequence< com::sun::star::frame::DispatchDescriptor > Requests )

The additional parameters (TargetFrameName, SearchFlags) of this call are only used for dispatching public URL schemes, because they specify a target frame and frame search mode to the loading process. Valid target names and search flags are described in the section Target Frame. The targets "_self", "_parent" and "_top" are well defined, so that they can be used, because a queryDispatch() call starts at a frame object. Using frame names or search flags with command URLs does not have any meaning in the office components in OpenOffice.org.

You receive a dispatch object that supports at least com.sun.star.frame.XDispatch:

  [oneway] void dispatch ( [in] com::sun::star::util::URL URL, 
                           [in] sequence< com::sun::star::beans::PropertyValue > Arguments )
  [oneway] void addStatusListener ( [in] com::sun::star::frame::XStatusListener Control, 
                           [in] com::sun::star::util::URL URL )
  [oneway] void removeStatusListener ( [in] com::sun::star::frame::XStatusListener Control, 
                           [in] com::sun::star::util::URL URL )

Listening for Status Information

If a dispatch object is received, add a listener for status events by calling its addStatusListener() method. A com.sun.star.frame.XStatusListener implements:

  [oneway] void statusChanged ( [in] com::sun::star::frame::FeatureStateEvent Event )

Keep a reference to the dispatch object until you call the removeStatusListener() method, because it is not sure that any other object will keep it alive. If a status listener is not registered, because you want to dispatch a command,and are not interested in status events, release all references to the dispatch object immediately after usage. If a dispatch object is not received, the desired functionality is not available. If you have a visual user interface element that represents that functionality, disable it.

If a status listener is registered and there is status information, a com.sun.star.frame.FeatureStateEvent is received immediately after registering the listener. Status information is still received later if the status changes and you are still listening. The IsEnabled member of the com.sun.star.frame.FeatureStateEvent tells you if the functionality is currently available, and the State member holds information about a status that could be represented by UI elements. Its type depends on the command URL. A boolean status information is visualized in a pressed or not pressed look of a toolbox button. Other types need complex elements, such as combo boxes or spinfields embedded in a toolbox that show the current font and font size. If the State member is empty, the action does not have an explicit status, such as the menu item File - Print. The current status can be ambiguous, because more than one object is selected and the objects are in a different status, for example. selected text that is partly formatted bold and partly regular.

A special event is a status event where the Requery flag is set. This is a request to release all references to the dispatch object and to ask the dispatch provider for a new object, because the old one has become invalid. This allows the office components to accommodate internal context changes. It is possible that a dispatch object is not received, because the desired functionality has become unavailable.

If you do not get any status information in your statusChanged() implementation, assume that the functionality is always available, but has no explicit status.

If you are no longer interested in status events, use the removeStatusListener() method and release all references to the dispatch object. You may get a disposing() callback from the dispatch object when it is going to be destroyed. It is not necessary to call removeStatusListener(). Ensure that you do not hold any references to the dispatch object anymore.

Listening for Context Changes

Sometimes internal changes, for example, traveling from a text paragraph to a text table, or selecting a different type of object, force an office component to invalidate all referenced dispatch objects and provides other dispatch objects, including dispatches for command URLs it could not handle before. The component then calls the contextChanged() method of its frame, and the frame broadcasts the corresponding com.sun.star.frame.FrameActionEvent. For this reason, register a frame action listener using addFrameActionListener() at frames you want dispatch objects. Refer to section Frame Actions for additional information. If the listener is called back with a CONTEXT_CHANGED event, release all dispatch objects and query new dispatch objects for every command URL you require. You can also try command URLs that did not get a dispatch object before.

If you are no longer interested in context changes of a frame, use the removeFrameActionListener() method of the frame to deregister and release all references to the frame. If you get a disposing() request from the frame in between, it is not necessary to call removeFrameActionListener(), but you must release all frame references you are currently holding.

Dispatching a Command

If the desired functionality is available, execute it by calling the dispatch() method of the dispatch object. This method is called with the same command URL you used to get it, and optionally with a sequence of arguments of type com.sun.star.beans.PropertyValue that depend on the command. It is not redundant that supplied the URL again, because it is allowed to use one dispatch object for many command URLs. The appendix shows the names and types for the parameters. However, the command URLs for simple user interface elements, such as menu entries or toolbox buttons send no parameters. Complex user interface elements use parameters, for example, a combo box in a toolbar that changes the font height.

  // Conditions: sURL = "private:factory/swriter" 
  // lProperties = new com.sun.star.beans.PropertyValue[0] 
  // xSMGR = m_xServiceManager 
  // xListener = this
  // xFrame = a given frame  
  // Query the frame for right interface which provides access to all 
  // available dispatch objects. 
  com.sun.star.frame.XDispatchProvider xProvider = 
    (com.sun.star.frame.XDispatchProvider)UnoRuntime.queryInterface ( 
       com.sun.star.frame.XDispatchProvider .class, xFrame );
  // Create and parse a valid URL 
  // Note: because it is an in/out parameter we must use an array of URLs 
  com.sun.star.util.XURLTransformer xParser = 
    (com.sun.star.util.XURLTransformer)UnoRuntime.queryInterface ( 
      com.sun.star.util.XURLTransformer .class,
        xSMGR.createInstance("com.sun.star.util.URLTransformer" ));  
  com.sun.star.util.URL[] aParseURL = new com.sun.star.util.URL[1]; 
  aParseURL[0]          = new com.sun.star.util.URL(); 
  aParseURL[0].Complete = sURL; 
  xParser.parseStrict (aParseURL);  
  // Ask for dispatch object for requested URL and use it. 
  // Force given frame as target "" which means the same like "_self". 
  xDispatcher = xProvider.queryDispatch(aParseURL[0],"",0); 
   xDispatcher.addStatusListener (xListener,aParseURL[0]); 
   xDispatcher.dispatch (aParseURL[0],lProperties); 
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages