The Model: XModel

XModel is the primary interface that distinguishes a component as a document, as opposed to the OOo Basic IDE or the included help pages. Objects that implement the interface com.sun.star.frame.XModel represent a component created from a URL. OOo document objects may be controlled by a controller, which is also considered a view of the document. The XModel interface defines the object methods in Table 7 .

Table 7: Object methods defined by the interface com.sun.star.frame.XModel.

Object Method	Description
getURL()	URL of the document returned as a String.
getArgs()	Return a copy of the com.sun.star.document.MediaDescriptor for this model (document).
lockControllers()	Prevent some display updates-macros may run faster.
unlockControllers()	Call this once for each call to lockControllers().
hasControllersLocked()	Is there at least one lock remaining?
getCurrentController()	The controller that currently controls this model.
getCurrentSelection()	Current selection on the current controller.

The object method getArgs() returns an object that supports the service com.sun.star.document.MediaDescriptor. The MediaDescriptor service defines multiple properties, all of them optional, which describe how the document was loaded. The MediaDescriptor service can also be accessed as an array of properties (see Listing 14 and Figure 8 ).

Figure 8: Properties returned by the getArgs() object method.

Listing 14: printDocumentArgs is found in the Generic module in this chapter's source code files as SC12.sxw.

 Sub printDocumentArgs()   REM This says to ignore any lines that cause an error.   REM Obtaining a value may cause an error, but that is   REM not a problem. It just prevents a value from being printed.   On Error Resume Next   Dim vArgs 'Media descriptor as an array of com.sun.star.beans.PropertyValue   Dim s$    'Display string   Dim i%    'Index variable   REM Obtain the media descriptor. It turns out that this   REM can be represented as an array of PropertyValue services.   vArgs = ThisComponent.getArgs()   For i = 0 To UBound(vArgs)       'For each property     s = s & vArgs(i).Name & " = "  'Add the property name and an equals sign     s = s & vArgs(i).Value         'Obtaining the value may fail!     s = s & CHR$(10)               'Add a new-line character   Next   MsgBox s, 0, "Args" End Sub 

 

A text file is not a standard OOo Writer file, but rather, a simple file that has typically been created by a simple editor such as Notepad. Text files contain no information that identify the character set that was used, or how lines are terminated . Text files usually use the file extension TXT. When a text file is opened, OOo displays a dialog and asks questions about the file so that it knows how the text file is encoded. I was asked how to load a text file using a macro, avoiding the dialog and explicitly specifying the import values. Although I was able to correctly determine the import filter name, I had no idea how to specify the required filter options. I had no idea, that is, until I found thegetArgs() object method. Figure 8 shows the arguments for an imported text file. The FilterName property indicates the name of the import filter, and the FilterOptions property indicates the filter options that were used to open the file. Using these properties with the desktop object method LoadComponentFromUrl(), the file is correctly imported and the dialog is not displayed. Table 8 contains a list of the properties that may be returned from the getArgs() object method. The OOo API Web site contains a few more properties, but they are obscure or deprecated.

Table 8: Object properties defined by the service MediaDescriptor.

Property	Description
AsTemplate	Document was loaded as a template.
Author	Author of this document version; this is for versioning.
CharacterSet	Document character set for single-byte characters .
Comment	Comment on the current document version; this is for versioning.
DocumentTitle	If the document title is specified, it is included here.
FilterName	Filter used to import or save this document.
FilterOptions	Filter used to import this document.
FilterData	Additional import properties if the FilterOptions string is not sufficient.
Hidden	If the Hidden argument is specified during load, it is included here.
InputStream	If the InputStream is specified during load, it is included here.
InteractionHandler	Exception handler if an error occurs during import.
JumpMark	Jump to this marked position after loading the document.
MediaType	MIME type of this document.
OpenNewView	Opens a new view for an already loaded document, rather than just opening the document twice. In other words, request two views of the same data.
Overwrite	Overwrite any existing file on save.
Password	Password for loading or storing the document.
Preview	Document loaded in preview mode; optimizes for preview-only use.
ReadOnly	Document opened as read-only; controller will not change the document.
StartPresentation	Immediately after loading an Impress document, start the presentation.
Referer	URL of document referrer-for example, if opened by clicking an HTTP link.
RepairPackage	Open the document in repair mode.
StatusIndicator	If a status indicator was specified when the document was loaded, it is included here.
Unpacked	If True, an OOo document is stored as a folder rather than a ZIP file.
URL	URL of the document.
Version	Current document version, if versioning is supported.
ViewData	The view data to use.
ViewId	The ID of the initial view.
MacroExecutionMode	Specifies how macros are treated when the document is loaded.

The properties shown in Table 8 are especially useful when you want to write a macro to import a document but you aren't certain what values to use during the import. First, import the document manually and then check the values in the media descriptor. You can use the values in the media descriptor in your macro while importing documents.