Difference between revisions of "Documentation/DevGuide/Text/Handling Text Document Files"

Revision as of 15:43, 4 September 2008

Creating and Loading Text Documents

If a document in OpenOffice.org is required, begin by getting a com.sun.star.frame.Desktop service from the service manager. The desktop handles all document components in OpenOffice.org, among other things. It is discussed thoroughly in the chapter Office Development. Office documents are often called components, because they support the com.sun.star.lang.XComponent interface. An XComponent is a UNO object that can be disposed explicitly and broadcast an event to other UNO objects when this happens.

The Desktop can load new and existing components from a URL. For this purpose it has a com.sun.star.frame.XComponentLoader interface that has one single method to load and instantiate components from a URL into a frame:

 com.sun.star.lang::XComponent loadComponentFromURL([in] string aURL, 
         [in] string aTargetFrameName, 
         [in] long nSearchFlags, 
         [in] sequence< com::sun::star::beans::PropertyValue > aArgs );

The interesting parameters in our context are the URL that describes which resource should be loaded and the sequence of load arguments. For the target frame pass "_blank" and set the search flags to 0. In most cases you will not want to reuse an existing frame.

The URL can be a file: URL, a http: URL, an ftp: URL or a private: URL. Look up the correct URL format in the load URL box in the function bar of OpenOffice.org. For new writer documents, a special URL scheme has to be used. The scheme is "private:", followed by "factory" as hostname. The resource is "swriter" for OpenOffice.org writer documents. For a new writer document, use "private:factory/swriter".

The load arguments are described in com.sun.star.document.MediaDescriptor. The arguments AsTemplate and Hidden have properties that are boolean values. If AsTemplate is true, the loader creates a new untitled document from the given URL. If it is false, template files are loaded for editing. If Hidden is true, the document is loaded in the background. This is useful when generating a document in the background without letting the user observe; for example, it can be used to generate a document and print it without previewing. Office development describes other available options.

The section Example: Fields in a Template discusses a complete example about how loading works. The following snippet loads a document in hidden mode:

 // (the method getRemoteServiceManager is described in the chapter First Steps)
 mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl);
 
 // retrieve the Desktop object, we need its XComponentLoader
 Object desktop = mxRemoteServiceManager.createInstanceWithContext(
 "com.sun.star.frame.Desktop", mxRemoteContext);
 
 // query the XComponentLoader interface from the Desktop service
 XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface(
     XComponentLoader.class, desktop);
 
 // define load properties according to com.sun.star.document.MediaDescriptor
 
 /* or simply create an empty array of com.sun.star.beans.PropertyValue structs:
    PropertyValue[] loadProps = new PropertyValue[0]
  */
 
 // the boolean property Hidden tells the office to open a file in hidden mode
 PropertyValue[] loadProps = new PropertyValue[1];
 loadProps[0] = new PropertyValue();
 loadProps[0].Name = "Hidden";
 loadProps[0].Value = new Boolean(true); 
 
 // load
 return xComponentLoader.loadComponentFromURL(loadUrl, "_blank", 0, loadProps);