Dispatch Results

From Apache OpenOffice Wiki
Jump to: navigation, search

Every dispatch object implements optional interfaces. An important extension is the com.sun.star.frame.XNotifyingDispatch interface for dispatch results. The dispatch() call is a void method and should be treated as an asynchronous or oneway call. Therefore a dispatch result can not be passed as a return value; rather, a callback interface is necessary. The interface that provides dispatch results by a callback is the com.sun.star.frame.XNotifyingDispatch interface:

  [oneway] void dispatchWithNotification ( [in] com::sun::star::util::URL URL, 
                             [in] sequence< com::sun::star::beans::PropertyValue > Arguments, 
                             [in] com::sun::star::frame::XDispatchResultListener Listener )

Its method dispatchWithNotification() takes a com.sun.star.frame.XDispatchResultListener interface that is called after a dispatched URL has been executed.

Documentation caution.png Although the dispatch process is considered to be asynchronous, this is not necessarily so. Therefore, be prepared to get the dispatch result notification before the dispatch call returns.

The dispatch result is transferred as a com.sun.star.frame.DispatchResultEvent struct in the callback method dispatchFinished(). The State member of this struct tells if the dispatch was successful or not, while the Result member contains the value that would be returned if the call had been executed as a synchronous function call. The appendix shows the types of return values. If a public URL is dispatched, the dispatch result is a reference to the frame the component was loaded into.

  // Conditions: sURL        = "private:factory/swriter" 
  //             lProperties = new com.sun.star.beans.PropertyValue[0] 
  //             xSMGR       = m_xServiceManager 
  //             xListener   = this  
  // 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 .class, 
       xSMGR.createInstance ("com.sun.star.util.URLTransformer "));
  // Ask for right dispatch object for requested URL and use it. 
  // Force given frame as target "" which means the same like "_self". 
  // Attention: The interface XNotifyingDispatch is an optional one!
  com.sun.star.frame.XDispatch xDispatcher = 
    xProvider.queryDispatch (aURL,"",0); 
  com.sun.star.frame.XNotifyingDispatch xNotifyingDispatcher =  
    (com.sun.star.frame.XNotifyingDispatch)UnoRuntime.queryInterface ( 
      com.sun.star.frame.XNotifyingDispatch.class , xDispatcher );
    xNotifyingDispatcher.dispatchWithNotification (aURL, lProperties, xListener);
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages