Chapter 5 Working with StarOffice Documents

The StarOffice API has been structured so that as many of its parts as possible can be used universally for different tasks. This includes the interfaces and services for creating, opening, saving, converting, and printing documents and for template administration. Since these function areas are available in all types of documents, they are explained first in this chapter.

The StarDesktop

When working with documents, there are two services which are used most frequently:

• The com.sun.star.frame.Desktop service, which is similar to the core service of StarOffice. It provides the functions for the frame object of StarOffice, under which all document windows are classified. Documents can also be created, opened and imported using this service.

• The basic functionality for the individual document objects is provided by the com.sun.star.document.OfficeDocument service. This provides the methods for saving, exporting and printing documents.

The com.sun.star.frame.Desktop service opens automatically when StarOffice is started. To do this, StarOffice creates an object which can be reached by means of the global name StarDesktop.

The most important interface of the StarDesktop is com.sun.star.frame.XComponentLoader. This basically covers the loadComponentFromURL method, which is responsible for creating, importing, and opening documents.

The name of the StarDesktop object dates back to StarOffice 5, in which all document windows were embedded in one common application called StarDesktop. In the present version of StarOffice, a visible StarDesktop is no longer used. The name StarDesktop was, however, retained for the frame object of StarOffice because it clearly indicates that this is a basic object for the entire application.

The StarDesktop object assumes the position of successor to the Application object of StarOffice 5 which previously applied as a root object. Unlike the old Application object however it is primarily responsible for opening new documents. The functions resident in the old Application object for controlling the on-screen depiction of StarOffice (for example, FullScreen, FunctionBarVisible, Height, Width, Top, Visible) are no longer used.

---

Note –

Whereas the active document in Word is accessed through Application.ActiveDocument and in Excel through Application.ActiveWorkbook, in StarOffice, the StarDesktop is responsible for this task. The active document object is accessed in StarOffice 7 through the StarDesktop.CurrentComponent property.

---

Basic Information about Documents in StarOffice

When working with StarOffice documents, it is useful to deal with some of the basic issues of document administration in StarOffice. This includes the way in which file names are structured for StarOffice documents, as well as the format in which files are saved.

File Names in URL Notation

Since StarOffice is a platform-independent application, it uses URL notation (which is independent of any operating system), as defined in the Internet Standard RFC 1738 for file names. Standard file names using this system begin with the prefix

file:///

followed by the local path. If the file name contains sub-directories, then these are separated by a single forward slash, not with a backslash usually used under Windows. The following path references the test.sxw file in the doc directory on the C: drive.

file:///C:/doc/test.sxw

To covert local file names into an URL, StarOffice provides the ConvertToUrl function. To convert a URL into a local file name, StarOffice provides the ConvertFromUrl function:

MsgBox ConvertToUrl("C:\doc\test.sxw") 
      ' supplies file:///C:/doc/test.sxw
MsgBox ConvertFromUrl("file:///C:/doc/test.sxw")    
      '  supplies (under Windows) c:\doc\test.sxw

The example converts a local file name into a URL and displays it in a message box. It then converts a URL into a local file name and also displays this.

The Internet Standard RFC 1738, upon which this is based, permits use of the 0-9, a-z, and A-Z characters. All other characters are inserted as escape coding in the URLs. To do this, they are converted into their hexadecimal value in the ISO 8859-1 (ISO-Latin) set of characters and are preceded by a percent sign. A space in a local file name therefore, for example, becomes a %20 in the URL.

XML File Format

Since Version 6.0, StarOffice provides an XML-based file format. Through the use of XML, the user has the option of also opening and editing files in other programs.

Compression of Files

Since XML is based on standard text files, the resultant files are usually very large. StarOffice therefore compresses the files and saves them as a ZIP file. By means of a storeAsURL method option, the user can save the original XML files directly. See storeAsURL Method Options.

Creating, Opening and Importing Documents

Documents are opened, imported and created using the method

StarDesktop.loadComponentFromURL(URL, Frame, _
            SearchFlags, FileProperties)

The first parameter of loadComponentFromURL specifies the URL of the associated file.

As the second parameter, loadComponentFromURL expects a name for the frame object of the window that StarOffice creates internally for its administration. The predefined _blank name is usually specified here, and this ensures that StarOffice creates a new window. Alternatively, _hidden can also be specified, and this ensures that the corresponding document is loaded but remains invisible.

Using these parameters, the user can open a StarOffice document, since place holders (dummy values) can be assigned to the last two parameters:

Dim Doc As Object
Dim Url As String
Dim Dummy() 

Url = "file:///C:/test.sxw"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

The preceding call opens the text.sxw file and displays this in a new window.

Any number of documents can be opened in this way in StarOffice Basic and then edited using the returned document objects.

---

Note –

StarDesktop.loadComponentFromURL supersedes the Documents.Add and Documents.Open methods from the old StarOffice API.

---

Replacing the Content of the Document Window

The named _blank and _hidden values for the Frame parameter ensure that StarOffice creates a new window for every call from loadComponentFromURL. In some situations, it is useful to replace the content of an existing window. In this case, the frame object of the window should contain an explicit name. Note that this name must not begin with an underscore. Furthermore, the SearchFlags parameter must be set so that the corresponding framework is created, if it does not already exist. The corresponding constant for SearchFlags is:

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

The following example shows how the content of an opened window can be replaced with the help of the frame parameter and SearchFlags:

Dim Doc As Object
Dim Dummy() 
Dim Url As String
Dim SearchFlags As Long

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

Url = "file:///C:/test.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

MsgBox "Press OK to display the second document."

Url = "file:///C:/test2.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

The example first opens the test.sxw file in a new window with the frame name of MyFrame. Once the message box has been confirmed, it replaces the content of the window with the test2.sxw file.

loadComponentFromURL Method Options

The fourth parameter of the loadComponentFromURL function is a PropertyValue data field. which provides StarOffice with various options for opening and creating documents. The data field must provide a PropertyValue structure for each option in which the name of the option is saved as a string as well as the associated value.

loadComponentFromURL supports the following options:

• AsTemplate (Boolean) – if true, loads a new, untitled document from the given URL. If is false, template files are loaded for editing.

• CharacterSet (String) – defines which set of characters a document is based on.

• FilterName (String) – specifies a special filter for the loadComponentFromURL function. The filter names available are defined in the \share\config\registry\instance\org\openoffice\office\TypeDetection.xml file.

• FilterOptions (String) – defines additional options for filters.

• JumpMark (String) – once a document has been opened, jumps to the position defined in JumpMark.

• Password (String) – transfers a password for a protected file.

• ReadOnly (Boolean) – loads a read-only document.

The following example shows how a text file separated by a comma in StarOffice Calc can be opened using the FilterName option.

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String

Url = "file:///C:/csv.doc"

FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv (StarOffice Calc)"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

The FileProperties data field covers precisely one value because it records one option. The Filtername property defines whether StarOffice uses a StarOffice Calc text filter to open files.

Creating New Documents

StarOffice automatically creates a new document if the document specified in the URL is a template.

Alternatively, if only an empty document without any adaptation is needed, a private:factory URL can be specified:

Dim Dummy() 
Dim Url As String
Dim Doc As Object

Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

The call creates an empty StarOffice writer document.

Document Objects

The loadComponentFromURL function introduced in the previous section returns a document object. This supports the com.sun.star.document.OfficeDocument service, which in turn provides two central interfaces:

• the com.sun.star.frame.XStorable interface, which is responsible for saving documents and

• the com.sun.star.view.XPrintable interface, which contains the methods for printing documents.

---

Note –

When changing over to StarOffice 8, you will find that the functional scope of the document objects has remained the same for the most part. The document objects, for example, still provide methods for saving and printing documents. The names and parameters of the methods have, however, changed.

---

Saving and Exporting Documents

StarOffice documents are saved directly through the document object. The store method of the com.sun.star.frame.XStorable interface is available for this purpose:

Doc.store()

This call functions provided that the document has already been assigned a memory space. This is not the case for new documents. In this instance, the storeAsURL method is used. This method is also defined in com.sun.star.frame.XStorable and can be used to define the location of the document:

Dim URL As String
Dim Dummy()

Url = "file:///C:/test3.sxw"

Doc.storeAsURL(URL, Dummy())

In addition to the preceding methods, com.sun.star.frame.XStorable also provides some help methods which are useful when saving documents. These are:

• hasLocation() – specifies whether the document has already been assigned a URL.

• isReadonly() – specifies whether a document has read-only protection.

• isModified() – specifies whether a document has been modified since it was last saved.

The code for saving a document can be extended by these options so that the document is only saved if the object has actually been modified and the file name is only queried if it is actually needed:

If (Doc.isModified) Then
   If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
      Doc.store()
   Else
      Doc.storeAsURL(URL, Dummy())
   End If
End If

The example first checks whether the relevant document has been modified since it was last saved. It only continues with the saving process if this is the case. If the document has already been assigned a URL and is not a read-only document, it is saved under the existing URL. If it does not have a URL or was opened in its read-only status, it is saved under a new URL.

storeAsURL Method Options

As with the loadComponentFromURL method, some options can also be specified in the form of a PropertyValue data field using the storeAsURL method. These determine the procedure StarOffice uses when saving a document. storeAsURL provides the following options:

• CharacterSet (String) – defines which set of characters a document is based on.

• FilterName (String) – specifies a special filter for the loadComponentFromURL function. The filter names available are defined in the \share\config\registry\instance\org\openoffice\office\TypeDetection.xml file.

• FilterOptions (String) – defines additional options for filters.

• Overwrite (Boolean) – allows a file which already exists to be overwritten without a query.

• Password (String) – transfers the password for a protected file.

• Unpacked (Boolean) – saves the document (not compressed) in sub-directories.

The following example shows how the Overwrite option can be used in conjunction with storeAsURL:

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String

' ... Initialize Doc 

Url = "file:///c:/test3.sxw"

FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True

Doc.storeAsURL(sUrl, mFileProperties())

The example then saves Doc under the specified file name if a file already exists under the name.

Printing Documents

Similar to saving, documents are printed out directly by means of the document object. The Print method of the com.sun.star.view.Xprintable interface is provided for this purpose. In its simplest form, the print call is:

Dim Dummy()

Doc.print(Dummy())

As in the case of the loadComponentFromURL method, the Dummy parameter is a PropertyValue data field through which StarOffice can specify several options for printing.

The options of the print method

The print method expects a PropertyValue data field as a parameter, which reflects the settings of the print dialog of StarOffice:

• CopyCount (Integer) – specifies the number of copies to be printed.

• FileName (String) – prints the document in the specified file.

• Collate (Boolean) – advises the printer to collate the pages of the copies.

• Sort (Boolean) – sorts the pages when printing out several copies (CopyCount > 1).

• Pages (String) – contains the list of the pages to be printed (syntax as specified in print dialog).

The following example shows how several pages of a document can be printed out using the Pages option:

Dim Doc As Object
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"

Doc.print(PrintProperties())

Printer selection and settings

The com.sun.star.view.XPrintable interface provides the Printer property, which selects the printer. This property receives a PropertyValue data field with the following settings:

• Name (String) – specifies the name of printer.

• PaperOrientation (Enum) – specifies the paper orientation (com.sun.star.view.PaperOrientation.PORTRAIT value for portrait format, com.sun.star.view.PaperOrientation.LANDSCAPE for landscape format).

• PaperFormat (Enum) – specifies the paper format (for example, com.sun.star.view.PaperFormat.A4 for DIN A4 or com.sun.star.view.PaperFormat.Letter for US letters).

• PaperSize (Size) – specifies the paper size in hundredths of a millimeter.

The following example shows how a printer can be changed and the paper size set with the help of the Printer property.

Dim Doc As Object
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size

PaperSize.Width = 20000   ' corresponds to 20 cm
PaperSize.Height = 20000   ' corresponds to 20 cm

PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"

PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize

Doc.Printer = PrinterProperties()

The example defines an object named PaperSize with the com.sun.star.awt.Size type. This is needed to specify the paper size. Furthermore, it creates a data field for two PropertyValue entries named PrinterProperties. This data field is then initialized with the values to be set and assigned the Printer property. From the standpoint of UNO, the printer is not a real property but an imitated one.

Templates

Templates are named lists containing formatting attributes. They move through all applications of StarOffice and help to significantly simplify formatting. If the user changes one of the attributes of a template, then StarOffice automatically adjusts all document sections depending on the attribute. The user can therefore, for example, change the font type of all level one headers by means of a central modification in the document. Depending on the relevant document types, StarOffice recognizes a whole range of different types of template.

StarOffice Writer supports

• character templates,

• paragraph templates,

• frame templates,

• page templates

• numbering templates

StarOffice Calc supports

• cell template

• page templates

StarOffice Impress supports

• character element templates

• presentation templates

In StarOffice terminology, the different types of templates are called StyleFamilies in accordance with the com.sun.star.style.StyleFamily service on which they are based. The StyleFamilies are accessed by means of the document object:

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim CellStyles As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
CellStyles = StyleFamilies.getByName("CellStyles")

The example uses the StyleFamilies property of a spreadsheet document to establish a list containing all available cell templates.

The individual templates can be accessed directly by means of an index:

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim CellStyles As Object
Dim CellStyle As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
CellStyles = StyleFamilies.getByName("CellStyles")

For I = 0 To CellStyles.Count - 1
   CellStyle = CellStyles(I)
   MsgBox CellStyle.Name
Next I

The loop added since the previous example displays the names of all cell templates one after another in a message box.

Details about various formatting options

Each type of template provides a whole range of individual formatting properties. Here is an overview of the most important formatting properties and the points at which they are explained:

• Character properties, Chapter 6, Text Documents, com.sun.star.style.CharacterProperties service

• Paragraph properties, Chapter 6, Text Documents, com.sun.star.text.Paragraph service

• Cell properties, Chapter 7, Spreadsheet Documents, com.sun.star.table.CellProperties service

• Page properties, Chapter 7, Spreadsheet Documents, com.sun.star.style.PageStyle service

• Character element properties, Chapter 7, Spreadsheet Documents, Various services

The format properties are by no means restricted to the applications in which these are explained, but instead can be used universally. For example, most of the page properties described in Chapter 7, Spreadsheet Documents can therefore be used not only in StarOffice Calc, but also in StarOffice Writer.

More information about working with templates can be found in the Default values for character and paragraph properties section in Chapter 6, Text Documents.