Saving a Document: XStorable | OpenOffice.org Macros Explained

The location where a document is saved is called its Uniform Resource Locator (URL)-in other words, its file name. A file URL usually contains the complete path to the file. When the file name is referred to as the URL, it has a form similar to "file:///c:/myfile.sxw" rather than "c:\myfile.sxw". A URL is a general way of writing a storage location, one that can be extended conveniently to include a wide range of storage location types in a manufacturer-independent and computer-independent manner. OOo Basic supports the functions ConvertToURL and ConvertFromURL to convert between the two notations. The XStorable interface defines object methods to save a document to a URL (see Table 9 ).

Table 9: Object methods defined by the service com.sun.star. frame.XStorable.
Object Method	Description
hasLocation()	True if the document has a storage location and False if this is a new blank document.
getLocation()	Return the URL where the object was stored after calling storeAsURL().
isReadonly()	You cannot call store() if the file was called from a read-only location.
store()	Stores the data to the current URL.
storeAsURL(URL, args)	Stores the document to the specified URL, which becomes the current URL.
storeToURL(URL, args)	Stores the document to the specified URL, but the current URL does not change.

Use the object method hasLocation() to determine if a document knows where to save itself, and use the method store() to save it to the current URL. The macro in Listing 15 uses methods defined by both XStorable and XModifiable to save a document to disk. The document is stored only if it knows where to store itself, it has changed, and it is not read-only.

Listing 15: Proper method to save a document.

 If (ThisComponent.isModified()) Then   If (ThisComponent.hasLocation() AND (Not ThisComponent.isReadOnly())) Then     ThisComponent.store()   Else     REM Either the document does not have a location or you cannot     REM save the document because the location is read-only.     setModified(False)   End If End If

A document does not have a storage location immediately after it is created. A document loaded from disk, however, has a known location. Use the object method storeAsURL() or storeToURL() to save a document to a specified location. The difference between the methods is that storeAsURL() sets the current location (URL) and storeToURL does not. The sequence of actions in Table 10 helps clarify the difference.

Table 10: Difference between storeToURL and storeAsURL.
Step	Action	Comment
1	Create document	Cannot use the store() method because the document has no location.
2	Use storeToURL	Document saved, but cannot use the store() methodbecause it has no location.
3	Use storeAsURL	Can use the store() method because now the document has a location.
4	Use storeToURL	Document saved, but the location is the same as set in step 3.

Note	The method storeAsURL() is similar to the menu option File Save As, which changes the current location. The method storeToURL() is usually used to export a document so that the file URL does not change and contain a non-OOo document extension.

The two object methods for storing a document, storeAsURL() and storeToURL(), accept the same arguments; learn to use one and you'll know how to use the other.

 ThisComponent.storeAsURL(url, args()) ThisComponent.storeToURL(url, args())

The second argument is an array of property values (see Table 8) that direct how the document is saved (see Listing 16 ). The files can just as easily be stored with no arguments (see Listing 17 ).

Listing 16: Save a document to a new location.

 Dim args(0) As New com.sun.star.beans.PropertyValue Dim sUrl As String sUrl = "file:///c:/My%20Documents/test_file.sxw" args(0).Name = "Overwrite"  'This property is defined in Table 8 args(0).Value = False       'Do not overwrite an existing document. ThisComponent.storeAsURL(sUrl, args())

Listing 17: Save the document with an inappropriate file extension.

 ThisComponent.storeToURL("file:///c:/two.xls" , Array())

Note

The com.sun. star. frame.XComponentLoader interface defines the object method LoadComponentFromUrl(), which is used to load a file. The different document types do not implement this interface, but the document frame and the desktop both implement the interface. The method LoadComponentFromUrl() also uses the values in Table 8 to direct how the file is loaded.

Warning

The macro in Listing 17 uses the file extension "xls", which is typically used by Microsoft Excel. This does not cause the file to be stored using the Microsoft Excel format. The file is saved using the standard OOo file format if an export filter is not explicitly stated.

When you open a file, OOo checks to see if the file is in a standard OOo file format. If not, the file type is determined based on the file extension. I cannot even count the number of times that I have been asked why OOo is not able to open a comma-delimited text file. The usual answer is that a comma-delimited file must have the file extension CSV or OOo cannot recognize the file. Although the file extension is important while loading a file from the GUI, it is not important while saving. If you want to save a file in a non-OpenOffice.org native format, you must explicitly tell OOo to save in a different file format (see Listing 18 ).

Listing 18: Export a document to the specified Microsoft Excel file format.

 Dim args(0) as new com.sun.star.beans.PropertyValue args(0).Name = "FilterName"         'I am so excited, which filter will we use? args(0).Value = "MS Excel 97"       'Oh, the Excel 97 format! ThisComponent.storeToURL("file:///c:/one.xls",args())

Note	Although the export filter names are the same as the import filter names , not every import filter can export and not every export filter can import.

Impress and Draw, used to edit graphical content, support multiple draw pages. To export a draw page to a specific graphics format requires the use of a graphics export filter (see Listing 19 ). The media type must be specified or the export will fail.

Listing 19: Export the first draw page to a JPG file.

 Dim oFilter Dim args(1) as new com.sun.star.beans.PropertyValue oFilter=CreateUnoService("com.sun.star.drawing.GraphicExportFilter") oFilter.setSourceDocument(ThisComponent.drawPages(0)) args(0).Name = "URL"                 'Where the file will be saved args(0).Value = "file:///c:/one.JPG" 'The destination URL args(1).Name = "MediaType"           'What type of file args(1).Value = "image/jpeg"         'The file type oFilter.filter(args())