View source for Documentation/BASIC Guide/StarDesktop

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Documents
|NextPage=Documentation/BASIC Guide/Templates
|docs=block
}} 
{{DISPLAYTITLE:The StarDesktop}}
__NOTOC__ 
When working with documents, two services are used most frequently: 

* The <idl>com.sun.star.frame.Desktop</idl> service, which is similar to the core service of {{OOo}}. It provides the functions for the frame object of {{OOo}}, 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 <idl>com.sun.star.document.OfficeDocument</idl> service. This provides the methods for saving, exporting and printing documents.

The <idl>com.sun.star.frame.Desktop</idl> service is created automatically when {{OOo}} is started. This service can be addressed in {{OOo}} Basic using the global name <tt>StarDesktop</tt>. 

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

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

The <tt>StarDesktop</tt> object replaces the <tt>Application</tt> object of StarOffice 5 which previously applied as a root object. However, unlike the old <tt>Application</tt> object, <tt>StarDesktop</tt> is primarily responsible for opening new documents. The functions resident in the old <tt>Application</tt> object for controlling the on-screen depiction of {{OOo}} (for example, <tt>FullScreen</tt>, <tt>FunctionBarVisible</tt>, <tt>Height</tt>, <tt>Width</tt>, <tt>Top</tt>, <tt>Visible</tt>) are no longer used.}}

{{Documentation/VBAnote|Whereas the active document in Word is accessed through <tt>Application.ActiveDocument</tt> and in Excel through <tt>Application.ActiveWorkbook,</tt> in {{OOo}}, the <tt>StarDesktop</tt> is responsible for this task. The active document object is accessed in {{OOo}} through the <tt>StarDesktop.CurrentComponent</tt> property, or through <tt>ThisComponent</tt>.}}

== ThisComponent ==
The global name <tt>ThisComponent</tt> generally returns the same object as <tt>StarDesktop.CurrentComponent</tt>, with one significant advantage. If you are running from within the Basic IDE, debugging or exploring, then <tt>StarDesktop</tt> returns the Basic IDE itself. This is probably not what you want. <tt>ThisComponent</tt> returns the last previously active document.

== Basic Information about Documents in {{OOo}} ==

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

=== File Names in URL Notation ===

Since {{OOo}} 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 <tt>file:///</tt> 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 <tt>test.odt</tt> file in the doc directory on the C: drive.

 file:///C:/doc/test.odt

To convert local file names into an URL, {{OOo}} provides the <tt>ConvertToUrl</tt> function. To convert a URL into a local file name, {{OOo}} provides the <tt>ConvertFromUrl</tt> function: 

<source lang="oobas">
MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' supplies file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  supplies (under Windows) c:\doc\test.odt
</source>

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 <tt>0-9</tt>, <tt>a-z</tt>, and <tt>A-Z</tt> characters. All other characters are inserted as escape coding in the URLs. To do this, they are converted into their hexadecimal value in the UTF-8 set of characters and are preceded by a percent sign. A space in a local file name therefore, for example, becomes a <tt>%20</tt> in the URL.

=== XML File Format ===

{{OOo}} documents are based on the XML file format.  XML-based files can be opened and edited with other programs.

=== Compression of Files ===

Since XML is based on standard text files, the resultant files are usually very large. {{OOo}} therefore compresses the files and saves them as a ZIP file. By means of a <tt>storeAsURL</tt> method option, the user can save the original XML files directly. See [[Documentation/BASIC Guide/StarDesktop#storeAsURL Method Options|storeAsURL Method Options]], below.

== Creating, Opening and Importing Documents ==

Documents are opened, imported and created using the method 

<source lang="oobas">
StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)
</source>

The first parameter of <tt>loadComponentFromURL</tt> specifies the URL of the associated file. 

As the second parameter, <tt>loadComponentFromURL</tt> expects a name for the frame object of the window that {{OOo}} creates internally for its administration. The predefined <tt>_blank</tt> name is usually specified here, and this ensures that {{OOo}} creates a new window.

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

<source lang="oobas">
Dim Doc As Object
Dim Url As String
Dim Dummy() 'An (empty) array of PropertyValues

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

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)
</source>

The preceding call opens the <tt>test.odt</tt> file and displays this in a new window. 

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

{{Documentation/SO5note|<tt>StarDesktop.loadComponentFromURL</tt> supersedes the <tt>Documents.Add</tt> and <tt>Documents.Open</tt> methods from the old {{OOo}} API.}}

=== Replacing the Content of the Document Window ===

The named <tt>_blank</tt> value for the <tt>Frame</tt> parameter ensures that {{OOo}} creates a new window for every call from <tt>loadComponentFromURL</tt>. 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 <tt>SearchFlags</tt> parameter must be set so that the corresponding framework is created, if it does not already exist. The corresponding constant for <tt>SearchFlags</tt> is:

<source lang="oobas">
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL
</source>

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

<source lang="oobas">
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.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)
MsgBox "Press OK to display the second document."

Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)
</source>

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

=== loadComponentFromURL Method Options ===

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

<tt>loadComponentFromURL</tt> supports the following options:

;<tt>AsTemplate (Boolean)</tt>:if true, loads a new, untitled document from the given URL. If is false, template files are loaded for editing.
;<tt>CharacterSet (String)</tt>:defines which set of characters a document is based on.
;<tt>FilterName (String)</tt>:specifies a special filter for the <tt>loadComponentFromURL</tt> function. The filter names available are defined in the <tt>\share\config\registry\instance\org\openoffice\office\TypeDetection.xml</tt> file.
;<tt>FilterData (String)</tt>:defines additional options for filters.
;<tt>FilterOptions (String)</tt>:defines additional options (used by old filters).
;<tt>Hidden (Boolean)</tt>:value true loads the document in invisible mode.
;<tt>JumpMark (String)</tt>:once a document has been opened, jumps to the position defined in JumpMark.
;<tt>MacroExecutionMode (Integer)</tt>:indicates if document macros may be executed. Values : see <idl>com.sun.star.document.MacroExecMode</idl>
;<tt>Password (String)</tt>:transfers a password for a protected file.
;<tt>ReadOnly (Boolean)</tt>:value true loads a document in read-only mode.
;<tt>UpdateDocMode (Integer)</tt>:indicates how/if links will be updated. Values : see <idl>com.sun.star.document.UpdateDocMode</idl>

The following example shows how a text file separated by a comma in {{OOo}} Calc can be opened using the <tt>FilterName</tt> option. 

<source lang="oobas">
Dim Doc As Object
Dim FileProperties(1) As New com.sun.star.beans.PropertyValue
Dim Url As String

Url = "file:///C:/doc.csv"
FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="Text - txt - csv (StarCalc)"
FileProperties(1).Name = "FilterOptions"
FileProperties(1).value  = "44,34,0,1"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())
</source>

The <tt>FileProperties</tt> array has two elements, one for each option used. The <tt>Filtername</tt> property defines whether {{OOo}} uses a {{OOo}} Calc text filter to open files. The <tt>FilterOptions</tt> property contains the description of the syntax of the csv file.

=== Creating New Documents ===

{{OOo}} 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 <tt>private:factory</tt> URL can be specified:

<source lang="oobas">
Dim Dummy() 
Dim Url As String
Dim Doc As Object

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

The call creates an empty {{OOo}} writer document.

== Document Objects ==

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

* The <idl>com.sun.star.frame.XStorable</idl> interface, which is responsible for saving documents.
* The <idl>com.sun.star.view.XPrintable</idl> interface, which contains the methods for printing documents. 

=== Saving and Exporting Documents ===

{{OOo}} documents are saved directly through the document object. The <tt>store</tt> method of the <idl>com.sun.star.frame.XStorable</idl> interface is available for this purpose:

<source lang="oobas">
Doc.store()
</source>

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 <tt>storeAsURL</tt> method is used. This method is also defined in <idl>com.sun.star.frame.XStorable</idl> and can be used to define the location of the document: 

<source lang="oobas">
Dim URL As String
Dim Dummy()

Url = "file:///C:/test3.odt"
Doc.storeAsURL(URL, Dummy())
</source>

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

;<tt>hasLocation()</tt>:specifies whether the document has already been assigned a URL.
;<tt>isReadonly()</tt>:specifies whether a document has read-only protection.
;<tt>isModified()</tt>: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:

<source lang="oobas">
If (Doc.isModified) Then
  If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
    Doc.store()
  Else
    Doc.storeAsURL(URL, Dummy())
  End If
End If
</source>

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 <tt>loadComponentFromURL</tt> method, some options can also be specified in the form of a <tt>PropertyValue</tt> data field using the <tt>storeAsURL</tt> method. These determine the procedure {{OOo}} uses when saving a document. <tt>storeAsURL</tt> provides the following options:

;<tt>CharacterSet (String)</tt>:defines which set of characters a document is based on.
;<tt>FilterName (String)</tt>:specifies a special filter for the <tt>loadComponentFromURL</tt> function. The filter names available are defined in the <tt>\share\config\registry\instance\org\openoffice\office\TypeDetection.xml</tt> file.
;<tt>FilterData (String)</tt>:defines additional options for filters.
;<tt>FilterOptions (String)</tt>:defines additional options (used by old filters).
;<tt>Overwrite (Boolean)</tt>:allows a file which already exists to be overwritten without a query.
;<tt>Password (String)</tt>:transfers the password for a protected file.
;<tt>Unpacked (Boolean)</tt>:saves the document (not compressed) in sub-directories.
:The possibility to store documents in unpacked way is not currently supported, the "Unpacked" property is just ignored, see {{Bug|64364}}.

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

<source lang="oobas">
Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
' ... Initialize Doc 

Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(Url, FileProperties())
</source>

The example then saves <tt>Doc</tt> 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 <tt>Print</tt> method of the <idl>com.sun.star.view.Xprintable</idl> interface is provided for this purpose. In its simplest form, the print call is:

<source lang="oobas">
Dim Dummy()

Doc.print(Dummy())
</source>

As in the case of the <tt>loadComponentFromURL</tt> method, the Dummy parameter is a <tt>PropertyValue</tt> data field through which {{OOo}} can specify several options for printing.

=== The options of the print method ===

The <tt>print</tt> method expects a <tt>PropertyValue</tt> data field as a parameter, which reflects the settings of the print dialog of {{OOo}}: 

;<tt>CopyCount (Integer)</tt>:specifies the number of copies to be printed.
;<tt>FileName (String)</tt>:prints the document in the specified file.
;<tt>Collate (Boolean)</tt>:advises the printer to collate the pages of the copies.
;<tt>Sort (Boolean)</tt>:sorts the pages when printing out several copies (<tt>CopyCount</tt> > 1).
;<tt>Pages (String)</tt>:contains the list of the pages to be printed (syntax as specified in print dialog).
;<tt>Wait (Boolean)</tt>:if set to True the print method will return ''after'' the job is stored on the waiting list for the printer. Use this option if you want to close the document after print.

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

<source lang="oobas">
Dim Doc As Object
Dim PrintProperties(1) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
PrintProperties(1).Name="Wait"
PrintProperties(1).Value=True
Doc.print(PrintProperties())
</source>

=== Printer selection and settings ===

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

;<tt>Name (String)</tt>:specifies the name of printer.
;<tt>PaperOrientation (Enum)</tt>:specifies the paper orientation (<idl>com.sun.star.view.PaperOrientation.PORTRAIT</idl> value for portrait format, <idl>com.sun.star.view.PaperOrientation.LANDSCAPE</idl> for landscape format).
;<tt>PaperFormat (Enum)</tt>:specifies the paper format (for example, <idl>com.sun.star.view.PaperFormat.A4</idl> for DIN A4 or <idl>com.sun.star.view.PaperFormat.Letter</idl> for US letters).
;<tt>PaperSize (Size)</tt>: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 <tt>Printer</tt> property. 

<source lang="oobas">
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()
</source>

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

 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/StarDesktop}}
{{PDL1}}