Difference between revisions of "NL/Documentation/BASIC Guide/StarDesktop"

Revision as of 16:28, 28 January 2013

Programmeursgids voor BASIC

De taal van Apache OpenOffice Basic

Runtime-bibliotheek

Introductie voor de API

Werken met documenten

De StarDesktop
Opmaakprofielen en sjablonen

Tekstdocumenten

Werkbladdocumenten

Tekeningen en presentaties

Grafieken (Diagrammen)

Databases

Dialoogvensters

Formulieren

< Vorige pagina

Volgende pagina >

Twee services worden het meest gebruikt bij het werken met documenten:

De service com.sun.star.frame.Desktop, die overeenkomt met de kernservice van Apache OpenOffice. Het verschaft de functies voor het frame-object van Apache OpenOffice, waaronder alle documentvensters worden geclassificeerd. Documenten kunnen ook worden gemaakt, geopend en geïmporteerd met deze service.
De basis-functionaliteit voor de individuele documentobjecten wordt verschaft door de service com.sun.star.document.OfficeDocument. Dit verschaft de methoden voor opslaan, exporteren en afdrukken van documenten.

De service com.sun.star.frame.Desktop wordt automatisch gemaakt als Apache OpenOffice wordt gestart. Deze service kan worden benaderd door Apache OpenOffice BASIC met globale naam StarDesktop.

De meest belangrijke interface van de StarDesktop is com.sun.star.frame.XComponentLoader. Deze regelt in principe de methode loadComponentFromURL, welke verantwoordelijk is voor het maken, importeren en openen van documenten.

StarOffice 5 : De naam van het object StarDesktop dateert uit StarOffice 5, waarin alle documentvensters waren ingebed in één algemene toepassing, genaamd StarDesktop. In de huidige versie van Apache OpenOffice wordt niet langer een zichtbare StarDesktop gebruikt. De naam StarDesktop werd echter behouden voor het frame-object van Apache OpenOffice omdat het duidelijk aangeeft dat het een basaal object is voor de gehele toepassing.

Het object StarDesktop object vervangt het object Application van StarOffice 5 dat eerder werd toegepast als bronobject. Echter, anders dan het oude object Application, is StarDesktop primair verantwoordelijk voor het openen van nieuwe documenten. De residente functies in het oude object Application voor het beheren van de on-screen weergave van Apache OpenOffice (bijvoorbeeld: FullScreen,FunctionBarVisible, Height, Width, Top, Visible) worden niet langer gebruikt.

VBA : Waar het actieve document in Word toegankelijk is via Application.ActiveDocument en in Excel via Application.ActiveWorkbook, is in Apache OpenOffice de StarDesktop verantwoordelijk voor die taak. Het object voor het actieve document is in Apache OpenOffice toegankelijk via de eigenschap StarDesktop.CurrentComponent, of via ThisComponent.

ThisComponent

De globale naam ThisComponent geeft in het algemeen hetzelfde object terug als StarDesktop.CurrentComponent, met één significant voordeel. Als u uitvoert vanuit de BASIC IDE, debuggen of verkennen, dan geeft StarDesktop de BASIC IDE zelf terug. Dat is waarschijnlijk niet wat u wilt. ThisComponent geeft het laatste eerder actieve document terug.

Basisinformatie over documenten in Apache OpenOffice

Bij het werken met documenten van Apache OpenOffice is het handig om enkele basiskwesties van het beheren van documenten in Apache OpenOffice te behandelen. Dit houdt onder meer in: de manier waarop bestandsnamen worden gestructureerd voor Apache OpenOffice documenten, als ook de opmaak waarin bestanden worden opgeslagen.

Bestandsnamen in URL-notatie

Omdat Apache OpenOffice een platform-onafhankelijke toepassing is wordt URL-notatie gebruikt (die onafhankelijk is van enig besturingssysteem), zoals die is gedefinieerd in de Internet Standard RFC 1738 voor bestandsnamen. Standaard bestandsnamen die dit systeem hanteren beginnen met het voorvoegsel (prefix) file:/// gevolgd door het lokale pad. Als de bestandsnaam sub-mappen bevat, dan worden deze gescheiden door één enkele voorwaartse streep, niet door een backslash zoals gebruikelijk is onder Windows. Het volgende pad refereert aan het bestand test.odt in de map doc op de C:-schijf.

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

Apache OpenOffice verschaft de functie ConvertToUrl om lokale bestandsnamen om te zetten naar een URL. Apache OpenOffice heeft de functie ConvertFromUrl om een URL om te zetten naar een lokale bestandsnaam:

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' levert op file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  levert op (onder Windows) c:\doc\test.odt

Het voorbeeld zet een lokale bestandsnaam om naar een URL en geeft het weer in een berichtenvenster. Vervolgens zet het de URL om naar een lokale bestandsnaam en geeft ook die weer.

De Internet Standard RFC 1738, waarop dit is gebaseerd, staat gebruik toe van de tekens 0-9, a-z en A-Z. Alle andere tekens worden ingevoegd in de URLs als een escape-code (hulpcode). Om dit te doen worden zij omgezet in hun hexadecimale waarde in de UTF-8-tekenset en worden zij voorafgegaan door een percentage-teken. Een spatie in een lokale bestandsnaam, bijvoorbeeld, wordt daarom dan %20 in de URL.

XML-bestandsindeling

Documenten van Apache OpenOffice zijn gebaseerd op de bestandsindeling XML. Op XML gebaseerde bestanden kunnen worden geopend en bewerkt met andere programma's.

Compressie van bestanden

Omdat XML is gebaseerd op standaard tekstbestanden, zijn de resulterende bestanden gewoonlijk zeer groot. Apache OpenOffice comprimeert daarom de bestanden en slaat ze op als een ZIP-bestand. Door middel van een methode optie storeAsURL, kan de gebruiker de originele XML-bestanden direct opslaan. Bekijk Methode optie storeAsURL, hieronder.

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 Apache OpenOffice creates internally for its administration. The predefined _blank name is usually specified here, and this ensures that Apache OpenOffice creates a new window.

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

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)

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

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

StarOffice 5 : StarDesktop.loadComponentFromURL supersedes the Documents.Add and Documents.Open methods from the old Apache OpenOffice API.

Replacing the Content of the Document Window

The named _blank value for the Frame parameter ensures that Apache OpenOffice 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.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)

The example first opens the test.odt 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.odt file.

loadComponentFromURL Method Options

The fourth parameter of the loadComponentFromURL function is a PropertyValue data field. which provides Apache OpenOffice 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.
FilterData (String): defines additional options for filters.
FilterOptions (String): defines additional options (used by old filters).
Hidden (Boolean): value true loads the document in invisible mode.
JumpMark (String): once a document has been opened, jumps to the position defined in JumpMark.
MacroExecutionMode (Integer): indicates if document macros may be executed. Values : see com.sun.star.document.MacroExecMode
Password (String): transfers a password for a protected file.
ReadOnly (Boolean): value true loads a document in read-only mode.
UpdateDocMode (Integer): indicates how/if links will be updated. Values : see com.sun.star.document.UpdateDocMode

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

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())

The FileProperties array has two elements, one for each option used. The Filtername property defines whether Apache OpenOffice uses a Apache OpenOffice Calc text filter to open files. The FilterOptions property contains the description of the syntax of the csv file.

Creating New Documents

Apache OpenOffice 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 Apache OpenOffice 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.
The com.sun.star.view.XPrintable interface, which contains the methods for printing documents.

Saving and Exporting Documents

Apache OpenOffice 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.odt"
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 Apache OpenOffice 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.
FilterData (String): defines additional options for filters.
FilterOptions (String): defines additional options (used by old 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 possibility to store documents in unpacked way is not currently supported, the "Unpacked" property is just ignored, see Issue 64364 .

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.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(Url, FileProperties())

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 Apache OpenOffice 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 Apache OpenOffice:

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).
Wait (Boolean): 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 Pages option:

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())

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.

Content on this page is licensed under the Public Documentation License (PDL).

@@ Line 26: / Line 26: @@
 De globale naam <tt>ThisComponent</tt> geeft in het algemeen hetzelfde object terug als <tt>StarDesktop.CurrentComponent</tt>, met één significant voordeel. Als u uitvoert vanuit de BASIC IDE, debuggen of verkennen, dan geeft <tt>StarDesktop</tt> de BASIC IDE zelf terug. Dat is waarschijnlijk niet wat u wilt. <tt>ThisComponent</tt> geeft het laatste eerder actieve document terug.
-== Basic Information about Documents in {{OOo}} ==
+== Basisinformatie over documenten 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.
+Bij het werken met documenten van {{OOo}} is het handig om enkele basiskwesties van het beheren van documenten in {{OOo}} te behandelen. Dit houdt onder meer in: de manier waarop bestandsnamen worden gestructureerd voor {{OOo}} documenten, als ook de opmaak waarin bestanden worden opgeslagen.
-=== File Names in URL Notation ===
+=== Bestandsnamen in URL-notatie ===
-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.
+Omdat {{OOo}} een platform-onafhankelijke toepassing is wordt URL-notatie gebruikt (die onafhankelijk is van enig besturingssysteem), zoals die is gedefinieerd in de Internet Standard RFC 1738 voor bestandsnamen. Standaard bestandsnamen die dit systeem hanteren beginnen met het voorvoegsel (prefix) <tt>file:///</tt> gevolgd door het lokale pad. Als de bestandsnaam sub-mappen bevat, dan worden deze gescheiden door één enkele voorwaartse streep, niet door een backslash zoals gebruikelijk is onder Windows. Het volgende pad refereert aan het bestand <tt>test.odt</tt> in de map doc op de C:-schijf.
   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:
+{{OOo}} verschaft de functie <tt>ConvertToUrl</tt> om lokale bestandsnamen om te zetten naar een URL. {{OOo}} heeft de functie <tt>ConvertFromUrl</tt> om een URL om te zetten naar een lokale bestandsnaam:
 <source lang="oobas">
 MsgBox ConvertToUrl("C:\doc\test.odt")
-   ' supplies file:///C:/doc/test.odt
+   ' levert op file:///C:/doc/test.odt
 MsgBox ConvertFromUrl("file:///C:/doc/test.odt")
-   '  supplies (under Windows) c:\doc\test.odt
+   '  levert op (onder 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.
+Het voorbeeld zet een lokale bestandsnaam om naar een URL en geeft het weer in een berichtenvenster. Vervolgens zet het de URL om naar een lokale bestandsnaam en geeft ook die weer.
-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.
+De Internet Standard RFC 1738, waarop dit is gebaseerd, staat gebruik toe van de tekens <tt>0-9</tt>, <tt>a-z</tt> en <tt>A-Z</tt>. Alle andere tekens worden ingevoegd in de URLs als een escape-code (hulpcode). Om dit te doen worden zij omgezet in hun hexadecimale waarde in de UTF-8-tekenset en worden zij voorafgegaan door een percentage-teken. Een spatie in een lokale bestandsnaam, bijvoorbeeld,  wordt daarom dan <tt>%20</tt> in de URL.
-=== XML File Format ===
+=== XML-bestandsindeling ===
-{{OOo}} documents are based on the XML file format.  XML-based files can be opened and edited with other programs.
+Documenten van {{OOo}} zijn gebaseerd op de bestandsindeling XML. Op XML gebaseerde bestanden kunnen worden geopend en bewerkt met andere programma's.
-=== Compression of Files ===
+=== Compressie van bestanden ===
-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.
+Omdat XML is gebaseerd op standaard tekstbestanden, zijn de resulterende bestanden gewoonlijk zeer groot. {{OOo}} comprimeert daarom de bestanden en slaat ze op als een ZIP-bestand. Door middel van een methode optie <tt>storeAsURL</tt>, kan de gebruiker de originele XML-bestanden direct opslaan. Bekijk [[NL/Documentation/BASIC Guide/StarDesktop#storeAsURL Method Options|Methode optie storeAsURL]], hieronder.
 == Creating, Opening and Importing Documents ==