Apache OpenOffice Wiki - User contributions [en]

Renaissance:The Roadmap

2009-10-23T13:59:17Z

Cking: Changed "fits very good to" to "fits very well with".

{{User Experience Community}}
=Roadmap 2009=

== Goal Towards OpenOffice.org 3.3 ==
Main focus towards OpenOffice.org 3.3 will be on Impress. Goal is to improve the most common interactions, to introduce direct object manipulation and to fix related UX issues[[Renaissance:Analyze | UX issues]]. This clean up based on the current UI will help us working towards a new interface and fits very well with OOo's iterative development process.

== Chart ==

[[Image:Renaissance-roadmap.png]]
<br>October 2009

Documentation/DevGuide/FirstSteps/Using Services

2008-10-07T22:03:22Z

Cking: Back to multiple-inheritance interfaces

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services
|NextPage=Documentation/DevGuide/FirstSteps/Example: Working with a Spreadsheet Document
}}
{{DISPLAYTITLE:Using Services}}
The concepts of interfaces and services were introduced for the following reasons:

'''Interfaces and services separate specification from implementation'''
: The specification of an interface or service is ''abstract'', that is, it does not define how objects supporting a certain functionality do this ''internally''. Through the abstract specification of the {{OOo}} API, it is possible to pull the implementation out from under the API and install a different implementation if required.

'''Service names allow to create instances by specification name, not by class names'''
: In Java or C++ you use the new operator to create a class instance. This approach is restricted: the class you get is hard-coded. You cannot later on exchange it by another class without editing the code. The concept of services solves this. The central object factory in {{OOo}}, the global service manager, is asked to create an object that can be used for a certain purpose without defining its internal implementation. This is possible because a service can be ordered from the factory by its ''service name'' and the factory decides which service implementation it returns. Which implementation you get makes no difference, you only use the well-defined interface of the service.

===Interfaces===
Abstract interfaces are more reusable if they are fine-grained, i.e., if they are small and describe only a single aspect of an object. To describe the many aspects of an object, objects can implement more than one of these fine-grained interfaces. Being able to implementation multiple interfaces allows similar aspects of similar objects to be accessed with the same code. For example, many objects support text: text may be found in the body of a document, in text frames, in headers and footers, footnotes, table cells, and in drawing shapes. These objects all support the same interface, so a procedure can use, for example, getText() to retrieve text from ''any'' of these objects.

Services, interfaces, and methods are illustrated in the figure below for the old-style service <idl>com.sun.star.text.TextDocument</idl>, shown using [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] notation. In this figure, services are shown on the left side. The arrow between services indicates that one service provided by the upper (arrowhead) service are inherited by the lower service. Interfaces exported by these services are shown on the right. All interface names in the {{OOo}} API start with an X, so as to be distinguishable from the names of other entities. Each interface contains methods, which are listed beneath the interface.

[[Image:TextDocumentWithMethods.png|none|thumb|450px|Figure. TextDocument inherits the methods of OfficeDocument.]]

A <code>TextDocument</code> object provides the <idl>com.sun.star.text.TextDocument</idl> service, which implements the interfaces, <code>XTextDocument</code>, <code>XSearchable</code>, and <code>XRefreshable</code>. These interfaces provide, for example, the methods <code>getText()</code>, for adding text to a document, and <code>findAll()</code>, for searching the document.

As indicated by the arrow, the <idl>com.sun.star.text.TextDocument</idl> service also inherits all the interfaces provided by the <idl>com.sun.star.document.OfficeDocument</idl> service, so these interfaces are also provided to a <code>TextDocument</code> object. These interfaces handle tasks common to the {{OOo}} applications: printing, <code>XPrintable</code>; storing, <code>XStorable</code>; modifying, <code>XModifiable</code>; and model handling, <code>XModel</code>.

The interfaces shown in the figure are only the mandatory interfaces of a <code>TextDocument</code> object. A <code>TextDocument</code> has optional properties and interfaces, among them the properties <code>CharacterCount</code>, <code>ParagraphCount</code> and <code>WordCount</code>, and the interface <code>XPropertySet</code>, which must be supported if properties are present at all. The implementation of the <code>TextDocument</code> service in {{OOo}} supports both required and all optional interfaces as well. The usage of a <code>TextDocument</code> is described thoroughly in [[Documentation/DevGuide/Text/Text Documents|Text Documents]].

C++ and Java require that the interface name be provided when accessing a method. An old-style service may provide several interfaces to keep track of. New-style services are easier to use because, since they have just one interface, the multiple-inheritance interface, all the methods are accessed through the same interface.

===Using Interfaces===


The fact that every UNO object must be accessed through its interfaces has an effect in languages like Java and C++, where the compiler needs the correct type of an object reference before you can call a method from it. In Java or C++, you normally just cast an object before you access an interface it implements. When working with UNO objects this is different: You must ask the UNO environment to get the appropriate reference for you whenever you want to access methods of an interface which your object supports, but your compiler does not yet know about. Only then you can cast it safely.

The Java UNO environment has a method <code>queryInterface()</code> for this purpose. It looks complicated at first sight, but once you understand that <code>queryInterface()</code> is about safe casting of UNO types across process boundaries, you will soon get used to it. Take a look at the second example FirstLoadComponent.java (in the sample directory, if you have installed the SDK on your computer), where a new Desktop object is created and, afterwards, the <idlm>queryInterface</idlm>() method is used to get the <idls>com.sun.star.frame.XComponentLoader</idls> interface.

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);

XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

We asked the service manager to create a <idl>com.sun.star.frame.Desktop</idl> using its factory method createInstanceWithContext(). This method is defined to return a Java Object type, which should not surprise you—after all the factory must be able to return any type:

<source lang="java">
java.lang.Object createInstanceWithContext(String serviceName, XComponentContext context)
</source>

The object we receive is a <idl>com.sun.star.frame.Desktop</idl> service. The point is, while we know that the object we ordered at the factory is a DesktopUnoUrlResolver and exports among other interfaces the interface <code>XComponentLoader</code>, the compiler does ''not''. Therefore, we have to use the UNO runtime environment to ask or ''query'' for the interface <code>XComponentLoader</code>, since we want to use the <code>loadComponentFromURL()</code> method on this interface. The method <code>queryInterface()</code> makes sure we get a reference that can be cast to the needed interface type, no matter if the target object is a local or a remote object. There are two <code>queryInterface</code> definitions in the Java UNO language binding:

<source lang="java">
java.lang.Object UnoRuntime.queryInterface(java.lang.Class targetInterface, Object sourceObject)
java.lang.Object UnoRuntime.queryInterface(com.sun.star.uno.Type targetInterface, Object sourceObject)
</source>

Since <code>UnoRuntime.queryInterface()</code> is specified to return a java.lang.Object just like the factory method <code>createInstanceWithContext()</code>, we still must explicitly cast our interface reference to the needed type. The difference is that after <code>queryInterface()</code> we can safely cast the object to our interface type and, most important, that the reference will now work even with an object in another process. Here is the <code>queryInterface()</code> call, explained step by step:

<source lang="java">
XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

<code>XComponentLoader</code> is the interface we want to use, so we define a <code>XComponentLoader</code> variable named <code>xComponentLoader</code> (lower x) to store the interface we expect from <code>queryInterface</code>.
Then we query our desktop object for the <code>XComponentLoader</code> interface, passing in <code>XComponentLoader.class</code> as target interface and desktop as source object. Finally we cast the outcome to <code>XComponentLoader</code> and assign the resulting reference to our variable <code>xComponentLoader</code>.
If the source object does not support the interface we are querying for, <code>queryInterface()</code> will return null.

In Java, this call to <code>queryInterface()</code> is necessary whenever you have a reference to an object which is known to support an interface that you need, but you do not have the proper reference type yet. Fortunately, you are not only allowed to <code>queryInterface()</code> from <code>java.lang.Object</code> source types, but you may also query an interface from another interface reference, like this:

<source lang="java">
// loading a blank spreadsheet document gives us its XComponent interface:
XComponent xComponent = xComponentLoader.loadComponentFromURL(
"private:factory/scalc", "_blank", 0, loadProps);

// now we query the interface XSpreadsheetDocument from xComponent
XSpreadsheetDocument xSpreadsheetDocument = (XSpreadsheetDocument)UnoRuntime.queryInterface(
XSpreadsheetDocument.class, xComponent);
</source>

Furthermore, if a method is defined in such a way that it already returns an interface type, you do not need to query the interface, but you can use its methods right away. In the snippet above, the method <code>loadComponentFromURL</code> is specified to return an <idl>com.sun.star.lang.XComponent</idl> interface, so you may call the <code>XComponent</code> methods <code>addEventListener()</code> and <code>removeEventListener()</code> directly at the <code>xComponent</code> variable, if you want to be notified that the document is being closed.
The corresponding step in C++ is done by a <code>Reference<></code> template that takes the source instance as parameter:

<source lang="java">
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
</source>

In {{OOo}} Basic, querying for interfaces is not necessary; the Basic runtime engine takes care of that internally.
With the proliferation of multiple-inheritance interfaces in the {{OOo}} API, there will be less of a demand to explicitly query for specific interfaces in Java or C++. For example, with the hypothetical interfaces

<source lang="idl">
interface XBase1 { void fun1();
};
interface XBase2 {
void fun2();
};
interface XBoth { // inherits from both XBase1 and XBase2
interface XBase1;
interface XBase2;
};
interface XFactory {
XBoth getBoth();};
</source>

you can directly call both <code>fun1()</code> and <code>fun2()</code> on a reference obtained through <code>XFactory.getBoth()</code>, without querying for either <code>XBase1</code> or <code>XBase2</code>.

===Using Properties===

An object must offer its properties through interfaces that allow you to work with properties. The most basic form of these interfaces is the interface <idl>com.sun.star.beans.XPropertySet</idl>. There are other interfaces for properties, such as <idl>com.sun.star.beans.XMultiPropertySet</idl>, that gets and sets a multitude of properties with a single method call. The <code>XPropertySet</code> is always supported when properties are present in a service.

In <code>XPropertySet</code>, two methods carry out the property access, which are defined in Java as follows:

<source lang="java">
void setPropertyValue(String propertyName, Object propertyValue)
Object getPropertyValue(String propertyName)
</source>

In the FirstLoadComponent example, the <code>XPropertySet</code> interface was used to set the CellStyle property at a cell object. The cell object was a <code>com.sun.star.sheet.SheetCell</code> and therefore supports also the <code>com.sun.star.table.CellProperties</code> service which had a property <code>CellStyle</code>. The following code explains how this property was set:

<source lang="java">
// query the XPropertySet interface from cell object
XPropertySet xCellProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xCell);

// set the CellStyle property
xCellProps.setPropertyValue("CellStyle", "Result");
</source>

You are now ready to start working with a {{PRODUCTNAME}} document.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Talk:Documentation/DevGuide/FirstSteps/Using Services

2008-10-07T21:35:53Z

Cking:

I [http://msdn.microsoft.com/en-us/library/ms973861.aspx read] that "multiple-inheritance interfaces" is more properly called "multiple interface implementation", so I made the change.--[[User:Cking|Cking]] 21:22, 5 October 2008 (CEST)

For old style services, "multiple interface implementation" indeed would be more accurate. However, old style services (where a service implements multiple, unrelated interfaces) are deprecated, and should be superseded by new style services (where a service implements just one interface, but that interface is typically a multiple-inheritance interface that in turn inherits from multiple, otherwise unrelated interfaces). So, I am undecided whether or not [http://wiki.services.openoffice.org/w/index.php?title=Documentation%2FDevGuide%2FFirstSteps%2FUsing_Services&diff=94529&oldid=94472 Created "Multiple Interface Implementation" section out of what was on the page] is an improvement.--[[User:Sb|Sb]] 13:49, 7 October 2008 (CEST)

Thanks, again, for commenting. I think I should go back with "multiple-inheritance interfaces" to be consistent with the rest of the guide. Perhaps a definition/discussion of that term should be added earlier in the guide, so that, whether or not we like the term, we all know what it means. The "Programmer's Guide" needs to make sense not only to C++ and Java folks, but also to Basic programmers, as well. (My background is Visual Basic, which, until VB.net, hasn't used interfaces.)--[[User:Cking|Cking]] 23:35, 7 October 2008 (CEST)

Talk:Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-07T21:01:33Z

Cking:

I don't think the term "multiple-inheritance interfaces" makes sense. Objects can inherit, but how can an interface inherit anything? Perhaps a better term would be "nested interfaces": these could be defined as interfaces that, besides their own methods, include all the methods of other interfaces. Java doesn't support multiple-inheritance objects, so I doubt that OOo does. I'll put "nested interface" into the section on interfaces to see how it looks.

Also, I've called the single interface of a new-style service a composite interface.
--[[User:Cking|Cking]] 20:17, 6 October 2008 (CEST)

At least in UNO (and also in Java, and, equating abstract classes with interfaces, also in C++), interfaces ''can'' inherit from (multiple) other interfaces. “Multiple inheritance” is an established term for this. Consequently, I undid most of your recent modifications.--[[User:Sb|Sb]] 15:43, 7 October 2008 (CEST)

Thanks for looking at it. I've had a hard time understanding interfaces. I'll post to the mailing list first, next time.--[[User:Cking|Cking]] 23:01, 7 October 2008 (CEST)

Documentation/BASIC Guide/StarDesktop

2008-10-06T22:25:22Z

Cking:

{{DISPLAYTITLE:The StarDesktop}}
{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Documents
|NextPage=Documentation/BASIC Guide/Templates
|docs=block
}}

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.

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. Unlike the old <tt>Application</tt> object however it 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/Note|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 ==
<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 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 <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. Alternatively, <tt>_hidden</tt> can also be specified, and this ensures that the corresponding document is loaded but remains invisible.

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>text.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/Note|<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> and <tt>_hidden</tt> values for the <tt>Frame</tt> parameter ensure 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>FilterOptions (String)</tt>:defines additional options for filters.
;<tt>JumpMark (String)</tt>:once a document has been opened, jumps to the position defined in JumpMark.
;<tt>Password (String)</tt>:transfers a password for a protected file.
;<tt>ReadOnly (Boolean)</tt>:loads a read-only document.

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(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 (OpenOffice.org Calc)"

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

The <tt>FileProperties</tt> data field covers precisely one value because it records one option. The <tt>Filtername</tt> property defines whether {{OOo}} uses a {{OOo}} Calc text filter to open files.

=== 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>FilterOptions (String)</tt>:defines additional options for 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 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(sUrl, mFileProperties())
</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).

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(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
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.

{{PDL1}}

Documentation/BASIC Guide/API Intro

2008-10-06T21:41:25Z

Cking:

{{DISPLAYTITLE:Introduction to the {{OOo}} API}}
{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Other Functions (Runtime Library)
|NextPage=Documentation/BASIC Guide/UNO
|api=block
}}

{{OOo}} objects and methods, such as paragraphs, spreadsheets, and fonts, are accessible to {{OOo}} Basic through the {{OOo}} application programming interface, or API. Through the API, for example, documents can be created, opened, modified and printed. The API can be used not only by {{OOo}} Basic, but also by other programming languages, such as Java and C++. The interface between the API and various programming languages is provided by something called '''Universal Network Objects''' (UNO).

This chapter provides a background on the API. Building on this background, the following chapters will show how the API can be used to make {{OOo}} do what you want it to do.

{{PDL1}}

Talk:Documentation/DevGuide/OfficeDev/Frames

2008-10-06T20:09:36Z

Cking: New page: I wonder what a frame does. Does it just pass a window reference on to the controller? Or, perhaps the controller says "Here's what needs to be drawn," and the frame issues the drawing c...

I wonder what a frame does. Does it just pass a window reference on to the controller? Or, perhaps the controller says "Here's what needs to be drawn," and the frame issues the drawing commands. If that's what happens, perhaps the controller is operating-system-independent, and the frame is what gets changed for different operating systems.--[[User:Cking|Cking]] 22:09, 6 October 2008 (CEST)

Documentation/DevGuide/OfficeDev/Controllers

2008-10-06T19:11:34Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevFramework=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Frames
|NextPage=Documentation/DevGuide/OfficeDev/Windows
}}
{{DISPLAYTITLE:Controllers}}

Controllers in {{PRODUCTNAME}} are between a frame and document model. This is their basic role as expressed in <idl>com.sun.star.frame.XController</idl>, which has methods <code>getModel()</code> and <code>getFrame()</code>. The method <code>getFrame()</code> provides the frame that the controller is attached to. The method <code>getModel()</code> returns a document model, but it may return an empty reference if the component does not have a model.

Usually the controller objects support additional interfaces specific to the document type they control, such as <idl>com.sun.star.sheet.XSpreadsheetView</idl> for Calc document controllers or <idl>com.sun.star.text.XTextViewCursorSupplier</idl> for Writer document controllers.

[[Image:FCMController.png|none|thumb|400px|Controller with Model and Frame]]

A single document model can be controlled simultaneously by several controller instances, each associated with a separate frame. Multiple controllers and frames are created by {{PRODUCTNAME}} when the user clicks '''Window - New Window'''.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment

2008-10-06T18:58:33Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Office Development
|NextPage=Documentation/DevGuide/OfficeDev/Desktop Environment
}}
{{DISPLAYTITLE:{{PRODUCTNAME}} Application Environment}}
The {{PRODUCTNAME}} application environment is made up of the ''desktop environment'' and the ''framework API''.

[[Image:AppEnvironment.png|none|frame|The {{PRODUCTNAME}} Application Environment]]

The desktop environment consists of the desktop service and auxiliary objects. The desktop environment's functions are carried out by the framework API. The framework API has two parts: the ''component framework'' and the ''dispatch framework''. The component framework follows a special Frame-Controller-Model paradigm to manage components viewable in {{PRODUCTNAME}}. The dispatch framework handles command requests sent by the GUI.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Office Development

2008-10-06T18:55:20Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/AdvUNO/UNO Design Patterns and Coding Styles
|NextPage=Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment
}}
{{DISPLAYTITLE:Office Development}}
This chapter describes the application environment of the {{PRODUCTNAME}} application. It assumes that you have read the chapter [[Documentation/DevGuide/FirstSteps/First Steps|First Steps]], and that you are able to connect to the office and load documents.

In most cases, users use the functionality of {{PRODUCTNAME}} by opening and modifying documents. The interfaces and services common to all document types and how documents are embedded in the surrounding application environment are discussed.

It is also possible to extend the functionality of {{PRODUCTNAME}} by replacing the services mentioned here by intercepting the communication between objects or by creating your own document type and integrating it into the desktop environment. All these things are discussed in this chapter.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-06T18:32:24Z

Cking: Removed inheritance from interface section.

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Working with Objects
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services]]
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
===Objects===

In UNO, an ''object'' is a software artifact that has methods that you can call and attributes that you can get and set. Exactly which methods and attributes an object offers is specified by the set of interfaces it supports.

===Interfaces===

An ''interface'' specifies a set of attributes and methods that together define one single aspect of an object. For instance, the interface <idl>com.sun.star.resource.XResourceBundle</idl> specifies the attribute <code>Parent</code> and the methods <code>getLocale()</code> and <code>getDirectElement()</code>.

<source lang="idl">
module com { module sun { module star { module resource { interfaceXResourceBundle: com::sun::star::container::XNameAccess {
[attribute] XResourceBundle Parent;
com::sun::star::lang::Locale getLocale();
any getDirectElement([in] string key);
};
}; }; }; };
</source>

To allow for reuse of such interface specifications, one interface can include another. For example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>. The ability to create such nested, composite interfaces was introduced in {{OOo2.x}}.

Strictly speaking, interface attributes are not needed in UNO. Each attribute could also be expressed as a combination of one method to get the attribute's value, and another method to set it (or just one method to get the value for a read-only attribute). However, there are at least two good reasons for the inclusion of interface attributes in UNO: First, the need for such combinations of getting and setting a value seems to be widespread enough to warrant extra support. Second, with attributes, a designer of an interface can better express nuances among the different features of an object. Attributes can be used for those features that are not considered integral or structural parts of an object, while explicit methods are reserved to access the core features.
Historically, a UNO object typically supported a set of many independent interfaces, corresponding to its many different aspects. With composite interfaces, there is less need for this, as an object may now support just one interface that includes all the other interfaces that make up the object’s various aspects.

===Services===

Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, the underlying concepts have been made cleaner. Unfortunately, this leaves two different meanings for the term “service” within UNO. In the following, we will use the term "new-style service" to denote an entity that conforms to the clarified, {{PRODUCTNAME}}-{{OOo2.x}} service concept, while we use "old-style service" to denote an entity that only conforms to the historical, more vague concept. To make matters even more complicated, the term “service” is often used with still different meanings in contexts outside UNO.

Although technically there should no longer be any need for old-style services, the {{PRODUCTNAME}} API still uses them extensively to remain backwards compatible. Therefore, be prepared to encounter uses of both service concepts in parallel when working with the {{PRODUCTNAME}} API.

A ''new-style service'' is of the form

<source lang="idl">
module com { module sun { module star { module bridge {
serviceUnoUrlResolver: XUnoUrlResolver;
}; }; }; };
</source>

and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) will be available under a certain service name (e.g., "com.sun.star.bridge.UnoUrlResolver") at a component context’s service manager. A new-style service has the feature that all of the interfaces, methods, and properties needed to define an object have been combined into a single, "composite interface". (Formally, new-style services are called “single-interface–based services.”)

The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].

An ''old-style service'' (formally called an “accumulation-based service”) is of the form

<source lang="idl">
module com { module sun { module star { module frame {serviceDesktop {
service Frame;
interface XDesktop;
interface XComponentLoader;
interface com::sun::star::document::XEventBroadcaster;
};
}; }; }; };
</source>

and is used to specify any of the following:

* The general contract is that, if an object is documented to support a certain old-style service, then you can expect that object to support all interfaces exported by the service itself and any inherited services. For example, the method <idlml>com.sun.star.frame.XFrames:queryFrames</idlml> returns a sequence of objects that should all support the old-style service <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
* Additionally, an old-style service may specify one or more properties, as in

<source lang="idl">
module com { module sun { module star { module frame {service Frame {
interface com::sun::star::frame::XFrame;
interface com::sun::star::frame::XDispatchProvider;
// ...
[property] string Title;
[property, optional] XDispatchRecorderSupplier RecorderSupplier;
// ...
};
}; }; }; };
</source>

: Properties, which are explained in detail in the following section, are similar to interface attributes, in that they describe additional features of an object. The main difference is that interface attributes can be accessed directly, while the properties of an old-style service are typically accessed via generic interfaces like <idl>com.sun.star.beans.XPropertySet</idl>. Often, interface attributes are used to represent integral features of an object, while properties represent additional, more volatile features.

* Some old-style services are intended to be available at a component context’s service manager. For example, the service <idl>com.sun.star.frame.Desktop</idl> can be instantiated at a component context’s service manager under its service name "com.sun.star.frame.Desktop". (The problem is that you cannot tell whether a given old-style service is intended to be available at a component context; using a new-style service instead makes that intent explicit.)

* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)

* Yet other old-style services only list properties, and do not export any interfaces at all. Instead of specifying the interfaces supported by certain objects, as the other kinds of old-style services do, such services are used to document a set of related properties. For example, the service <idl>com.sun.star.document.MediaDescriptor</idl> lists all the properties that can be passed to <idlml>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlml>.

A ''property'' is a feature of an object which is typically not considered an integral or structural part of the object and therefore is handled through generic <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> interface to be prepared to handle all kinds of properties. Typical examples are properties for character or paragraph formatting. With properties, you can set multiple features of an object through a single call to <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Talk:Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-06T18:17:50Z

Cking: New page: I don't think the term "multiple-inheritance interfaces" makes sense. Objects can inherit, but how can an interface inherit anything? Perhaps a better term would be "nested interfaces": ...

Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-06T18:05:34Z

Cking: Called the new-style service interface a "composite interface".

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Working with Objects
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services]]
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
===Objects===

In UNO, an ''object'' is a software artifact that has methods that you can call and attributes that you can get and set. Exactly which methods and attributes an object offers is specified by the set of interfaces it supports.

===Interfaces===

An ''interface'' specifies a set of attributes and methods that together define one single aspect of an object. For instance, the interface <idl>com.sun.star.resource.XResourceBundle</idl> specifies the attribute <code>Parent</code> and the methods <code>getLocale()</code> and <code>getDirectElement()</code>.

<source lang="idl">
module com { module sun { module star { module resource { interfaceXResourceBundle: com::sun::star::container::XNameAccess {
[attribute] XResourceBundle Parent;
com::sun::star::lang::Locale getLocale();
any getDirectElement([in] string key);
};
}; }; }; };
</source>

To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>). Multiple inheritance, the ability to inherit more than one interface, was introduced in {{PRODUCTNAME}} {{OOo2.x}}.

Strictly speaking, interface attributes are not needed in UNO. Each attribute could also be expressed as a combination of one method to get the attribute's value, and another method to set it (or just one method to get the value for a read-only attribute). However, there are at least two good reasons for the inclusion of interface attributes in UNO: First, the need for such combinations of getting and setting a value seems to be widespread enough to warrant extra support. Second, with attributes, a designer of an interface can better express nuances among the different features of an object. Attributes can be used for those features that are not considered integral or structural parts of an object, while explicit methods are reserved to access the core features.
Historically, a UNO object typically supported a set of many independent interfaces, corresponding to its many different aspects. With multiple-inheritance interfaces, there is less need for this, as an object may now support just one interface that inherits from all the other interfaces that make up the object’s various aspects.

===Services===

Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, the underlying concepts have been made cleaner. Unfortunately, this leaves two different meanings for the term “service” within UNO. In the following, we will use the term "new-style service" to denote an entity that conforms to the clarified, {{PRODUCTNAME}}-{{OOo2.x}} service concept, while we use "old-style service" to denote an entity that only conforms to the historical, more vague concept. To make matters even more complicated, the term “service” is often used with still different meanings in contexts outside UNO.

Although technically there should no longer be any need for old-style services, the {{PRODUCTNAME}} API still uses them extensively to remain backwards compatible. Therefore, be prepared to encounter uses of both service concepts in parallel when working with the {{PRODUCTNAME}} API.

A ''new-style service'' is of the form

<source lang="idl">
module com { module sun { module star { module bridge {
serviceUnoUrlResolver: XUnoUrlResolver;
}; }; }; };
</source>

and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) will be available under a certain service name (e.g., "com.sun.star.bridge.UnoUrlResolver") at a component context’s service manager. A new-style service has the feature that all of the interfaces, methods, and properties needed to define an object have been combined into a single, "composite interface". (Formally, new-style services are called “single-interface–based services.”)

The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].

An ''old-style service'' (formally called an “accumulation-based service”) is of the form

<source lang="idl">
module com { module sun { module star { module frame {serviceDesktop {
service Frame;
interface XDesktop;
interface XComponentLoader;
interface com::sun::star::document::XEventBroadcaster;
};
}; }; }; };
</source>

and is used to specify any of the following:

* The general contract is that, if an object is documented to support a certain old-style service, then you can expect that object to support all interfaces exported by the service itself and any inherited services. For example, the method <idlml>com.sun.star.frame.XFrames:queryFrames</idlml> returns a sequence of objects that should all support the old-style service <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
* Additionally, an old-style service may specify one or more properties, as in

<source lang="idl">
module com { module sun { module star { module frame {service Frame {
interface com::sun::star::frame::XFrame;
interface com::sun::star::frame::XDispatchProvider;
// ...
[property] string Title;
[property, optional] XDispatchRecorderSupplier RecorderSupplier;
// ...
};
}; }; }; };
</source>

: Properties, which are explained in detail in the following section, are similar to interface attributes, in that they describe additional features of an object. The main difference is that interface attributes can be accessed directly, while the properties of an old-style service are typically accessed via generic interfaces like <idl>com.sun.star.beans.XPropertySet</idl>. Often, interface attributes are used to represent integral features of an object, while properties represent additional, more volatile features.

* Some old-style services are intended to be available at a component context’s service manager. For example, the service <idl>com.sun.star.frame.Desktop</idl> can be instantiated at a component context’s service manager under its service name "com.sun.star.frame.Desktop". (The problem is that you cannot tell whether a given old-style service is intended to be available at a component context; using a new-style service instead makes that intent explicit.)

* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)

* Yet other old-style services only list properties, and do not export any interfaces at all. Instead of specifying the interfaces supported by certain objects, as the other kinds of old-style services do, such services are used to document a set of related properties. For example, the service <idl>com.sun.star.document.MediaDescriptor</idl> lists all the properties that can be passed to <idlml>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlml>.

A ''property'' is a feature of an object which is typically not considered an integral or structural part of the object and therefore is handled through generic <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> interface to be prepared to handle all kinds of properties. Typical examples are properties for character or paragraph formatting. With properties, you can set multiple features of an object through a single call to <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Using Services

2008-10-05T23:58:26Z

Cking: Added paragraph about new-style services having just 1 interface to mess with.

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services
|NextPage=Documentation/DevGuide/FirstSteps/Example: Working with a Spreadsheet Document
}}
{{DISPLAYTITLE:Using Services}}
The concepts of interfaces and services were introduced for the following reasons:

'''Interfaces and services separate specification from implementation'''
: The specification of an interface or service is ''abstract'', that is, it does not define how objects supporting a certain functionality do this ''internally''. Through the abstract specification of the {{OOo}} API, it is possible to pull the implementation out from under the API and install a different implementation if required.

'''Service names allow to create instances by specification name, not by class names'''
: In Java or C++ you use the new operator to create a class instance. This approach is restricted: the class you get is hard-coded. You cannot later on exchange it by another class without editing the code. The concept of services solves this. The central object factory in {{OOo}}, the global service manager, is asked to create an object that can be used for a certain purpose without defining its internal implementation. This is possible because a service can be ordered from the factory by its ''service name'' and the factory decides which service implementation it returns. Which implementation you get makes no difference, you only use the well-defined interface of the service.

===Multiple Interface Implementation===
Abstract interfaces are more reusable if they are fine-grained, i.e., if they are small and describe only a single aspect of an object. To describe the many aspects of an object, objects can implement more than one of these fine-grained interfaces. This "multiple interface implementation" allows same aspects of similar objects accessed with the same code. For example, many objects support text: text may be found in the body of a document, in text frames, in headers and footers, footnotes, table cells, and in drawing shapes. These objects all support the same interface, so a procedure can use, for example, getText() to retrieve text from ''any'' of them.

Services, interfaces, and methods are illustrated in the figure below for the old-style service <idl>com.sun.star.text.TextDocument</idl>, shown using [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] notation. In this figure, services are shown on the left side. The arrow between services indicates that one service provided by the upper (arrowhead) service are inherited by the lower service. Interfaces exported by these services are shown on the right. All interface names in the {{OOo}} API start with an X, so as to be distinguishable from the names of other entities. Each interface contains methods, which are listed beneath the interface.

[[Image:TextDocumentWithMethods.png|none|thumb|450px|Figure. TextDocument inherits the methods of OfficeDocument.]]

A <code>TextDocument</code> object provides the <idl>com.sun.star.text.TextDocument</idl> service, which implements the interfaces, <code>XTextDocument</code>, <code>XSearchable</code>, and <code>XRefreshable</code>. These interfaces provide, for example, the methods <code>getText()</code>, for adding text to a document, and <code>findAll()</code>, for searching the document.

As indicated by the arrow, the <idl>com.sun.star.text.TextDocument</idl> service also inherits all the interfaces provided by the <idl>com.sun.star.document.OfficeDocument</idl> service, so these interfaces are also provided to a <code>TextDocument</code> object. These interfaces handle tasks common to the {{OOo}} applications: printing, <code>XPrintable</code>; storing, <code>XStorable</code>; modifying, <code>XModifiable</code>; and model handling, <code>XModel</code>.

The interfaces shown in the figure are only the mandatory interfaces of a <code>TextDocument</code> object. A <code>TextDocument</code> has optional properties and interfaces, among them the properties <code>CharacterCount</code>, <code>ParagraphCount</code> and <code>WordCount</code>, and the interface <code>XPropertySet</code>, which must be supported if properties are present at all. The implementation of the <code>TextDocument</code> service in {{OOo}} supports both required and all optional interfaces as well. The usage of a <code>TextDocument</code> is described thoroughly in [[Documentation/DevGuide/Text/Text Documents|Text Documents]].

C++ and Java require that the interface name be provided when accessing a method. An old-style service may provide several interfaces to keep track of. New-style services are easier to use because, since they have just one interface, all the methods are accessed through the same interface.

===Using Interfaces===


The fact that every UNO object must be accessed through its interfaces has an effect in languages like Java and C++, where the compiler needs the correct type of an object reference before you can call a method from it. In Java or C++, you normally just cast an object before you access an interface it implements. When working with UNO objects this is different: You must ask the UNO environment to get the appropriate reference for you whenever you want to access methods of an interface which your object supports, but your compiler does not yet know about. Only then you can cast it safely.

The Java UNO environment has a method <code>queryInterface()</code> for this purpose. It looks complicated at first sight, but once you understand that <code>queryInterface()</code> is about safe casting of UNO types across process boundaries, you will soon get used to it. Take a look at the second example FirstLoadComponent.java (in the sample directory, if you have installed the SDK on your computer), where a new Desktop object is created and, afterwards, the <idlm>queryInterface</idlm>() method is used to get the <idls>com.sun.star.frame.XComponentLoader</idls> interface.

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);

XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

We asked the service manager to create a <idl>com.sun.star.frame.Desktop</idl> using its factory method createInstanceWithContext(). This method is defined to return a Java Object type, which should not surprise you—after all the factory must be able to return any type:

<source lang="java">
java.lang.Object createInstanceWithContext(String serviceName, XComponentContext context)
</source>

The object we receive is a <idl>com.sun.star.frame.Desktop</idl> service. The point is, while we know that the object we ordered at the factory is a DesktopUnoUrlResolver and exports among other interfaces the interface <code>XComponentLoader</code>, the compiler does ''not''. Therefore, we have to use the UNO runtime environment to ask or ''query'' for the interface <code>XComponentLoader</code>, since we want to use the <code>loadComponentFromURL()</code> method on this interface. The method <code>queryInterface()</code> makes sure we get a reference that can be cast to the needed interface type, no matter if the target object is a local or a remote object. There are two <code>queryInterface</code> definitions in the Java UNO language binding:

<source lang="java">
java.lang.Object UnoRuntime.queryInterface(java.lang.Class targetInterface, Object sourceObject)
java.lang.Object UnoRuntime.queryInterface(com.sun.star.uno.Type targetInterface, Object sourceObject)
</source>

Since <code>UnoRuntime.queryInterface()</code> is specified to return a java.lang.Object just like the factory method <code>createInstanceWithContext()</code>, we still must explicitly cast our interface reference to the needed type. The difference is that after <code>queryInterface()</code> we can safely cast the object to our interface type and, most important, that the reference will now work even with an object in another process. Here is the <code>queryInterface()</code> call, explained step by step:

<source lang="java">
XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

<code>XComponentLoader</code> is the interface we want to use, so we define a <code>XComponentLoader</code> variable named <code>xComponentLoader</code> (lower x) to store the interface we expect from <code>queryInterface</code>.
Then we query our desktop object for the <code>XComponentLoader</code> interface, passing in <code>XComponentLoader.class</code> as target interface and desktop as source object. Finally we cast the outcome to <code>XComponentLoader</code> and assign the resulting reference to our variable <code>xComponentLoader</code>.
If the source object does not support the interface we are querying for, <code>queryInterface()</code> will return null.

In Java, this call to <code>queryInterface()</code> is necessary whenever you have a reference to an object which is known to support an interface that you need, but you do not have the proper reference type yet. Fortunately, you are not only allowed to <code>queryInterface()</code> from <code>java.lang.Object</code> source types, but you may also query an interface from another interface reference, like this:

<source lang="java">
// loading a blank spreadsheet document gives us its XComponent interface:
XComponent xComponent = xComponentLoader.loadComponentFromURL(
"private:factory/scalc", "_blank", 0, loadProps);

// now we query the interface XSpreadsheetDocument from xComponent
XSpreadsheetDocument xSpreadsheetDocument = (XSpreadsheetDocument)UnoRuntime.queryInterface(
XSpreadsheetDocument.class, xComponent);
</source>

Furthermore, if a method is defined in such a way that it already returns an interface type, you do not need to query the interface, but you can use its methods right away. In the snippet above, the method <code>loadComponentFromURL</code> is specified to return an <idl>com.sun.star.lang.XComponent</idl> interface, so you may call the <code>XComponent</code> methods <code>addEventListener()</code> and <code>removeEventListener()</code> directly at the <code>xComponent</code> variable, if you want to be notified that the document is being closed.
The corresponding step in C++ is done by a <code>Reference<></code> template that takes the source instance as parameter:

<source lang="java">
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
</source>

In {{OOo}} Basic, querying for interfaces is not necessary; the Basic runtime engine takes care of that internally.
With the proliferation of multiple-inheritance interfaces in the {{OOo}} API, there will be less of a demand to explicitly query for specific interfaces in Java or C++. For example, with the hypothetical interfaces

<source lang="idl">
interface XBase1 { void fun1();
};
interface XBase2 {
void fun2();
};
interface XBoth { // inherits from both XBase1 and XBase2
interface XBase1;
interface XBase2;
};
interface XFactory {
XBoth getBoth();};
</source>

you can directly call both <code>fun1()</code> and <code>fun2()</code> on a reference obtained through <code>XFactory.getBoth()</code>, without querying for either <code>XBase1</code> or <code>XBase2</code>.

===Using Properties===

An object must offer its properties through interfaces that allow you to work with properties. The most basic form of these interfaces is the interface <idl>com.sun.star.beans.XPropertySet</idl>. There are other interfaces for properties, such as <idl>com.sun.star.beans.XMultiPropertySet</idl>, that gets and sets a multitude of properties with a single method call. The <code>XPropertySet</code> is always supported when properties are present in a service.

In <code>XPropertySet</code>, two methods carry out the property access, which are defined in Java as follows:

<source lang="java">
void setPropertyValue(String propertyName, Object propertyValue)
Object getPropertyValue(String propertyName)
</source>

In the FirstLoadComponent example, the <code>XPropertySet</code> interface was used to set the CellStyle property at a cell object. The cell object was a <code>com.sun.star.sheet.SheetCell</code> and therefore supports also the <code>com.sun.star.table.CellProperties</code> service which had a property <code>CellStyle</code>. The following code explains how this property was set:

<source lang="java">
// query the XPropertySet interface from cell object
XPropertySet xCellProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xCell);

// set the CellStyle property
xCellProps.setPropertyValue("CellStyle", "Result");
</source>

You are now ready to start working with a {{PRODUCTNAME}} document.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-05T23:30:22Z

Cking: Added that new-style interface is created in a separate step

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Working with Objects
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services]]
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
===Objects===

In UNO, an ''object'' is a software artifact that has methods that you can call and attributes that you can get and set. Exactly which methods and attributes an object offers is specified by the set of interfaces it supports.

===Interfaces===

An ''interface'' specifies a set of attributes and methods that together define one single aspect of an object. For instance, the interface <idl>com.sun.star.resource.XResourceBundle</idl> specifies the attribute <code>Parent</code> and the methods <code>getLocale()</code> and <code>getDirectElement()</code>.

<source lang="idl">
module com { module sun { module star { module resource { interfaceXResourceBundle: com::sun::star::container::XNameAccess {
[attribute] XResourceBundle Parent;
com::sun::star::lang::Locale getLocale();
any getDirectElement([in] string key);
};
}; }; }; };
</source>

To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>). Multiple inheritance, the ability to inherit more than one interface, was introduced in {{PRODUCTNAME}} {{OOo2.x}}.

Strictly speaking, interface attributes are not needed in UNO. Each attribute could also be expressed as a combination of one method to get the attribute's value, and another method to set it (or just one method to get the value for a read-only attribute). However, there are at least two good reasons for the inclusion of interface attributes in UNO: First, the need for such combinations of getting and setting a value seems to be widespread enough to warrant extra support. Second, with attributes, a designer of an interface can better express nuances among the different features of an object. Attributes can be used for those features that are not considered integral or structural parts of an object, while explicit methods are reserved to access the core features.
Historically, a UNO object typically supported a set of many independent interfaces, corresponding to its many different aspects. With multiple-inheritance interfaces, there is less need for this, as an object may now support just one interface that inherits from all the other interfaces that make up the object’s various aspects.

===Services===

Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, the underlying concepts have been made cleaner. Unfortunately, this leaves two different meanings for the term “service” within UNO. In the following, we will use the term "new-style service" to denote an entity that conforms to the clarified, {{PRODUCTNAME}}-{{OOo2.x}} service concept, while we use "old-style service" to denote an entity that only conforms to the historical, more vague concept. To make matters even more complicated, the term “service” is often used with still different meanings in contexts outside UNO.

Although technically there should no longer be any need for old-style services, the {{PRODUCTNAME}} API still uses them extensively to remain backwards compatible. Therefore, be prepared to encounter uses of both service concepts in parallel when working with the {{PRODUCTNAME}} API.

A ''new-style service'' is of the form

<source lang="idl">
module com { module sun { module star { module bridge {
serviceUnoUrlResolver: XUnoUrlResolver;
}; }; }; };
</source>

and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) will be available under a certain service name (e.g., "com.sun.star.bridge.UnoUrlResolver") at a component context’s service manager. Formally, new-style services are called “single-interface–based services.” That "single interface" is created in a separate step that combines all the interfaces needed to define the object.

The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].

An ''old-style service'' (formally called an “accumulation-based service”) is of the form

<source lang="idl">
module com { module sun { module star { module frame {serviceDesktop {
service Frame;
interface XDesktop;
interface XComponentLoader;
interface com::sun::star::document::XEventBroadcaster;
};
}; }; }; };
</source>

and is used to specify any of the following:

* The general contract is that, if an object is documented to support a certain old-style service, then you can expect that object to support all interfaces exported by the service itself and any inherited services. For example, the method <idlml>com.sun.star.frame.XFrames:queryFrames</idlml> returns a sequence of objects that should all support the old-style service <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
* Additionally, an old-style service may specify one or more properties, as in

<source lang="idl">
module com { module sun { module star { module frame {service Frame {
interface com::sun::star::frame::XFrame;
interface com::sun::star::frame::XDispatchProvider;
// ...
[property] string Title;
[property, optional] XDispatchRecorderSupplier RecorderSupplier;
// ...
};
}; }; }; };
</source>

: Properties, which are explained in detail in the following section, are similar to interface attributes, in that they describe additional features of an object. The main difference is that interface attributes can be accessed directly, while the properties of an old-style service are typically accessed via generic interfaces like <idl>com.sun.star.beans.XPropertySet</idl>. Often, interface attributes are used to represent integral features of an object, while properties represent additional, more volatile features.

* Some old-style services are intended to be available at a component context’s service manager. For example, the service <idl>com.sun.star.frame.Desktop</idl> can be instantiated at a component context’s service manager under its service name "com.sun.star.frame.Desktop". (The problem is that you cannot tell whether a given old-style service is intended to be available at a component context; using a new-style service instead makes that intent explicit.)

* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)

* Yet other old-style services only list properties, and do not export any interfaces at all. Instead of specifying the interfaces supported by certain objects, as the other kinds of old-style services do, such services are used to document a set of related properties. For example, the service <idl>com.sun.star.document.MediaDescriptor</idl> lists all the properties that can be passed to <idlml>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlml>.

A ''property'' is a feature of an object which is typically not considered an integral or structural part of the object and therefore is handled through generic <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> interface to be prepared to handle all kinds of properties. Typical examples are properties for character or paragraph formatting. With properties, you can set multiple features of an object through a single call to <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/WritingUNO/Defining a Service

2008-10-05T22:52:00Z

Cking:

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2a=block
|WritingUNO2Spec=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Defining an Interface
|NextPage=Documentation/DevGuide/WritingUNO/Defining a Sequence
}}
[[zh:Zh/Documentation/DevGuide/WritingUNO/Defining a Service]]
{{DISPLAYTITLE:Defining a Service}}
The new-style UNOIDL services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes, <code>interface</code>, <code>property</code> and <code>service</code> declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the {{PRODUCTNAME}} API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.


We are ready to assemble our <code>ImageShrink</code> service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our <code>XImageShrink</code> interface offers the needed capabilities, together with the interface <idl>com.sun.star.document.XFilter</idl> that supports two methods:
<source lang="idl">
boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)
void cancel()
</source>
A new-style service can only encompass one interface, so we need to combine <code>XImageShrink</code> and <code>XFilter</code> in a single, multiple-inheritance interface:
<source lang="idl">
#ifndef __org_openoffice_test_XImageShrinkFilter_idl__
#define __org_openoffice_test_XImageShrinkFilter_idl__
#include <com/sun/star/document/XFilter.idl>
#include <org/openoffice/test/XImageShrink.idl>

module org { module openoffice { module test {

interface XImageShrinkFilter {
interface XImageShrink;
interface com::sun::star::document::XFilter;
};

}; }; };

#endif
</source>
The <code>ImageShrink</code> service specification is provided by the following code:

<source lang="idl">
#ifndef __org_openoffice_test_ImageShrink_idl__
#define __org_openoffice_test_ImageShrink_idl__
#include <org/openoffice/test/XImageShrinkFilter.idl>

module org { module openoffice { module test {

service ImageShrink: XImageShrinkFilter;

}; }; };

#endif
</source>
A new-style service is defined using the <code>service</code> declaration. A new-style service opens with the keyword <code>service</code>, followed by a service name, a colon, the name of the interface supported by the service, and, finally, a semicolon. The first letter of the service name should be upper-case.

<source lang="idl">
service ServiceName: XInterface;
</source>

An old-style service is much more complex. It opens with the keyword <code>service</code>, followed by a service name and the service body in braces, and, finally, a semicolon. The body of a service can reference interfaces and services using <code>interface</code> and <code>service</code> instructions, and it can identify properties supported by the service through <code>[property]</code> instructions.

* <code>Interface</code> keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, the <code>interface</code> forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keyword <code>interface</code>. This weakens the specification to a permission. An optional interface can be implemented. Use one interface declaration for each supported interface or give a comma-separated list of interfaces to be exported by a service. You must terminate the <code>interface</code> instruction using a semicolon.

* <code>service</code> instructions in a service body include other services. The effect is that all interface and property definitions of the other services become part of the current service. A service reference can be optional using the <code>[optional]</code> flag in front of the <code>service</code> keyword. Use one declaration per service or a comma-separated list for the services to reference. The <code>service</code> declaration ends with a semicolon.

* <code>[property]</code> declaration s describe qualities of a service that can be reached from the outside under a particular name and type. As opposed to interface attributes, these qualities are not considered to be a structural part of a service. Refer to the section [[Documentation/DevGuide/ProUNO/Properties|Properties]] in the chapter [[Documentation/DevGuide/ProUNO/Professional UNO|Professional UNO]] to determine when to use interface attributes and when to introduce properties in a service . The <code>property</code> keyword must be enclosed in square brackets, and continue with a known type and a property identifier. Just like a service and an interface, make a property non-mandatory writing <code>[property, optional]</code>. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with <code>[property]</code>:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Property Flags
!Description
|-
|<code>optional</code>
|Property is non-mandatory.
|-
|<code>readonly</code>
|The value of the property cannot be changed using the setter methods for properties, such as <code>setPropertyValue(string name)</code>.
|-
|<code>bound</code>
|Changes of values are broadcast to <idl>com.sun.star.beans.XPropertyChangeListener</idl>s registered with the component.
|-
|<code>constrained</code>
|The component must broadcast an event before a value changes, listeners can veto.
|-
|<code>maybeambiguous</code>
|The value cannot be determined in some cases, for example, in multiple selections.
|-
|<code>maybedefault</code>
|The value might come from a style or the application environment instead of from the object itself.
|-
|<code>maybevoid</code>
|The property type determines the range of possible values, but sometimes there may be situations where there is no information available. Instead of defining special values for each type denoting that there are no meaningful values, the UNO type <code>void</code> can be used. Its meaning is comparable to <code>null</code> in relational databases.
|-
|<code>removable</code>
|The property is removable. If a property is made removable, you must check for the existence of a property using <code>hasPropertyByName()</code> at the interface <idl>com.sun.star.beans.XPropertySetInfo</idl> and consider providing the capability to add or remove properties using <idl>com.sun.star.beans.XPropertyContainer</idl>.
|-
|<code>transient</code>
|The property will not be stored if the object is serialized (made persistent).
|}

* Several properties of the same type can be listed in one <code>property</code> declaration. Remember to add a semicolon at the end. Implement the interface <idl>com.sun.star.beans.XPropertySet</idl> when putting properties in your service, otherwise the properties specified will not work for others using the component.

{{Documentation/Note|Some old-style services, which specify no interfaces at all, only properties, are used as a sequence of <idl>com.sun.star.beans.PropertyValue</idl> in {{PRODUCTNAME}}, for example, <idl>com.sun.star.document.MediaDescriptor</idl>.}}

The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service <idl>com.sun.star.text.TextDocument</idl> as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.
<source lang="idl">
service TextDocument
{
service com::sun::star::document::OfficeDocument;

interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
interface com::sun::star::util::XNumberFormatsSupplier;

[optional] interface com::sun::star::text::XFootnotesSupplier;
[optional] interface com::sun::star::text::XEndnotesSupplier;
[optional] interface com::sun::star::util::XReplaceable;
[optional] interface com::sun::star::text::XPagePrintable;
[optional] interface com::sun::star::text::XReferenceMarksSupplier;
[optional] interface com::sun::star::text::XLineNumberingSupplier;
[optional] interface com::sun::star::text::XChapterNumberingSupplier;
[optional] interface com::sun::star::beans::XPropertySet;
[optional] interface com::sun::star::text::XTextGraphicObjectsSupplier;
[optional] interface com::sun::star::text::XTextEmbeddedObjectsSupplier;
[optional] interface com::sun::star::text::XTextTablesSupplier;
[optional] interface com::sun::star::style::XStyleFamiliesSupplier;

[optional, property] com::sun::star::lang::Locale CharLocale;
[optional, property] string WordSeparator;

[optional, readonly, property] long CharacterCount;
[optional, readonly, property] long ParagraphCount;
[optional, readonly, property] long WordCount;

};
</source>
{{Documentation/Note|You might encounter two more keywords in old-style service bodies. The keyword <tt>observes</tt> can stand in front of interface references and means that the given interfaces must be "observed". Since the <tt>observes</tt> concept is disapproved of, no further explanation is provided.

If a service references another service using the keyword <tt>needs</tt> in front of the reference, then this service depends on the availability of the needed service at runtime. Services should not use needs as it is considered too implementation specific.}}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Documentation/DevGuide/WritingUNO/Defining a Service

2008-10-05T22:50:22Z

Cking: Added a line showing the new-style service: "service ServiceName: XInterface;"

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2a=block
|WritingUNO2Spec=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Defining an Interface
|NextPage=Documentation/DevGuide/WritingUNO/Defining a Sequence
}}
[[zh:Zh/Documentation/DevGuide/WritingUNO/Defining a Service]]
{{DISPLAYTITLE:Defining a Service}}
The new-style UNOIDL Services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes, <code>interface</code>, <code>property</code> and <code>service</code> declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the {{PRODUCTNAME}} API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.


We are ready to assemble our <code>ImageShrink</code> service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our <code>XImageShrink</code> interface offers the needed capabilities, together with the interface <idl>com.sun.star.document.XFilter</idl> that supports two methods:
<source lang="idl">
boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)
void cancel()
</source>
A new-style service can only encompass one interface, so we need to combine <code>XImageShrink</code> and <code>XFilter</code> in a single, multiple-inheritance interface:
<source lang="idl">
#ifndef __org_openoffice_test_XImageShrinkFilter_idl__
#define __org_openoffice_test_XImageShrinkFilter_idl__
#include <com/sun/star/document/XFilter.idl>
#include <org/openoffice/test/XImageShrink.idl>

module org { module openoffice { module test {

interface XImageShrinkFilter {
interface XImageShrink;
interface com::sun::star::document::XFilter;
};

}; }; };

#endif
</source>
The <code>ImageShrink</code> service specification is provided by the following code:

<source lang="idl">
#ifndef __org_openoffice_test_ImageShrink_idl__
#define __org_openoffice_test_ImageShrink_idl__
#include <org/openoffice/test/XImageShrinkFilter.idl>

module org { module openoffice { module test {

service ImageShrink: XImageShrinkFilter;

}; }; };

#endif
</source>
A new-style service is defined using the <code>service</code> declaration. A new-style service opens with the keyword <code>service</code>, followed by a service name, a colon, the name of the interface supported by the service, and, finally, a semicolon. The first letter of the service name should be upper-case.

<source lang="idl">
service ServiceName: XInterface;
</source>

An old-style service is much more complex. It opens with the keyword <code>service</code>, followed by a service name and the service body in braces, and, finally, a semicolon. The body of a service can reference interfaces and services using <code>interface</code> and <code>service</code> instructions, and it can identify properties supported by the service through <code>[property]</code> instructions.

* <code>Interface</code> keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, the <code>interface</code> forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keyword <code>interface</code>. This weakens the specification to a permission. An optional interface can be implemented. Use one interface declaration for each supported interface or give a comma-separated list of interfaces to be exported by a service. You must terminate the <code>interface</code> instruction using a semicolon.

* <code>service</code> instructions in a service body include other services. The effect is that all interface and property definitions of the other services become part of the current service. A service reference can be optional using the <code>[optional]</code> flag in front of the <code>service</code> keyword. Use one declaration per service or a comma-separated list for the services to reference. The <code>service</code> declaration ends with a semicolon.

* <code>[property]</code> declaration s describe qualities of a service that can be reached from the outside under a particular name and type. As opposed to interface attributes, these qualities are not considered to be a structural part of a service. Refer to the section [[Documentation/DevGuide/ProUNO/Properties|Properties]] in the chapter [[Documentation/DevGuide/ProUNO/Professional UNO|Professional UNO]] to determine when to use interface attributes and when to introduce properties in a service . The <code>property</code> keyword must be enclosed in square brackets, and continue with a known type and a property identifier. Just like a service and an interface, make a property non-mandatory writing <code>[property, optional]</code>. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with <code>[property]</code>:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Property Flags
!Description
|-
|<code>optional</code>
|Property is non-mandatory.
|-
|<code>readonly</code>
|The value of the property cannot be changed using the setter methods for properties, such as <code>setPropertyValue(string name)</code>.
|-
|<code>bound</code>
|Changes of values are broadcast to <idl>com.sun.star.beans.XPropertyChangeListener</idl>s registered with the component.
|-
|<code>constrained</code>
|The component must broadcast an event before a value changes, listeners can veto.
|-
|<code>maybeambiguous</code>
|The value cannot be determined in some cases, for example, in multiple selections.
|-
|<code>maybedefault</code>
|The value might come from a style or the application environment instead of from the object itself.
|-
|<code>maybevoid</code>
|The property type determines the range of possible values, but sometimes there may be situations where there is no information available. Instead of defining special values for each type denoting that there are no meaningful values, the UNO type <code>void</code> can be used. Its meaning is comparable to <code>null</code> in relational databases.
|-
|<code>removable</code>
|The property is removable. If a property is made removable, you must check for the existence of a property using <code>hasPropertyByName()</code> at the interface <idl>com.sun.star.beans.XPropertySetInfo</idl> and consider providing the capability to add or remove properties using <idl>com.sun.star.beans.XPropertyContainer</idl>.
|-
|<code>transient</code>
|The property will not be stored if the object is serialized (made persistent).
|}

* Several properties of the same type can be listed in one <code>property</code> declaration. Remember to add a semicolon at the end. Implement the interface <idl>com.sun.star.beans.XPropertySet</idl> when putting properties in your service, otherwise the properties specified will not work for others using the component.

{{Documentation/Note|Some old-style services, which specify no interfaces at all, only properties, are used as a sequence of <idl>com.sun.star.beans.PropertyValue</idl> in {{PRODUCTNAME}}, for example, <idl>com.sun.star.document.MediaDescriptor</idl>.}}

The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service <idl>com.sun.star.text.TextDocument</idl> as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.
<source lang="idl">
service TextDocument
{
service com::sun::star::document::OfficeDocument;

interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
interface com::sun::star::util::XNumberFormatsSupplier;

[optional] interface com::sun::star::text::XFootnotesSupplier;
[optional] interface com::sun::star::text::XEndnotesSupplier;
[optional] interface com::sun::star::util::XReplaceable;
[optional] interface com::sun::star::text::XPagePrintable;
[optional] interface com::sun::star::text::XReferenceMarksSupplier;
[optional] interface com::sun::star::text::XLineNumberingSupplier;
[optional] interface com::sun::star::text::XChapterNumberingSupplier;
[optional] interface com::sun::star::beans::XPropertySet;
[optional] interface com::sun::star::text::XTextGraphicObjectsSupplier;
[optional] interface com::sun::star::text::XTextEmbeddedObjectsSupplier;
[optional] interface com::sun::star::text::XTextTablesSupplier;
[optional] interface com::sun::star::style::XStyleFamiliesSupplier;

[optional, property] com::sun::star::lang::Locale CharLocale;
[optional, property] string WordSeparator;

[optional, readonly, property] long CharacterCount;
[optional, readonly, property] long ParagraphCount;
[optional, readonly, property] long WordCount;

};
</source>
{{Documentation/Note|You might encounter two more keywords in old-style service bodies. The keyword <tt>observes</tt> can stand in front of interface references and means that the given interfaces must be "observed". Since the <tt>observes</tt> concept is disapproved of, no further explanation is provided.

If a service references another service using the keyword <tt>needs</tt> in front of the reference, then this service depends on the availability of the needed service at runtime. Services should not use needs as it is considered too implementation specific.}}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Documentation/DevGuide/ProUNO/Services

2008-10-05T21:46:29Z

Cking: Added blockquote about multiple-inheritance interface vs. multiple interface implementation

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2a=block
|ProUNO2aDTypes=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Interfaces
|NextPage=Documentation/DevGuide/ProUNO/Structs
}}
{{DISPLAYTITLE:Services}}
__NOTOC__
We have seen that a single-inheritance interface describes only one aspect of an object. However, it is quite common that objects have more than one aspect. UNO uses ''multiple-inheritance interfaces'' and ''services'' to specify complete objects which can have many aspects.
<blockquote>
{{OOo}} objects can ''inherit'' services, including interfaces, from only one parent object. However, objects can ''implement'' multiple interfaces. Inherited methods can be provided by the parent of the object; implemented methods must be provide by the object itself. Although {{OOo}} does not support true multiple-inheritance, objects can implement multiple interfaces, which gives them the appearance of having inherited methods from several other objects. When the term ''multiple-inheritance interface'' is used in {{OOo}}, it actually refers to ''multiple interface implementation''.
</blockquote>
In a first step, all the various aspects of an object (which are typically represented by single-inheritance interfaces) are grouped together in one multiple-inheritance interface type. If such an object is obtainable by calling specific factory methods, this step is all that is needed. The factory methods are specified to return values of the given, multiple-inheritance interface type. If, however, such an object is available as a general service at the global component context, a service description must be provided in a second step. This service description will be of the new style, mapping the service name (under which the service is available at the component context) to the given, multiple-inheritance interface type.

For backward compatibility, there are also old-style services, which comprise a set of single-inheritance interfaces and properties that are needed to support a certain functionality. Such a service can include other old-style services as well. The main drawback of an old-style service is that it is unclear whether it describes objects that can be obtained through specific factory methods (and for which there would therefore be no new-style service description), or whether it describes a general service that is available at the global component context, and for which there would thus be a new-style service description.

From the perspective of a ''user'' of a UNO object, the object offers one or sometimes even several independent, multiple-inheritance interfaces or old-style services described in the API reference. The services are utilized through method calls grouped in interfaces, and through properties, which are handled through special interfaces as well. Because the access to the functionality is provided by interfaces only, the implementation is irrelevant to a user who wants to use an object.

From the perspective of an ''implementer'' of a UNO object, multiple-inheritance interfaces and old-style services are used to define a functionality independently of a programming language and without giving instructions about the internal implementation of the object. Implementing an object means that it must support all specified interfaces and properties. It is possible that a UNO object implements more than one independent, multiple-inheritance interface or old-style service. Sometimes it is useful to implement two or more independent, multiple-inheritance interfaces or services because they have related functionality, or because they support different views to the object.

The [[:Image:RemoteControlImpl.png|RemoteControl service]] illustration shows the relationship between interfaces and services. The language independent specification of an old-style service with several interfaces is used to implement a UNO object that fulfills the specification. Such a UNO object is sometimes called a "component," although that term is more correctly used to describe deployment entities within a UNO environment. The illustration uses an old-style service description that directly supports multiple interfaces; for a new-style service description, the only difference would be that it would only support one multiple-inheritance interface, which in turn would inherit the other interfaces.

[[Image:RelationshipSpecImpl.png|none|thumb|400px|Interfaces, services and implementation ]]

The functionality of a TV system with a TV set and a remote control can be described in terms of service specifications. The interfaces <code>XPower</code> and <code>XChannel</code> described above would be part of a service specification <code>RemoteControl</code>. The new service <code>TVSet</code> consists of the three interfaces <code>XPower</code>, <code>XChannel</code> and <code>XStandby</code> to control the power, the channel selection, the additional power function <code>standby()</code> and a <code>timer()</code> function.

[[Image:TVRemoteServices.png|none|thumb|500px|TV System Specification ]]

===Referencing Interfaces===

References to interfaces in a service definition mean that an implementation of this service ''must'' offer the specified interfaces. However, optional interfaces are possible. If a multiple-inheritance interface inherits an optional interface, or an old-style service contains an optional interface, any given UNO object may or may not support this interface. If you utilize an optional interface of a UNO object, always check if the result of <code>queryInterface()</code> is equal to <code>null</code> and react accordingly - otherwise your code will not be compatible with implementations without the optional interface and you might end up with null pointer exceptions. The following UNOIDL snippet shows a fragment of the specification for the old-style <idl>com.sun.star.text.TextDocument</idl> service in the {{PRODUCTNAME}} API. Note the flag optional in square brackets, which makes the interfaces <code>XFootnotesSupplier</code> and <code>XEndnotesSupplier</code> non-mandatory.

<source lang="idl">// com.sun.star.text.TextDocument
service TextDocument
{
...

interface com::sun::star::text::XTextDocument;
interface com::sun::star::util::XSearchable;
interface com::sun::star::util::XRefreshable;
[optional] interface com::sun::star::text::XFootnotesSupplier;
[optional] interface com::sun::star::text::XEndnotesSupplier;

...
};</source>

===Service Constructors===

New-style services can have constructors, similar to interface methods:
<source lang="idl">
service SomeService: XSomeInterface {
create1();
create2([in] long arg1, [in] string arg2);
create3([in] any... rest);
};
</source>
In the above example, there are three ''explicit'' constructors, named <code>create1</code>, <code>create2</code>, and <code>create3</code>. The first has no parameters, the second has two normal parameters, and the third has a special ''rest'' parameter, which accepts an arbitrary number of any values. Constructor parameters may only be <code>[in]</code>, and a rest parameter must be the only parameter of a constructor, and must be of type <code>any;</code> also, unlike an interface method, a service constructor does not specify a return type.

The various language bindings map the UNO constructors into language-specific constructs, which can be used in client code to obtain instances of those services, given a component context. The general convention (followed,for example, by the Java and C++ language bindings) is to map each constructor to a static method (resp. function) with the same name, that takes as a first parameter an <idls>com.sun.star.uno.XComponentContext</idls>, followed by all the parameters specified in the constructor, and returns an (appropriately typed) service instance. If an instance cannot be obtained, a <idl>com.sun.star.uno.DeploymentException</idl> is thrown. The above <code>SomeService</code> would map to the following Java 1.5 class, for example:
<source lang="java">
public class SomeService {
public static XSomeInterface create1(
com.sun.star.uno.XComponentContext context) { ... }
public static XSomeInterface create2(
com.sun.star.uno.XComponentContext context, int arg1, String arg2) { ... }
public static XSomeInterface create3(
com.sun.star.uno.XComponentContext context, Object... rest) { ... }
}
</source>
Service constructors can also have exception specifications (<code>"raises (Exception1, ...)"</code>), which are treated in the same way as exception specifications of interface methods. (If a constructor has no exception specification, it may only throw runtime exceptions, <idl>com.sun.star.uno.DeploymentException</idl> in particular.)

If a new-style service is written using the short form,
<source lang="idl">
service SomeService: XSomeInterface;
</source>
then it has an ''implicit'' constructor. The exact behavior of the implicit constructor is language-binding - specific, but it is typically named <code>create</code>, takes no arguments besides the <idls>com.sun.star.uno.XComponentContext</idls>, and may only throw runtime exceptions.

===Including Properties===

When the structure of the {{PRODUCTNAME}} API was founded, the designers discovered that the objects in an office environment would have huge numbers of qualities that did not appear to be part of the structure of the objects, rather they seemed to be superficial changes to the underlying objects. It was also clear that not all qualities would be present in each object of a certain kind. Therefore, instead of defining a complicated pedigree of optional and non-optional interfaces for each and every quality, the concept of properties was introduced. Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods. The concept of properties has other advantages, and there is more to know about properties. Please refer to [[Documentation/DevGuide/ProUNO/Properties|Properties]] for further information about properties.

Old-style services can list supported properties directly in the UNOIDL specification. A <code>property</code> defines a member variable with a specific type that is accessible at the implementing component by a specific name. It is possible to add further restrictions to a property through additional flags. The following old-style service references one interface and three optional properties. All known API types can be valid property types:

<source lang="idl">// com.sun.star.text.TextContent
service TextContent
{
interface com::sun::star::text::XTextContent;
[optional, property] com::sun::star::text::TextContentAnchorType AnchorType;
[optional, readonly, property] sequence<com::sun::star::text::TextContentAnchorType> AnchorTypes;
[optional, property] com::sun::star::text::WrapTextMode TextWrap;
};</source>

Possible property flags are:

* <code>optional</code>
:The property does not have to be supported by the implementing component.
* <code>readonly</code>
:The value of the property cannot be changed using [IDL:com.sun.star.beans.XPropertySet].
* <code>bound</code>
:Changes of property values are broadcast to <idls>com.sun.star.beans.XPropertyChangeListener</idls>, if any were registered through <idl>com.sun.star.beans.XPropertySet</idl>.
* <code>constrained</code>
:The property broadcasts an event before its value changes. Listeners have the right to veto the change.
* <code>maybeambiguous</code>
:Possibly the property value cannot be determined in some cases, for example, in multiple selections with different values.
* <code>maybedefault</code>
:The value might be stored in a style sheet or in the environment instead of the object itself.
* <code>maybevoid</code>
:In addition to the range of the property type, the value can be void. It is similar to a null value in databases.
* <code>removable</code>
:The property is removable, this is used for dynamic properties.
* <code>transient</code>
:The property will not be stored if the object is serialized

===Referencing other Services===

Old-style services can include other old-style services. Such references may be optional. That a service is included by another service has nothing to do with implementation inheritance, only the specifications are combined. It is up to the implementer if he inherits or delegates the necessary functionality, or if he implements it from scratch.

The old-style service <idl>com.sun.star.text.Paragraph</idl> in the following UNOIDL example includes one mandatory service <idl>com.sun.star.text.TextContent</idl> and five optional services. Every <code>Paragraph</code> must be a <code>TextContent</code>. It can be a <code>TextTable</code> and it is used to support formatting properties for paragraphs and characters:
<source lang="idl">
// com.sun.star.text.Paragraph
service Paragraph
{
service com::sun::star::text::TextContent;
[optional] service com::sun::star::text::TextTable;
[optional] service com::sun::star::style::ParagraphProperties;
[optional] service com::sun::star::style::CharacterProperties;
[optional] service com::sun::star::style::CharacterPropertiesAsian;
[optional] service com::sun::star::style::CharacterPropertiesComplex;

...
};
</source>
If all the old-style services in the example above were multiple-inheritance interface types instead, the structure would be similar: the multiple-inheritance interface type <code>Paragraph</code> would inherit the mandatory interface <code>TextContent</code> and the optional interfaces <code>TextTable</code>, <code>ParagraphProperties</code>, etc.

===Service Implementations in Components===

A ''component'' is a shared library or Java archive containing implementations of one or more services in one of the target programming languages supported by UNO. Such a component must meet basic requirements, mostly different for the different target language, and it must support the specification of the implemented services. That means all specified interfaces and properties must be implemented. Components must be registered in the UNO runtime system. After the registration all implemented services can be used by ordering an instance of the service at the appropriate service factory and accessing the functionality over interfaces.

Based on our example specifications for a <code>TVSet</code> and a <code>RemoteControl</code> service, a component <code>RemoteTVImpl</code> could simulate a remote TV system:

[[Image:RemoteTVComponent.png|none|thumb|400px|RemoteTVImpl Component]]

Such a <code>RemoteTV</code> component could be a jar file or a shared library. It would contain two service implementations, <code>TVSet</code> and <code>RemoteControl</code>. Once the <code>RemoteTV</code> component is registered with the global service manager, users can call the factory method of the service manager and ask for a <code>TVSet</code> or a <code>RemoteControl</code> service. Then they could use their functionality over the interfaces <code>XPower</code>, <code>XChannel</code> and <code>XStandby</code>. When a new implementation of these services with better performance or new features is available later on, the old component can be replaced without breaking existing code, provided that the new features are introduced by adding interfaces.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/ProUNO/Interfaces

2008-10-05T19:34:47Z

Cking:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2a=block
|ProUNO2aDTypes=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/The Any Type
|NextPage=Documentation/DevGuide/ProUNO/Services
}}
[[zh:Zh/Documentation/DevGuide/ProUNO/Interfaces]]
{{DISPLAYTITLE:Interfaces}}

Communication between UNO objects is based on object interfaces. Interfaces can be seen from the outside or the inside of an object.

From the ''outside'' of an object, an interface provides a functionality or special aspect of the object. Interfaces provide access to objects by publishing a set of operations that cover a certain aspect of an object ''without telling anything about its internals''.

The concept of interfaces is quite natural and frequently used in everyday life. Interfaces allow the creation of things that fit in with each other without knowing internal details about them. A power plug that fits into a standard socket or a one-size-fits-all working glove are simple examples. They all work by standardizing the minimal conditions that must be met to make things work together.

A more advanced example would be the "remote control aspect" of a simple TV system. One possible feature of a TV system is a remote control. The remote control functions can be described by an <code>XPower</code> and an <code>XChannel</code> interface. The illustration below shows a <code>RemoteControl</code> object with these interfaces:

[[Image:RemoteControlImpl.png|none|thumb|350px|RemoteControl service]]

The <code>XPower</code> interface has the functions <code>turnOn()</code> and <code>turnOff()</code> to control the power and the <code>XChannel</code> interface has the functions <code>select()</code>, <code>next()</code>, <code>previous()</code> to control the current channel. The user of these interfaces does not care if he uses an original remote control that came with a TV set or a universal remote control as long as it carries out these functions. The user is only dissatisfied if some of the functions promised by the interface do not work with a remote control.

From the ''inside'' of an object, or from the perspective of someone who implements a UNO object, interfaces are abstract specifications. The abstract specification of all the interfaces in the {{PRODUCTNAME}} API has the advantage that user and implementer can enter into a contract, agreeing to adhere to the interface specification. A program that strictly uses the {{PRODUCTNAME}} API according to the specification will always work, while an implementer can do whatever he wants with his objects, as long as he serves the contract.

UNO uses the <code>interface</code> type to describe such aspects of UNO objects. By convention, all interface names start with the letter X to distinguish them from other types. All interface types must inherit the <idl>com.sun.star.uno.XInterface</idl> root interface, either directly or in the inheritance hierarchy. <code>XInterface</code> is explained in [[Documentation/DevGuide/ProUNO/Using UNO Interfaces|Using UNO Interfaces]]. The <code>interface</code> types define ''methods'' (sometimes also called ''operations'') to provide access to the specified UNO objects.

Interfaces allow access to the data inside an object through dedicated methods (member functions) which encapsulate the data of the object. The methods always have a parameter list and a return value, and they may define exceptions for smart error handling.

The exception concept in the OpenOffice.org API is comparable with the exception concepts known from Java or C++. All operations can raise <idls>com.sun.star.uno.RuntimeException</idls> without explicit specification, but all other exceptions must be specified. UNO exceptions are explained in the section [[Documentation/DevGuide/ProUNO/Exception Handling|Exception Handling]].

Consider the following two examples for interface definitions in UNOIDL (UNO Interface Definition Language) notation. UNOIDL interfaces resemble Java interfaces, and methods look similar to Java method signatures. However, note the flags in square brackets in the following example:

<source lang="idl">// base interface for all UNO interfaces
interface XInterface
{
any queryInterface( [in] type aType );
[oneway] void acquire();
[oneway] void release();

};

// fragment of the Interface com.sun.star.io.XInputStream

interface XInputStream: com::sun::star::uno::XInterface
{
long readBytes( [out] sequence<byte> aData,
[in] long nBytesToRead )
raises( com::sun::star::io::NotConnectedException,
com::sun::star::io::BufferSizeExceededException,
com::sun::star::io::IOException);
...
};
</source>
The <code>[oneway]</code> flag indicates that an operation can be executed asynchronously if the underlying method invocation system does support this feature. For example, a UNO Remote Protocol (URP) bridge is a system that supports oneway calls.

{{Documentation/Caution|Although there are no general problems with the specification and the implementation of the UNO <tt>oneway</tt> feature, there are several API remote usage scenarios where <tt>oneway</tt> calls cause deadlocks in {{PRODUCTNAME}}. Therefore, do not introduce new <tt>oneway</tt> methods with new {{PRODUCTNAME}} UNO APIs.}}

There are also parameter flags. Each parameter definition begins with one of the direction flags in, out, or inout to specify the use of the parameter:

* <code>in</code> specifies that the parameter will be used as an input parameter only
* <code>out</code> specifies that the parameter will be used as an output parameter only
* <code>inout</code> specifies that the parameter will be used as an input and output parameter

These parameter flags do not appear in the API reference. The fact that a parameter is an <code>[out]</code> or <code>[inout]</code> parameter is explained in the method details.

Interfaces consisting of methods form the basis for service specifications.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Talk:Documentation/DevGuide/FirstSteps/Using Services

2008-10-05T19:22:05Z

Cking: New page: I [http://msdn.microsoft.com/en-us/library/ms973861.aspx read] that "multiple-inheritance interfaces" is more properly called "multiple interface implementation", so I made the change.--~~...

Documentation/DevGuide/FirstSteps/Using Services

2008-10-05T19:19:42Z

Cking: Created "Multiple Interface Implementation" section out of what was on the page.

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services
|NextPage=Documentation/DevGuide/FirstSteps/Example: Working with a Spreadsheet Document
}}
{{DISPLAYTITLE:Using Services}}
The concepts of interfaces and services were introduced for the following reasons:

'''Interfaces and services separate specification from implementation'''
: The specification of an interface or service is ''abstract'', that is, it does not define how objects supporting a certain functionality do this ''internally''. Through the abstract specification of the {{OOo}} API, it is possible to pull the implementation out from under the API and install a different implementation if required.

'''Service names allow to create instances by specification name, not by class names'''
: In Java or C++ you use the new operator to create a class instance. This approach is restricted: the class you get is hard-coded. You cannot later on exchange it by another class without editing the code. The concept of services solves this. The central object factory in {{OOo}}, the global service manager, is asked to create an object that can be used for a certain purpose without defining its internal implementation. This is possible because a service can be ordered from the factory by its ''service name'' and the factory decides which service implementation it returns. Which implementation you get makes no difference, you only use the well-defined interface of the service.

===Multiple Interface Implementation===
Abstract interfaces are more reusable if they are fine-grained, i.e., if they are small and describe only a single aspect of an object. To describe the many aspects of an object, objects can implement more than one of these fine-grained interfaces. This "multiple interface implementation" allows same aspects of similar objects accessed with the same code. For example, many objects support text: text may be found in the body of a document, in text frames, in headers and footers, footnotes, table cells, and in drawing shapes. These objects all support the same interface, so a procedure can use, for example, getText() to retrieve text from ''any'' of them.

Services, interfaces, and methods are illustrated in the figure below for the old-style service <idl>com.sun.star.text.TextDocument</idl>, shown using [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] notation. In this figure, services are shown on the left side. The arrow between services indicates that one service provided by the upper (arrowhead) service are inherited by the lower service. Interfaces exported by these services are shown on the right. All interface names in the {{OOo}} API start with an X, so as to be distinguishable from the names of other entities. Each interface contains methods, which are listed beneath the interface.

[[Image:TextDocumentWithMethods.png|none|thumb|450px|Figure. TextDocument inherits the methods of OfficeDocument.]]

A <code>TextDocument</code> object provides the <idl>com.sun.star.text.TextDocument</idl> service, which implements the interfaces, <code>XTextDocument</code>, <code>XSearchable</code>, and <code>XRefreshable</code>. These interfaces provide, for example, the methods <code>getText()</code>, for adding text to a document, and <code>findAll()</code>, for searching the document.

As indicated by the arrow, the <idl>com.sun.star.text.TextDocument</idl> service also inherits all the interfaces provided by the <idl>com.sun.star.document.OfficeDocument</idl> service, so these interfaces are also provided to a <code>TextDocument</code> object. These interfaces handle tasks common to the {{OOo}} applications: printing, <code>XPrintable</code>; storing, <code>XStorable</code>; modifying, <code>XModifiable</code>; and model handling, <code>XModel</code>.

The interfaces shown in the figure are only the mandatory interfaces of a <code>TextDocument</code> object. A <code>TextDocument</code> has optional properties and interfaces, among them the properties <code>CharacterCount</code>, <code>ParagraphCount</code> and <code>WordCount</code>, and the interface <code>XPropertySet</code>, which must be supported if properties are present at all. The implementation of the <code>TextDocument</code> service in {{OOo}} supports both required and all optional interfaces as well. The usage of a <code>TextDocument</code> is described thoroughly in [[Documentation/DevGuide/Text/Text Documents|Text Documents]].

===Using Interfaces===


The fact that every UNO object must be accessed through its interfaces has an effect in languages like Java and C++, where the compiler needs the correct type of an object reference before you can call a method from it. In Java or C++, you normally just cast an object before you access an interface it implements. When working with UNO objects this is different: You must ask the UNO environment to get the appropriate reference for you whenever you want to access methods of an interface which your object supports, but your compiler does not yet know about. Only then you can cast it safely.

The Java UNO environment has a method <code>queryInterface()</code> for this purpose. It looks complicated at first sight, but once you understand that <code>queryInterface()</code> is about safe casting of UNO types across process boundaries, you will soon get used to it. Take a look at the second example FirstLoadComponent.java (in the sample directory, if you have installed the SDK on your computer), where a new Desktop object is created and, afterwards, the <idlm>queryInterface</idlm>() method is used to get the <idls>com.sun.star.frame.XComponentLoader</idls> interface.

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);

XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

We asked the service manager to create a <idl>com.sun.star.frame.Desktop</idl> using its factory method createInstanceWithContext(). This method is defined to return a Java Object type, which should not surprise you—after all the factory must be able to return any type:

<source lang="java">
java.lang.Object createInstanceWithContext(String serviceName, XComponentContext context)
</source>

The object we receive is a <idl>com.sun.star.frame.Desktop</idl> service. The point is, while we know that the object we ordered at the factory is a DesktopUnoUrlResolver and exports among other interfaces the interface <code>XComponentLoader</code>, the compiler does ''not''. Therefore, we have to use the UNO runtime environment to ask or ''query'' for the interface <code>XComponentLoader</code>, since we want to use the <code>loadComponentFromURL()</code> method on this interface. The method <code>queryInterface()</code> makes sure we get a reference that can be cast to the needed interface type, no matter if the target object is a local or a remote object. There are two <code>queryInterface</code> definitions in the Java UNO language binding:

<source lang="java">
java.lang.Object UnoRuntime.queryInterface(java.lang.Class targetInterface, Object sourceObject)
java.lang.Object UnoRuntime.queryInterface(com.sun.star.uno.Type targetInterface, Object sourceObject)
</source>

Since <code>UnoRuntime.queryInterface()</code> is specified to return a java.lang.Object just like the factory method <code>createInstanceWithContext()</code>, we still must explicitly cast our interface reference to the needed type. The difference is that after <code>queryInterface()</code> we can safely cast the object to our interface type and, most important, that the reference will now work even with an object in another process. Here is the <code>queryInterface()</code> call, explained step by step:

<source lang="java">
XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

<code>XComponentLoader</code> is the interface we want to use, so we define a <code>XComponentLoader</code> variable named <code>xComponentLoader</code> (lower x) to store the interface we expect from <code>queryInterface</code>.
Then we query our desktop object for the <code>XComponentLoader</code> interface, passing in <code>XComponentLoader.class</code> as target interface and desktop as source object. Finally we cast the outcome to <code>XComponentLoader</code> and assign the resulting reference to our variable <code>xComponentLoader</code>.
If the source object does not support the interface we are querying for, <code>queryInterface()</code> will return null.

In Java, this call to <code>queryInterface()</code> is necessary whenever you have a reference to an object which is known to support an interface that you need, but you do not have the proper reference type yet. Fortunately, you are not only allowed to <code>queryInterface()</code> from <code>java.lang.Object</code> source types, but you may also query an interface from another interface reference, like this:

<source lang="java">
// loading a blank spreadsheet document gives us its XComponent interface:
XComponent xComponent = xComponentLoader.loadComponentFromURL(
"private:factory/scalc", "_blank", 0, loadProps);

// now we query the interface XSpreadsheetDocument from xComponent
XSpreadsheetDocument xSpreadsheetDocument = (XSpreadsheetDocument)UnoRuntime.queryInterface(
XSpreadsheetDocument.class, xComponent);
</source>

Furthermore, if a method is defined in such a way that it already returns an interface type, you do not need to query the interface, but you can use its methods right away. In the snippet above, the method <code>loadComponentFromURL</code> is specified to return an <idl>com.sun.star.lang.XComponent</idl> interface, so you may call the <code>XComponent</code> methods <code>addEventListener()</code> and <code>removeEventListener()</code> directly at the <code>xComponent</code> variable, if you want to be notified that the document is being closed.
The corresponding step in C++ is done by a <code>Reference<></code> template that takes the source instance as parameter:

<source lang="java">
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
</source>

In {{OOo}} Basic, querying for interfaces is not necessary; the Basic runtime engine takes care of that internally.
With the proliferation of multiple-inheritance interfaces in the {{OOo}} API, there will be less of a demand to explicitly query for specific interfaces in Java or C++. For example, with the hypothetical interfaces

<source lang="idl">
interface XBase1 { void fun1();
};
interface XBase2 {
void fun2();
};
interface XBoth { // inherits from both XBase1 and XBase2
interface XBase1;
interface XBase2;
};
interface XFactory {
XBoth getBoth();};
</source>

you can directly call both <code>fun1()</code> and <code>fun2()</code> on a reference obtained through <code>XFactory.getBoth()</code>, without querying for either <code>XBase1</code> or <code>XBase2</code>.

===Using Properties===

An object must offer its properties through interfaces that allow you to work with properties. The most basic form of these interfaces is the interface <idl>com.sun.star.beans.XPropertySet</idl>. There are other interfaces for properties, such as <idl>com.sun.star.beans.XMultiPropertySet</idl>, that gets and sets a multitude of properties with a single method call. The <code>XPropertySet</code> is always supported when properties are present in a service.

In <code>XPropertySet</code>, two methods carry out the property access, which are defined in Java as follows:

<source lang="java">
void setPropertyValue(String propertyName, Object propertyValue)
Object getPropertyValue(String propertyName)
</source>

In the FirstLoadComponent example, the <code>XPropertySet</code> interface was used to set the CellStyle property at a cell object. The cell object was a <code>com.sun.star.sheet.SheetCell</code> and therefore supports also the <code>com.sun.star.table.CellProperties</code> service which had a property <code>CellStyle</code>. The following code explains how this property was set:

<source lang="java">
// query the XPropertySet interface from cell object
XPropertySet xCellProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xCell);

// set the CellStyle property
xCellProps.setPropertyValue("CellStyle", "Result");
</source>

You are now ready to start working with a {{PRODUCTNAME}} document.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Example: Hello Text, Hello Table, Hello Shape

2008-10-05T02:09:42Z

Cking:

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/How do I know Which Type I Have?
|NextPage=Documentation/DevGuide/FirstSteps/Common Mechanisms for Text, Tables and Drawings
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Example: Hello Text, Hello Table, Hello Shape]]
{{DISPLAYTITLE:Example: Hello Text, Hello Table, Hello Shape}}
The goal of this section is to give a brief overview of those mechanisms in the {{OOo}} API that are common to all document types. The three main application areas of {{OOo}} are text, tables and drawing shapes. The point is: texts, tables and drawing shapes can occur in all three document types, no matter if you are dealing with a Writer, Calc or Draw/Impress file, but they are treated in the same manner everywhere. When you master the common mechanisms, you will be able to insert and use texts, tables and drawings in all document types.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Element Access

2008-10-05T02:05:06Z

Cking:

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Sequence
|NextPage=Documentation/DevGuide/FirstSteps/How do I know Which Type I Have?
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Element Access]]
{{DISPLAYTITLE:Element Access}}
We have already seen in the section [[Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org|How to get Objects in OpenOffice.org]] that sets of objects can also be provided through element access methods. The three most important kinds of element access interfaces are <idl>com.sun.star.container.XNameContainer</idl>, <idl>com.sun.star.container.XIndexContainer</idl> and <idl>com.sun.star.container.XEnumeration</idl>.

The three element access interfaces are examples of how the fine-grained interfaces of the {{PRODUCTNAME}} API allow consistent object design.

All three interfaces inherit from <code>XElementAccess</code>; therefore, they include the methods

<source lang="java">
type getElementType()
boolean hasElements()
</source>

for finding out basic information about a set of elements. The method <code>hasElements()</code> tells whether or not a set contains any elements at all; the method <code>getElementType()</code> tells which type a set contains. In Java and C++, you can get information about a UNO type through <code>com.sun.star.uno.Type</code>, cf, the Java UNO and the C++ UNO reference.

The <idl>com.sun.star.container.XIndexContainer</idl> and <idl>com.sun.star.container.XNameContainer</idl> interface have a parallel design. Consider both interfaces in UML notation.

[[Image:XNameIndexContainer.png|none|thumb|400px|Indexed and Named Container]]

The <code>XIndexAccess/XNameAccess</code> interfaces are about getting an ''element''. The <code>XIndexReplace/XNameReplace</code> interfaces allow you to ''replace existing'' elements without changing the number of elements in the set, whereas the <code>XIndexContainer/XNameContainer</code> interfaces allow you to ''increase and decrease the number of elements'' by inserting and removing elements.

Many sets of named or indexed objects do not support the whole inheritance hierarchy of <code>XIndexContainer</code> or <code>XNameContainer</code>, because the capabilities added by every subclass are not always logical for any set of elements.

The <code>XEumerationAccess</code> interface works differently from named and indexed containers below the <code>XElementAccess</code> interface. <code>XEnumerationAccess</code> does not provide single elements like <code>XNameAccess</code> and <code>XIndexAccess</code>, but it creates an enumeration of objects which has methods to go to the next element as long as there are more elements.

[[Image:XEnumerationAccess.png|none|thumb|200px|Enumerated Container]]

Sets of objects sometimes support all element access methods, some also support only name, index, or enumeration access. Always look up the various types in the API reference to see which access methods are available.

For instance, the method <code>getSheets()</code> at the interface <idl>com.sun.star.sheet.XSpreadsheetDocument</idl> is specified to return a <idl>com.sun.star.sheet.XSpreadsheets</idl> interface inherited from <code>XNameContainer</code>. In addition, the API reference tells you that the provided object supports the <idl>com.sun.star.sheet.Spreadsheets</idl> service, which defines additional element access interfaces besides <code>XSpreadsheets</code>.

Examples that show how to work with <code>XNameAccess</code>, <code>XIndexAccess</code>, and <code>XEnumerationAccess</code> are provided below.

===Name Access===
The basic interface which hands out elements by name is the <idl>com.sun.star.container.XNameAccess</idl> interface. It has three methods:

<source lang="java">
any getByName( [in] string name)
sequence< string > getElementNames()
boolean hasByName( [in] string name)
</source>

In the FirstLoadComponent.java example above, the method <code>getSheets()</code> returned a <idl>com.sun.star.sheet.XSpreadsheets</idl> interface, which inherits from <code>XNameAccess</code>. Therefore, you could use <code>getByName()</code> to obtain the sheet "MySheet" by name from the <code>XSpreadsheets</code> container:

<source lang="java">
XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets();

Object sheet = xSpreadsheets.getByName("MySheet");
XSpreadsheet xSpreadsheet = (XSpreadsheet)UnoRuntime.queryInterface(
XSpreadsheet.class, sheet);

// use XSpreadsheet interface to get the cell A1 at position 0,0 and enter 42 as value
XCell xCell = xSpreadsheet.getCellByPosition(0, 0);
</source>

Since <code>getByName()</code> returns an any, you have to use <code>AnyConverter.toObject()</code> and/or <code>UnoRuntime.queryInterface()<(code> before you can call methods at the spreadsheet object.

===Index Access===
The interface which hands out elements by index is the <idl>com.sun.star.container.XIndexAccess</idl> interface. It has two methods:

<source lang="java">
any getByIndex( [in] long index)
long getCount()
</source>

The FirstLoadComponent example allows to demonstrate <code>XIndexAccess</code>. The API reference tells us that the service returned by <code>getSheets()</code> is a <idl>com.sun.star.sheet.Spreadsheet</idl> service and supports not only the interface <idl>com.sun.star.sheet.XSpreadsheets</idl>, but <code>XIndexAccess</code> as well. Therefore, the sheets could have been accessed by index and not just by name by performing a query for the <code>XIndexAccess</code> interface from our <code>xSpreadsheets</code> variable:

<source lang="java">
XIndexAccess xSheetIndexAccess = (XIndexAccess)UnoRuntime.queryInterface(
XIndexAccess.class, xSpreadsheets);

Object sheet = XSheetIndexAccess.getByIndex(0);
</source>

===Enumeration Access===
The interface <idl>com.sun.star.container.XEnumerationAccess</idl> creates enumerations that allow traveling across a set of objects. It has one method:

<source lang="java">
com.sun.star.container.XEnumeration createEnumeration()
</source>

The enumeration object gained from <code>createEnumeration()</code> supports the interface <idl>com.sun.star.container.XEnumeration</idl>. With this interface we can keep pulling elements out of the enumeration as long as it has more elements. <code>XEnumeration</code> supplies the methods:

<source lang="java">
booleanhasMoreElements()
any nextElement()
</source>

which are meant to build loops such as:

<source lang="java">
while (xCells.hasMoreElements()) {

Object cell = xCells.nextElement();
// do something with cell
}
</source>

For example, in spreadsheets you have the opportunity to find out which cells contain formulas. The resulting set of cells is provided as <code>XEnumerationAccess</code>.

The interface that queries for cells with formulas is <idl>com.sun.star.sheet.XCellRangesQuery</idl>, it defines (among others) a method

<source lang="java">
XSheetCellRanges queryContentCells(short cellFlags)
</source>

which queries for cells having content as defined in the constants group <idl>com.sun.star.sheet.CellFlags</idl>. One of these cell flags is <code>FORMULA</code>. From <code>queryContentCells()</code> we receive an object with an <idl>com.sun.star.sheet.XSheetCellRanges</idl> interface, which has these methods:

<source lang="java">
XEnumerationAccessgetCells()
StringgetRangeAddressesAsString()
sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses()
</source>

The method <code>getCells()</code> can be used to list all formula cells and the containing formulas in the spreadsheet document from our FirstLoadComponent example, utilizing <code>XEnumerationAccess<code>. 

<source lang="java">
XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface(
XCellRangesQuery.class, sheet);
XSheetCellRanges xFormulaCells = xCellQuery.queryContentCells(
(short)com.sun.star.sheet.CellFlags.FORMULA);

XEnumerationAccess xFormulas = xFormulaCells.getCells();
XEnumeration xFormulaEnum = xFormulas.createEnumeration();

while (xFormulaEnum.hasMoreElements()) {

Object formulaCell = xFormulaEnum.nextElement();

// do something with formulaCell
xCell = (XCell)UnoRuntime.queryInterface(XCell.class, formulaCell);
XCellAddressable xCellAddress = (XCellAddressable)UnoRuntime.queryInterface(
XCellAddressable.class, xCell);
System.out.print("Formula cell in column " + xCellAddress.getCellAddress().Column
+ ", row " + xCellAddress.getCellAddress().Row
+ " contains " + xCell.getFormula());
}
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Any

2008-10-05T01:46:31Z

Cking: minor formatting

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Struct
|NextPage=Documentation/DevGuide/FirstSteps/Sequence
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Any]]
{{DISPLAYTITLE:Any}}
The {{OOo}} API frequently uses an <code>any</code> type, which is the counterpart of the <code>Variant</code> type known from other environments. The <code>any</code> type holds one arbitrary UNO type. The <code>any</code> type is especially used in generic UNO interfaces.

Examples for the occurrence of any are the method parameters and return values of the following, frequently used methods:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Interface!!returning an any type!!colspan="2"|taking an any type
|-
|XPropertySet||any getPropertyValue(string propertyName)||colspan="2"|void setPropertyValue(any value)
|-
|XNameContainer||any getByName(string name)||void replaceByName(string name, any element)||void insertByName(string name, any element)
|-
|XIndexContainer||any getByIndex(long index)||void replaceByIndex(long index, any element)||void insertByIndex(long index, any element)
|-
|XEnumeration||any nextElement()||colspan="2"|-
|-
|}

The <code>any</code> type also occurs in the <idl>com.sun.star.beans.PropertyValue</idl> struct.

[[Image:PropertyValue.png|none|thumb|200px|PropertyValue]]

This <code>struct</code> has two member variables, <code>Name</code> and <code>Value</code>, and is ubiquitous in sets of <code>PropertyValue</code> structs, where every <code>PropertyValue</code> is a name-value pair that describes a property by name and value. If you need to set the value of such a <code>PropertyValue struct</code>, you must assign an <code>any</code> type, and you must be able to interpret the contained <code>any</code>, if you are reading from a <code>PropertyValue</code>. How this is done depends on your language.

In Java, the <code>any</code> type is mapped to <code>java.lang.Object</code>, but there is also a special Java class <code>com.sun.star.uno.Any</code>, mainly used in those cases where a plain <code>Object</code> would be ambiguous. There are two simple rules of thumb to follow:

: 1. When you are supposed to pass in an <code>any</code> value, always pass in a <code>java.lang.Object</code> or a Java UNO object.

For instance, if you use <code>setPropertyValue()</code> to set a property that has a non-interface type in the target object, you must pass in a <code>java.lang.Object</code> for the new value. If the new value is of a primitive type in Java, use the corresponding <code>Object</code> type for the primitive type:

<source lang="java">
xCellProps.setPropertyValue("CharWeight", new Double(200.0));
</source>

Another example would be a <code>PropertyValue</code> struct you want to use for <code>loadComponentFromURL</code>:

<source lang="java">
com.sun.star.beans.PropertyValue aProperty = new com.sun.star.beans.PropertyValue();
aProperty.Name = "ReadOnly";
aProperty.Value = Boolean.TRUE;
</source>

: 2. When you ''receive'' an <code>any</code> instance, always use the <code>com.sun.star.uno.AnyConverter</code> to retrieve its value.

The <code>AnyConverter</code> requires a closer look. For instance, if you want to get a property which contains a primitive Java type, you must be aware that <code>getPropertyValue()</code> returns a <code>java.lang.Object</code> containing your primitive type wrapped in an any value. The <code>com.sun.star.uno.AnyConverter</code> is a converter for such objects. Actually it can do more than just conversion, you can find its specification in the Java UNO reference. The following list sums up the conversion functions in the <code>AnyConverter</code>:

<source lang="java">
static java.lang.Object toArray(java.lang.Object object)
static boolean toBoolean(java.lang.Object object)
static byte toByte(java.lang.Object object)
static char toChar(java.lang.Object object)
static double toDouble(java.lang.Object object)
static float toFloat(java.lang.Object object)
static int toInt(java.lang.Object object)
static long toLong(java.lang.Object object)
static java.lang.Object toObject(Class clazz, java.lang.Object object)
static java.lang.Object toObject(Type type, java.lang.Object object)
static short toShort(java.lang.Object object)
static java.lang.String toString(java.lang.Object object)
static Type toType(java.lang.Object object)
static int toUnsignedInt(java.lang.Object object)
static long toUnsignedLong(java.lang.Object object)
static short toUnsignedShort(java.lang.Object object)
</source>

Its usage is straightforward:

<source lang="java">
import com.sun.star.uno.AnyConverter;
long cellColor = AnyConverter.toLong(xCellProps.getPropertyValue("CharColor"));
</source>

For convenience, for interface types you can directly use <code>UnoRuntime.queryInterface()</code> without first calling <code>AnyConverter.getObject()</code>:

<source lang="java">
import com.sun.star.uno.AnyConverter;import com.sun.star.uno.UnoRuntime;
Object ranges = xSpreadsheet.getPropertyValue("NamedRanges");
XNamedRanges ranges1 = (XNamedRanges) UnoRuntime.queryInterface(
XNamedRanges.class, AnyConverter.toObject(XNamedRanges.class, r));
XNamedRanges ranges2 = (XNamedRanges) UnoRuntime.queryInterface( XNamedRanges.class, r);
</source>

In {{OOo}} Basic, the <code>any</code> type becomes a Variant:

<source lang="vb">
'OpenOffice.org Basic
Dim cellColor as Variant
cellColor = oCellProps.CharColor
</source>

In C++, there are special operators for the <code>any</code> type:

<source lang="cpp">
//C++ has >>= and <<= for Any (the pointed brackets are always left)
sal_Int32 cellColor;
Any any;
any = rCellProps->getPropertyValue(OUString::createFromAscii( "CharColor" ));
// extract the value from any
any >>= cellColor;
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Struct

2008-10-05T01:33:41Z

Cking: Changed starbasic to OOo Basic

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Common Types
|NextPage=Documentation/DevGuide/FirstSteps/Any
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Struct]]
{{DISPLAYTITLE:Struct}}
Structs in the {{OOo}} API are used to create compounds of other UNO types. They correspond to C structs or Java classes consisting of public member variables only.
While structs do not encapsulate data, they are easier to transport as a whole, instead of marshaling <code>get()</code> and <code>set()</code> calls back and forth. In particular, this has advantages for remote communication.

You gain access to struct members through the . (dot) operator as in

<source lang="java">
aProperty.Name = "ReadOnly";
</source>

In Java, C++ and {{OOo}} Basic, the keyword new instantiates structs. In OLE automation, use <idl>com.sun.star.reflection.CoreReflection</idl> to get a UNO struct. Do not use the service manager to create structs.

<source lang="java">
//In Java:
com.sun.star.beans.PropertyValue aProperty
= new com.sun.star.beans.PropertyValue();
</source>

<source lang="vb">
'In OpenOffice.org Basic
Dim aProperty as new com.sun.star.beans.PropertyValue
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Using Services

2008-10-05T01:22:19Z

Cking: Reworded from the paragraph before the 1st figure through "Using Interfaces"

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services
|NextPage=Documentation/DevGuide/FirstSteps/Example: Working with a Spreadsheet Document
}}
{{DISPLAYTITLE:Using Services}}
The concepts of interfaces and services were introduced for the following reasons:

'''Interfaces and services separate specification from implementation'''
: The specification of an interface or service is ''abstract'', that is, it does not define how objects supporting a certain functionality do this ''internally''. Through the abstract specification of the {{OOo}} API, it is possible to pull the implementation out from under the API and install a different implementation if required.

'''Service names allow to create instances by specification name, not by class names'''
: In Java or C++ you use the new operator to create a class instance. This approach is restricted: the class you get is hard-coded. You cannot later on exchange it by another class without editing the code. The concept of services solves this. The central object factory in {{OOo}} the global service manager, is asked to create an object that can be used for a certain purpose without defining its internal implementation. This is possible, because a service can be ordered from the factory by its ''service name'' and the factory decides which service implementation it returns. Which implementation you get makes no difference, you only use the well-defined interface of the service.

'''Multiple-inheritance interfaces make fine-grained interfaces manageable'''
: Abstract interfaces are more reusable if they are fine-grained, i.e., if they are small and describe only one aspect of an object, not several aspects. But then you need many of them to describe a useful object. Multiple-inheritance interfaces allow to have fine-grained interfaces on the one hand and to manage them easily by forging them into a collection. Since it is quite probable that objects in an office environment will share many aspects, this fine granularity allows the interfaces to be reused and thus to get objects that behave consistently. For instance, it was possible to realize a unified way to handle text, no matter if you are dealing with body text, text frames, header or footer text, footnotes, table cells or text in drawing shapes. It was not necessary to define separate interfaces for all of these purposes.

How services, interfaces, and inheritance interact is illustrated by the old-style service <idl>com.sun.star.text.TextDocument</idl>, shown using [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] notation in the figure below. In this figure, services are shown on the left side. The arrow between services indicates that services provided by the upper (arrowhead) service are passed on to the lower service. Interfaces exported by these services are shown on the right. All interface names in the {{OOo}} API start with an X, so as to be distinguishable from the names of other entities. Each interface contains methods, which are listed beneath the interface.

[[Image:TextDocumentWithMethods.png|none|thumb|450px|Figure. TextDocument inherits the methods of OfficeDocument.]]

A <code>TextDocument</code> object provides the <idl>com.sun.star.text.TextDocument</idl> service, which provides the interfaces, <code>XTextDocument</code>, <code>XSearchable</code>, and <code>XRefreshable</code>. These interfaces provide, for example, the methods <code>getText()</code>, for adding text to a document, and <code>findAll()</code>, for searching the document.

As indicated by the arrow, the <idl>com.sun.star.text.TextDocument</idl> service also includes all the interfaces provided by the <idl>com.sun.star.document.OfficeDocument</idl> service, so these interfaces are also provided to a <code>TextDocument</code> object. These interfaces handle tasks common to the {{OOo}} applications: printing, <code>XPrintable</code>; storing, <code>XStorable</code>; modifying, <code>XModifiable</code>; and model handling, <code>XModel</code>.

The interfaces shown in the figure are only the mandatory interfaces of a <code>TextDocument</code> object. A <code>TextDocument</code> has optional properties and interfaces, among them the properties <code>CharacterCount</code>, <code>ParagraphCount</code> and <code>WordCount</code>, and the interface <code>XPropertySet</code>, which must be supported if properties are present at all. The implementation of the <code>TextDocument</code> service in {{OOo}} supports both required and all optional interfaces as well. The usage of a <code>TextDocument</code> is described thoroughly in [[Documentation/DevGuide/Text/Text Documents|Text Documents]].

===Using Interfaces===


The fact that every UNO object must be accessed through its interfaces has an effect in languages like Java and C++, where the compiler needs the correct type of an object reference before you can call a method from it. In Java or C++, you normally just cast an object before you access an interface it implements. When working with UNO objects this is different: You must ask the UNO environment to get the appropriate reference for you whenever you want to access methods of an interface which your object supports, but your compiler does not yet know about. Only then you can cast it safely.

The Java UNO environment has a method <code>queryInterface()</code> for this purpose. It looks complicated at first sight, but once you understand that <code>queryInterface()</code> is about safe casting of UNO types across process boundaries, you will soon get used to it. Take a look at the second example FirstLoadComponent.java (in the sample directory, if you have installed the SDK on your computer), where a new Desktop object is created and, afterwards, the <idlm>queryInterface</idlm>() method is used to get the <idls>com.sun.star.frame.XComponentLoader</idls> interface.

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);

XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

We asked the service manager to create a <idl>com.sun.star.frame.Desktop</idl> using its factory method createInstanceWithContext(). This method is defined to return a Java Object type, which should not surprise you—after all the factory must be able to return any type:

<source lang="java">
java.lang.Object createInstanceWithContext(String serviceName, XComponentContext context)
</source>

The object we receive is a <idl>com.sun.star.frame.Desktop</idl> service.

The following figure is a simplified specification in UML notation showing the relation to the <idl>com.sun.star.frame.Frame</idl> service and the supported interfaces.The point is, while we know that the object we ordered at the factory is a DesktopUnoUrlResolver and exports among other interfaces the interface <code>XComponentLoader</code>, the compiler does ''not''. Therefore, we have to use the UNO runtime environment to ask or ''query'' for the interface <code>XComponentLoader</code>, since we want to use the <code>loadComponentFromURL()</code> method on this interface. The method <code>queryInterface()</code> makes sure we get a reference that can be cast to the needed interface type, no matter if the target object is a local or a remote object. There are two <code>queryInterface</code> definitions in the Java UNO language binding:

<source lang="java">
java.lang.Object UnoRuntime.queryInterface(java.lang.Class targetInterface, Object sourceObject)
java.lang.Object UnoRuntime.queryInterface(com.sun.star.uno.Type targetInterface, Object sourceObject)
</source>

Since <code>UnoRuntime.queryInterface()</code> is specified to return a java.lang.Object just like the factory method <code>createInstanceWithContext()</code>, we still must explicitly cast our interface reference to the needed type. The difference is that after <code>queryInterface()</code> we can safely cast the object to our interface type and, most important, that the reference will now work even with an object in another process. Here is the <code>queryInterface()</code> call, explained step by step:

<source lang="java">
XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

<code>XComponentLoader</code> is the interface we want to use, so we define a <code>XComponentLoader</code> variable named <code>xComponentLoader</code> (lower x) to store the interface we expect from <code>queryInterface</code>.
Then we query our desktop object for the <code>XComponentLoader</code> interface, passing in <code>XComponentLoader.class</code> as target interface and desktop as source object. Finally we cast the outcome to <code>XComponentLoader</code> and assign the resulting reference to our variable <code>xComponentLoader</code>.
If the source object does not support the interface we are querying for, <code>queryInterface()</code> will return null.

In Java, this call to <code>queryInterface()</code> is necessary whenever you have a reference to an object which is known to support an interface that you need, but you do not have the proper reference type yet. Fortunately, you are not only allowed to <code>queryInterface()</code> from <code>java.lang.Object</code> source types, but you may also query an interface from another interface reference, like this:

<source lang="java">
// loading a blank spreadsheet document gives us its XComponent interface:
XComponent xComponent = xComponentLoader.loadComponentFromURL(
"private:factory/scalc", "_blank", 0, loadProps);

// now we query the interface XSpreadsheetDocument from xComponent
XSpreadsheetDocument xSpreadsheetDocument = (XSpreadsheetDocument)UnoRuntime.queryInterface(
XSpreadsheetDocument.class, xComponent);
</source>

Furthermore, if a method is defined in such a way that it already returns an interface type, you do not need to query the interface, but you can use its methods right away. In the snippet above, the method <code>loadComponentFromURL</code> is specified to return an <idl>com.sun.star.lang.XComponent</idl> interface, so you may call the <code>XComponent</code> methods <code>addEventListener()</code> and <code>removeEventListener()</code> directly at the <code>xComponent</code> variable, if you want to be notified that the document is being closed.
The corresponding step in C++ is done by a <code>Reference<></code> template that takes the source instance as parameter:

<source lang="java">
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
</source>

In {{OOo}} Basic, querying for interfaces is not necessary; the Basic runtime engine takes care of that internally.
With the proliferation of multiple-inheritance interfaces in the {{OOo}} API, there will be less of a demand to explicitly query for specific interfaces in Java or C++. For example, with the hypothetical interfaces

<source lang="idl">
interface XBase1 { void fun1();
};
interface XBase2 {
void fun2();
};
interface XBoth { // inherits from both XBase1 and XBase2
interface XBase1;
interface XBase2;
};
interface XFactory {
XBoth getBoth();};
</source>

you can directly call both <code>fun1()</code> and <code>fun2()</code> on a reference obtained through <code>XFactory.getBoth()</code>, without querying for either <code>XBase1</code> or <code>XBase2</code>.

===Using Properties===

An object must offer its properties through interfaces that allow you to work with properties. The most basic form of these interfaces is the interface <idl>com.sun.star.beans.XPropertySet</idl>. There are other interfaces for properties, such as <idl>com.sun.star.beans.XMultiPropertySet</idl>, that gets and sets a multitude of properties with a single method call. The <code>XPropertySet</code> is always supported when properties are present in a service.

In <code>XPropertySet</code>, two methods carry out the property access, which are defined in Java as follows:

<source lang="java">
void setPropertyValue(String propertyName, Object propertyValue)
Object getPropertyValue(String propertyName)
</source>

In the FirstLoadComponent example, the <code>XPropertySet</code> interface was used to set the CellStyle property at a cell object. The cell object was a <code>com.sun.star.sheet.SheetCell</code> and therefore supports also the <code>com.sun.star.table.CellProperties</code> service which had a property <code>CellStyle</code>. The following code explains how this property was set:

<source lang="java">
// query the XPropertySet interface from cell object
XPropertySet xCellProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xCell);

// set the CellStyle property
xCellProps.setPropertyValue("CellStyle", "Result");
</source>

You are now ready to start working with a {{PRODUCTNAME}} document.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org

2008-10-05T01:07:55Z

Cking:

{{Documentation/DevGuide/FirstStepsTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/First Contact
|NextPage=Documentation/DevGuide/FirstSteps/Working with Objects
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org]]
{{DISPLAYTITLE:How to get Objects in OpenOffice.org}}
__NOTOC__
An ''object'' in our context is a software artifact that has methods you can call. Objects are required to do something with {{PRODUCTNAME}}. But where do you obtain them?

===New objects===
In general, new objects or objects which are necessary for a first access are created by ''service managers'' in {{PRODUCTNAME}}. In the <code>FirstLoadComponent</code> example, the remote service manager creates the remote <code>Desktop</code> object, which handles application windows and loaded documents in {{PRODUCTNAME}}:

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);
</source>

===Document objects===
Document objects represent the files that are opened with {{PRODUCTNAME}}. They are created by the <code>Desktop</code> object, which has a <code>loadComponentFromURL()</code> method for this purpose.

===Objects that are provided by other objects===
Objects can hand out other objects. There are two cases:

* Features which are designed to be an integral part of the object that provides the feature can be obtained by get methods in the {{PRODUCTNAME}} API. It is common to get an object from a get method. For instance, <code>getSheets()</code> is required for every Calc document, <code>getText()</code> is essential for every Writer Document and <code>getDrawpages()</code> is an essential part of every Draw document. After loading a document, these methods are used to get the Sheets, Text and Drawpages object of the corresponding document. Object-specific get methods are an important technique to get objects.

* Features which are not considered integral for the architecture of an object are accessible through a set of universal methods. In the {{PRODUCTNAME}} API, these features are called properties, and generic methods are used, such as <code>getPropertyValue(String propertyName)</code> to access them. In some cases such a non-integral feature is provided as an object, therefore the method <code>getPropertyValue()</code> can be another source for objects. For instance, page styles for spreadsheets have the properties <code>"RightPageHeaderContent"</code> and <code>"LeftPageHeaderContent"</code>, that contain objects for the page header sections of a spreadsheet document. The generic <code>getPropertyValue()</code> method can sometimes provide an object you need.

===Sets of objects===
Objects can be elements in a set of similar objects. In sets, to access an object you need to know how to get a particular element from the set. The {{PRODUCTNAME}} API allows four ways to provide an element in a set. The first three ways are objects with element access methods that allow access by name, index, or enumeration. The fourth way is a sequence of elements which has no access methods but can be used as an array directly. How these sets of elements are used will be discussed later.

The designer of an object decides which of those opportunities to offer, based on special conditions of the object, such as how it performs remotely or which access methods best work with implementation.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Using Services

2008-10-04T22:18:23Z

Cking: Worked on readability.

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services
|NextPage=Documentation/DevGuide/FirstSteps/Example: Working with a Spreadsheet Document
}}
{{DISPLAYTITLE:Using Services}}
The concepts of interfaces and services were introduced for the following reasons:

'''Interfaces and services separate specification from implementation'''
: The specification of an interface or service is ''abstract'', that is, it does not define how objects supporting a certain functionality do this ''internally''. Through the abstract specification of the {{PRODUCTNAME}} API, it is possible to pull the implementation out from under the API and install a different implementation if required.

'''Service names allow to create instances by specification name, not by class names'''
: In Java or C++ you use the new operator to create a class instance. This approach is restricted: the class you get is hard-coded. You cannot later on exchange it by another class without editing the code. The concept of services solves this. The central object factory in {{PRODUCTNAME}} the global service manager, is asked to create an object that can be used for a certain purpose without defining its internal implementation. This is possible, because a service can be ordered from the factory by its ''service name'' and the factory decides which service implementation it returns. Which implementation you get makes no difference, you only use the well-defined interface of the service.

'''Multiple-inheritance interfaces make fine-grained interfaces manageable'''
: Abstract interfaces are more reusable if they are fine-grained, i.e., if they are small and describe only one aspect of an object, not several aspects. But then you need many of them to describe a useful object. Multiple-inheritance interfaces allow to have fine-grained interfaces on the one hand and to manage them easily by forging them into a collection. Since it is quite probable that objects in an office environment will share many aspects, this fine granularity allows the interfaces to be reused and thus to get objects that behave consistently. For instance, it was possible to realize a unified way to handle text, no matter if you are dealing with body text, text frames, header or footer text, footnotes, table cells or text in drawing shapes. It was not necessary to define separate interfaces for all of these purposes.

Let us consider the old-style service <idl>com.sun.star.text.TextDocument</idl> in UML notation. A <code>TextDocument</code> service has mandatory interfaces, all of which are depicted in the [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] chart, below. These interfaces express the basic aspects of a text document in {{PRODUCTNAME}}: it contains text; it is searchable and refreshable; it is a model with URL and controller; and it is modifiable, printable and storable. The UML chart shows how this is specified in the API.

[[Image:TextDocumentWithMethods.png|none|thumb|400px|Text Document]]

Every <code>TextDocument</code> object includes, by definition, the services <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.document.OfficeDocument</idl>, shown on the left side of the chart. These services export the interfaces shown on the right side of the chart. Also shown are the methods contained in each interface. All interface names in the {{PRODUCTNAME}} API start with an X to be distinguishable from the names of other entities.

Every <code>TextDocument</code> object must support three interfaces: <code>XTextDocument</code>, <code>XSearchable</code>, and <code>XRefreshable</code>. In addition, because a <code>TextDocument</code> is always an <code>OfficeDocument</code>, it must also support the interfaces <code>XPrintable</code>, <code>XStorable</code>, <code>XModifiable</code> and <code>XModel</code>. The methods contained in these interfaces cover these aspects: printing, storing, modification and model handling.

Note that the interfaces shown in the illustration are only the mandatory interfaces of a <code>TextDocument</code>. A <code>TextDocument</code> has optional properties and interfaces, among them the properties <code>CharacterCount</code>, <code>ParagraphCount</code> and <code>WordCount</code> and the <code>XPropertySet</code> interface which must be supported if properties are present at all. The current implementation of the <code>TextDocument</code> service in {{PRODUCTNAME}} does not only support these interfaces, but all optional interfaces as well. The usage of a <code>TextDocument</code> is described thoroughly in [[Documentation/DevGuide/Text/Text Documents|Text Documents]].

===Using Interfaces===


The fact that every UNO object must be accessed through its interfaces has an effect in languages like Java and C++, where the compiler needs the correct type of an object reference before you can call a method from it. In Java or C++, you normally just cast an object before you access an interface it implements. When working with UNO objects this is different: You must ask the UNO environment to get the appropriate reference for you whenever you want to access methods of an interface which your object supports, but your compiler does not yet know about. Only then you can cast it safely.

The Java UNO environment has a method <code>queryInterface()</code> for this purpose. It looks complicated at first sight, but once you understand that <code>queryInterface()</code> is about safe casting of UNO types across process boundaries, you will soon get used to it. Take a look to the second example FirstLoadComponent  where a new Desktop object is created and afterwards the <idlm>queryInterface</idlm>() method is used to get the <idls>com.sun.star.frame.XComponentLoader</idls> interface.

<source lang="java">
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext);

XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

We asked the service manager to create a <idl>com.sun.star.frame.Desktop</idl> using its factory method createInstanceWithContext(). This method is defined to return a Java Object type, which should not surprise you—after all the factory must be able to return any type:

<source lang="java">
java.lang.Object createInstanceWithContext(String serviceName, XComponentContext context)
</source>

The object we receive is a <idl>com.sun.star.frame.Desktop</idl> service.

The following figure is a simplified specification in UML notation showing the relation to the <idl>com.sun.star.frame.Frame</idl> service and the supported interfaces.The point is, while we know that the object we ordered at the factory is a DesktopUnoUrlResolver and exports among other interfaces the interface <code>XComponentLoader</code>, the compiler does ''not''. Therefore, we have to use the UNO runtime environment to ask or ''query'' for the interface <code>XComponentLoader</code>, since we want to use the <code>loadComponentFromURL()</code> method on this interface. The method <code>queryInterface()</code> makes sure we get a reference that can be cast to the needed interface type, no matter if the target object is a local or a remote object. There are two <code>queryInterface</code> definitions in the Java UNO language binding:

<source lang="java">
java.lang.Object UnoRuntime.queryInterface(java.lang.Class targetInterface, Object sourceObject)
java.lang.Object UnoRuntime.queryInterface(com.sun.star.uno.Type targetInterface, Object sourceObject)
</source>

Since <code>UnoRuntime.queryInterface()</code> is specified to return a java.lang.Object just like the factory method <code>createInstanceWithContext()</code>, we still must explicitly cast our interface reference to the needed type. The difference is that after <code>queryInterface()</code> we can safely cast the object to our interface type and, most important, that the reference will now work even with an object in another process. Here is the <code>queryInterface()</code> call, explained step by step:

<source lang="java">
XComponentLoader xComponentLoader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, desktop);
</source>

<code>XComponentLoader</code> is the interface we want to use, so we define a <code>XComponentLoader</code> variable named <code>xComponentLoader</code> (lower x) to store the interface we expect from <code>queryInterface</code>.
Then we query our desktop object for the <code>XComponentLoader</code> interface, passing in <code>XComponentLoader.class</code> as target interface and desktop as source object. Finally we cast the outcome to <code>XComponentLoader</code> and assign the resulting reference to our variable <code>xComponentLoader</code>.
If the source object does not support the interface we are querying for, <code>queryInterface()</code> will return null.

In Java, this call to <code>queryInterface()</code> is necessary whenever you have a reference to an object which is known to support an interface that you need, but you do not have the proper reference type yet. Fortunately, you are not only allowed to <code>queryInterface()</code> from <code>java.lang.Object</code> source types, but you may also query an interface from another interface reference, like this:

<source lang="java">
// loading a blank spreadsheet document gives us its XComponent interface:
XComponent xComponent = xComponentLoader.loadComponentFromURL(
"private:factory/scalc", "_blank", 0, loadProps);

// now we query the interface XSpreadsheetDocument from xComponent
XSpreadsheetDocument xSpreadsheetDocument = (XSpreadsheetDocument)UnoRuntime.queryInterface(
XSpreadsheetDocument.class, xComponent);
</source>

Furthermore, if a method is defined in such a way that it already returns an interface type, you do not need to query the interface, but you can use its methods right away. In the snippet above, the method <code>loadComponentFromURL</code> is specified to return an <idl>com.sun.star.lang.XComponent</idl> interface, so you may call the <code>XComponent</code> methods <code>addEventListener()</code> and <code>removeEventListener()</code> directly at the <code>xComponent</code> variable, if you want to be notified that the document is being closed.
The corresponding step in C++ is done by a <code>Reference<></code> template that takes the source instance as parameter:

<source lang="java">
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
</source>

In {{PRODUCTNAME}} Basic, querying for interfaces is not necessary, the Basic runtime engine takes care about that internally.
With the proliferation of multiple-inheritance interfaces in the {{PRODUCTNAME}} API, there will be less of a demand to explicitly query for specific interfaces in Java or C++. For example, with the hypothetical interfaces

<source lang="idl">
interface XBase1 { void fun1();
};
interface XBase2 {
void fun2();
};
interface XBoth { // inherits from both XBase1 and XBase2
interface XBase1;
interface XBase2;
};
interface XFactory {
XBoth getBoth();};
</source>

you can directly call both <code>fun1()</code> and <code>fun2()</code> on a reference obtained through <code>XFactory.getBoth()</code>, without querying for either <code>XBase1</code> or <code>XBase2</code>.

===Using Properties===

An object must offer its properties through interfaces that allow you to work with properties. The most basic form of these interfaces is the interface <idl>com.sun.star.beans.XPropertySet</idl>. There are other interfaces for properties, such as <idl>com.sun.star.beans.XMultiPropertySet</idl>, that gets and sets a multitude of properties with a single method call. The <code>XPropertySet</code> is always supported when properties are present in a service.

In <code>XPropertySet</code>, two methods carry out the property access, which are defined in Java as follows:

<source lang="java">
void setPropertyValue(String propertyName, Object propertyValue)
Object getPropertyValue(String propertyName)
</source>

In the FirstLoadComponent example, the <code>XPropertySet</code> interface was used to set the CellStyle property at a cell object. The cell object was a <code>com.sun.star.sheet.SheetCell</code> and therefore supports also the <code>com.sun.star.table.CellProperties</code> service which had a property <code>CellStyle</code>. The following code explains how this property was set:

<source lang="java">
// query the XPropertySet interface from cell object
XPropertySet xCellProps = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xCell);

// set the CellStyle property
xCellProps.setPropertyValue("CellStyle", "Result");
</source>

You are now ready to start working with a {{PRODUCTNAME}} document.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services

2008-10-04T21:19:59Z

Cking: what methods --> which methods

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Working with Objects
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services]]
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
===Objects===

In UNO, an ''object'' is a software artifact that has methods that you can call and attributes that you can get and set. Exactly which methods and attributes an object offers is specified by the set of interfaces it supports.

===Interfaces===

An ''interface'' specifies a set of attributes and methods that together define one single aspect of an object. For instance, the interface <idl>com.sun.star.resource.XResourceBundle</idl> specifies the attribute <code>Parent</code> and the methods <code>getLocale()</code> and <code>getDirectElement()</code>.

<source lang="idl">
module com { module sun { module star { module resource { interfaceXResourceBundle: com::sun::star::container::XNameAccess {
[attribute] XResourceBundle Parent;
com::sun::star::lang::Locale getLocale();
any getDirectElement([in] string key);
};
}; }; }; };
</source>

To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>). Multiple inheritance, the ability to inherit more than one interface, was introduced in {{PRODUCTNAME}} {{OOo2.x}}.

Strictly speaking, interface attributes are not needed in UNO. Each attribute could also be expressed as a combination of one method to get the attribute's value, and another method to set it (or just one method to get the value for a read-only attribute). However, there are at least two good reasons for the inclusion of interface attributes in UNO: First, the need for such combinations of getting and setting a value seems to be widespread enough to warrant extra support. Second, with attributes, a designer of an interface can better express nuances among the different features of an object. Attributes can be used for those features that are not considered integral or structural parts of an object, while explicit methods are reserved to access the core features.
Historically, a UNO object typically supported a set of many independent interfaces, corresponding to its many different aspects. With multiple-inheritance interfaces, there is less need for this, as an object may now support just one interface that inherits from all the other interfaces that make up the object’s various aspects.

===Services===

Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, the underlying concepts have been made cleaner. Unfortunately, this leaves two different meanings for the term “service” within UNO. In the following, we will use the term "new-style service" to denote an entity that conforms to the clarified, {{PRODUCTNAME}}-{{OOo2.x}} service concept, while we use "old-style service" to denote an entity that only conforms to the historical, more vague concept. To make matters even more complicated, the term “service” is often used with still different meanings in contexts outside UNO.

Although technically there should no longer be any need for old-style services, the {{PRODUCTNAME}} API still uses them extensively to remain backwards compatible. Therefore, be prepared to encounter uses of both service concepts in parallel when working with the {{PRODUCTNAME}} API.

A ''new-style service'' is of the form

<source lang="idl">
module com { module sun { module star { module bridge {
serviceUnoUrlResolver: XUnoUrlResolver;
}; }; }; };
</source>

and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) will be available under a certain service name (e.g., "com.sun.star.bridge.UnoUrlResolver") at a component context’s service manager. (Formally, new-style services are called “single-interface–based services.”)

The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].

An ''old-style service'' (formally called an “accumulation-based service”) is of the form

<source lang="idl">
module com { module sun { module star { module frame {serviceDesktop {
service Frame;
interface XDesktop;
interface XComponentLoader;
interface com::sun::star::document::XEventBroadcaster;
};
}; }; }; };
</source>

and is used to specify any of the following:

* The general contract is that, if an object is documented to support a certain old-style service, then you can expect that object to support all interfaces exported by the service itself and any inherited services. For example, the method <idlml>com.sun.star.frame.XFrames:queryFrames</idlml> returns a sequence of objects that should all support the old-style service <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
* Additionally, an old-style service may specify one or more properties, as in

<source lang="idl">
module com { module sun { module star { module frame {service Frame {
interface com::sun::star::frame::XFrame;
interface com::sun::star::frame::XDispatchProvider;
// ...
[property] string Title;
[property, optional] XDispatchRecorderSupplier RecorderSupplier;
// ...
};
}; }; }; };
</source>

: Properties, which are explained in detail in the following section, are similar to interface attributes, in that they describe additional features of an object. The main difference is that interface attributes can be accessed directly, while the properties of an old-style service are typically accessed via generic interfaces like <idl>com.sun.star.beans.XPropertySet</idl>. Often, interface attributes are used to represent integral features of an object, while properties represent additional, more volatile features.

* Some old-style services are intended to be available at a component context’s service manager. For example, the service <idl>com.sun.star.frame.Desktop</idl> can be instantiated at a component context’s service manager under its service name "com.sun.star.frame.Desktop". (The problem is that you cannot tell whether a given old-style service is intended to be available at a component context; using a new-style service instead makes that intent explicit.)

* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)

* Yet other old-style services only list properties, and do not export any interfaces at all. Instead of specifying the interfaces supported by certain objects, as the other kinds of old-style services do, such services are used to document a set of related properties. For example, the service <idl>com.sun.star.document.MediaDescriptor</idl> lists all the properties that can be passed to <idlml>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlml>.

A ''property'' is a feature of an object which is typically not considered an integral or structural part of the object and therefore is handled through generic <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> interface to be prepared to handle all kinds of properties. Typical examples are properties for character or paragraph formatting. With properties, you can set multiple features of an object through a single call to <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/FirstSteps/First Contact

2008-10-04T21:02:38Z

Cking: Replaced "A service always exists in a component context'' with instead of A service always exists in a ''component context''...,

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Configuration
|NextPage=Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/First Contact]]
{{DISPLAYTITLE:First Contact}}
=== Getting Started ===


Since {{PRODUCTNAME}} {{OOo2.x}} it is very simple to get a working environment that offers a transparent use of UNO functionality and of office functionality. The following demonstrates how to write a small program that initializes UNO, which means that it internally connects to an office or starts a new office process if necessary and tells you if it was able to get the office component context that provides the office service manager object. Start the Java IDE or source editor, and enter the following source code for the <code>FirstUnoContact</code> class.

To create and run the example in the NetBeans IDE, use the following steps:

# From the '''File''' menu, select '''New Project'''. Select '''OpenOffice.org''' category and select the '''OpenOffice.org Client Application'''. On the next wizard panel insert '''FirstUnoContact''' as project name and maybe change the package and/or the location path. Press '''Finish''' to create the project.
# Navigate over the project node '''FirstUnoContact''' -> '''Source Packages''' -> ... to the generated '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as shown below 
# Build the project by pressing '''F11''' and run it by pressing '''F6'''

The FirstUnoContact example: 

<source lang="java">
public class FirstUnoContact {
...
public static void main(String[] args) {
try {
// get the remote office component context
com.sun.star.uno.XComponentContext xContext =
com.sun.star.comp.helper.Bootstrap.bootstrap();

System.out.println("Connected to a running office ...");

com.sun.star.lang.XMultiComponentFactory xMCF =
xContext.getServiceManager();

String available = (xMCF != null ? "available" : "not available");
System.out.println( "remote ServiceManager is " + available );
}
catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit(0);
}
}
}
</source>

Whereas in NetBeans the '''OpenOffice.org Client Application''' wizard prepares a working project environment for you, it should be easy possible to integrate the necessary steps in other IDEs as well or run an ant script directly.

An example ant build script couild be as the following: 

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="all" name="FirstUnoContact">

<property name="OFFICE_HOME" value="c:/OpenOffice.org"/>
<property name="OO_SDK_HOME" value="c:/OpenOffice.org_SDK"/>

<target name="init">
<property name="OUTDIR" value="${OO_SDK_HOME}/WINExample.out/class/FirstUnoContact"/>
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes"
files="jurt.jar,unoil.jar,ridl.jar,juh.jar"/>
</path>

<fileset id="bootstrap.glue.code" dir="${OO_SDK_HOME}/classes">
<patternset>
<include name="com/sun/star/lib/loader/*.class"/>
<include name="win/unowinreg.dll"/>
</patternset>
</fileset>

<target name="compile" depends="init">
<mkdir dir="${OUTDIR}"/>
<javac debug="true" deprecation="true" destdir="${OUTDIR}" srcdir=".">
<classpath refid="office.class.path"/>
</javac>
</target>

<target name="jar" depends="init,compile">
<jar basedir="${OUTDIR}" compress="true"
jarfile="${OUTDIR}/FirstUnoContact.jar">
<exclude name="**/*.java"/>
<exclude name="*.jar"/>
<fileset refid="bootstrap.glue.code"/>
<manifest>
<attribute name="Main-Class" value="com.sun.star.lib.loader.Loader"/>
<section name="com/sun/star/lib/loader/Loader.class">
<attribute name="Application-Class" value="FirstUnoContact"/>
</section>
</manifest>
</jar>
</target>

<target name="all" description="Build everything." depends="init,compile,jar">
<echo message="Application built. FirstUnoContact!"/>
</target>

<target name="run" description="Try running it." depends="init,all">
<java jar="${OUTDIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="clean" description="Clean all build products." depends="init">
<delete>
<fileset dir="${OUTDIR}">
<include name="**/*.class"/>
</fileset>
</delete>
<delete file="${OUTDIR}/FirstUnoContact.jar"/>
</target>

</project>
</source>

For an example that connects to the office with C++, see chapter [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]]. Accessing the office with {{PRODUCTNAME}} Basic is described in [[Documentation/DevGuide/Basic/First Steps with OpenOffice.org Basic|First Steps with OpenOffice.org Basic]].
The next section describes what happens during the connection between a Java program and {{PRODUCTNAME}}

====Service Managers====

UNO introduces the concept of service managers, which can be considered as “factories” that create ''services''. For now, it is sufficient to see services as UNO objects that can be used to perform specific tasks. Later on we will give a more precise definition for the term service.
For example, the following services are available:

''com.sun.star.frame.Desktop''
: maintains loaded documents: is used to load documents, to get the current document, and access all loaded documents

''com.sun.star.configuration.ConfigurationProvider''
: yields access to the {{PRODUCTNAME}} configuration, for instance the settings in the Tools - Options dialog

''com.sun.star.sdb.DatabaseContext''
: holds databases registered with {{PRODUCTNAME}}

''com.sun.star.system.SystemShellExecute''
: executes system commands or documents registered for an application on the current platform

''com.sun.star.text.GlobalSettings''
: manages global view and print settings for text documents

[[Image:Service.png|none|thumb|300px|Service manager]]

A service always has a ''component context'', which consists of the service manager that created the service and other data to be used by the service.

The <code>FirstUnoContact</code> class above is considered a client of the {{PRODUCTNAME}} process, {{PRODUCTNAME}} is the server in this respect. The server has its own component context and its own service manager, which can be accessed from client programs to use the office functionality. The client program initializes UNO and gets the component context from the {{PRODUCTNAME}} process. Internally, this initialization process creates a local service manager, establishes a pipe connection to a running {{PRODUCTNAME}} process (if necessary a new process is started) and returns the remote component context. In the first step this is the only thing you have to know. The <code>com.sun.star.comp.helper.Bootstrap.bootstrap()</code> method initializes UNO and returns the remote component context of a running {{PRODUCTNAME}} process. You can find more details about bootstrapping UNO, the opportunities of different connection types and how to establish a connection to a UNO server process in the [[Documentation/DevGuide/ProUNO/UNO Concepts|UNO Concepts]].

After this first initialization step, you can use the method <idlm>com.sun.star.uno.XComponentContext:getServiceManager</idlm>() from the component context to get the remote service manager from the {{PRODUCTNAME}} process, which offers you access to the complete office functionality available through the API.

====Failed Connections====


A remote connection can fail under certain conditions:

* Client programs should be able to detect errors. For instance, sometimes the bridge might become unavailable. Simple clients that connect to the office, perform a certain task and exit afterwards should stop their work and inform the user if an error occurred.
* Clients that are supposed to run over a long period of time should not assume that a reference to an initial object will be valid over the whole runtime of the client. The client should resume even if the connection goes down for some reason and comes back later on. When the connection fails, a robust, long running client should stop the current work, inform the user that the connection is not available and release the references to the remote process. When the user tries to repeat the last action, the client should try to rebuild the connection. Do not force the user to restart your program just because the connection was temporarily unavailable.

When the bridge has become unavailable and access is tried, it throws a <idls>com.sun.star.lang.DisposedException</idls>. Whenever you access remote references in your program, catch this Exception in such a way that you set your remote references to null and inform the user accordingly. If your client is designed to run for a longer period of time, be prepared to get new remote references when you find that they are currently null.

A more sophisticated way to handle lost connections is to register a listener at the underlying bridge object. The chapter [[Documentation/DevGuide/ProUNO/UNO Interprocess Connections|UNO Interprocess Connections]] shows how to write a connection-aware client.

{{PDL1}}

[[Category:Documentation/Developer's Guide/First Steps]]

Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment

2008-10-04T19:49:52Z

Cking: Improving readability

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Office Development
|NextPage=Documentation/DevGuide/OfficeDev/Desktop Environment
}}
{{DISPLAYTITLE:{{PRODUCTNAME}} Application Environment}}
The {{PRODUCTNAME}} application environment is made up of the ''desktop environment'' and the ''framework API''.

[[Image:AppEnvironment.png|none|frame|The {{PRODUCTNAME}} Application Environment]]

The desktop environment consists of the desktop and auxiliary objects. The desktop environment's functions are carried out by the framework API. The framework API has two parts: the ''component framework'' and the ''dispatch framework''. The component framework follows a special Frame-Controller-Model paradigm to manage components viewable in {{PRODUCTNAME}}. The dispatch framework handles command requests sent by the GUI.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Using the Desktop

2008-10-04T19:24:57Z

Cking: Increased thumb picture size from 400 to 450 px.

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Dispatch Framework
|NextPage=Documentation/DevGuide/OfficeDev/Using the Component Framework
}}
{{DISPLAYTITLE:Using the Desktop}}

[[Image:framework.png|none|thumb|450px|Desktop Service and Component Framework]]


The <idl>com.sun.star.frame.Desktop</idl> service available at the global service manager includes the service <idl>com.sun.star.frame.Frame</idl>. The Desktop service specification provides three interfaces: <idl>com.sun.star.frame.XDesktop</idl>, <idl>com.sun.star.frame.XComponentLoader</idl> and <idl>com.sun.star.document.XEventBroadcaster</idl>, as shown in the following UML chart:

[[Image:Desktop.png|none|thumb|450px|UML description of the desktop service]]

The interface <idl>com.sun.star.frame.XDesktop</idl> provides access to frames and components, and controls the termination of the office process. It defines the following methods:
<source lang="idl">
com::sun::star::frame::XFrame getCurrentFrame ()
com::sun::star::container::XEnumerationAccess getComponents ()
com::sun::star::lang::XComponent getCurrentComponent ()
boolean terminate ()
void addTerminateListener ( [in] com::sun::star::frame::XTerminateListener xListener)
void removeTerminateListener ( [in] com::sun::star::frame::XTerminateListener xListener)
</source>
The methods <code>getCurrentFrame()</code> and <code>getCurrentComponent()</code> distribute the active frame and document model, whereas <code>getComponents()</code> returns a <idl>com.sun.star.container.XEnumerationAccess</idl> to all loaded documents. For documents loaded in the desktop environment the methods <code>getComponents()</code> and <code>getCurrentComponent()</code> always return the <idl>com.sun.star.lang.XComponent</idl> interface of the document model.

{{Documentation/Tip|If a specific document component is required, but you are not sure whether this component is the current component, use <tt>getComponents()</tt> to get an enumeration of all document components, check each for the existence of the <idl>com.sun.star.frame.XModel</idl> interface and use <tt>getURL()</tt> at <tt>XModel</tt> to identify your document. Since not all components have to support <tt>XModel</tt>, test for <tt>XModel</tt> before calling <tt>getURL()</tt>.}}

The office process is usually terminated when the user selects '''File - Exit''' or after the last application window has been closed. Clients can terminate the office through a call to <code>terminate()</code> and add a terminate listener to veto the shutdown process.


As long as the Windows quickstarter is active, the soffice executable is not terminated.

The following sample shows an <idl>com.sun.star.frame.XTerminateListener</idl> implementation that prevents the office from being terminated when the class <code>TerminationTest</code> is still active:
<source lang="java">
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;

public class TerminateListener implements XTerminateListener {

public void notifyTermination (com.sun.star.lang.EventObject eventObject) {
System.out.println("about to terminate...");
}

public void queryTermination (com.sun.star.lang.EventObject eventObject)
throws TerminationVetoException {

// test if we can terminate now
if (TerminationTest.isAtWork() == true) {
System.out.println("Terminate while we are at work? No way!");
throw new TerminationVetoException() ; // this will veto the termination,
// a call to terminate() returns false
}
}

public void disposing (com.sun.star.lang.EventObject eventObject) {
}
}
</source>
The following class <code>TerminationTest</code> tests the <code>TerminateListener</code> above.
<source lang="java">
import com.sun.star.bridge.XUnoUrlResolver;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lang.XMultiComponentFactory;
import com.sun.star.beans.XPropertySet;
import com.sun.star.beans.PropertyValue;

import com.sun.star.frame.XDesktop;
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;

public class TerminationTest extends java.lang.Object {

private static boolean atWork = false;

public static void main(String[] args) {

XComponentContext xRemoteContext = null;
XMultiComponentFactory xRemoteServiceManager = null;
XDesktop xDesktop = null;

try {
// connect and retrieve a remote service manager and component context
XComponentContext xLocalContext =
com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
Object urlResolver = xLocalServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", xLocalContext );
XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(
XUnoUrlResolver.class, urlResolver );
Object initialObject = xUnoUrlResolver.resolve(
"uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" );
XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, initialObject);
Object context = xPropertySet.getPropertyValue("DefaultContext");
xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(
XComponentContext.class, context);
xRemoteServiceManager = xRemoteContext.getServiceManager();

// get Desktop instance
Object desktop = xRemoteServiceManager.createInstanceWithContext (
"com.sun.star.frame.Desktop", xRemoteContext);
xDesktop = (XDesktop)UnoRuntime.queryInterface(XDesktop.class, desktop);

TerminateListener terminateListener = new TerminateListener ();
xDesktop.addTerminateListener (terminateListener);

// try to terminate while we are at work
atWork = true;
boolean terminated = xDesktop.terminate ();
System.out.println("The Office " +
(terminated == true ? "has been terminated" : "is still running, we are at work"));

// no longer at work
atWork = false;
// once more: try to terminate
terminated = xDesktop.terminate ();
System.out.println("The Office " +
(terminated == true ? "has been terminated" :
"is still running. Someone else prevents termination, e.g. the quickstarter"));
}
catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit(0);
}

}
public static boolean isAtWork() {
return atWork;
}

}
</source>

The office freezes when <code>terminate()</code> is called if there are unsaved changes. As a workaround set all documents into an unmodified state through their <idl>com.sun.star.util.XModifiable</idl> interface or store them using <idl>com.sun.star.frame.XStorable</idl>.

The Desktop offers a facility to load components through its interface <idl>com.sun.star.frame.XComponentLoader</idl>. It has one method:
<source lang="idl">
com::sun::star::lang::XComponent loadComponentFromURL ( [in] string aURL,
[in] string aTargetFrameName,
[in] long nSearchFlags,
[in] sequence < com::sun::star::beans::PropertyValue aArgs > )
</source>
Refer to chapter [[Documentation/DevGuide/OfficeDev/Handling Documents|Handling Documents]] for details about the loading process.

For versions beyond 641, the desktop also provides an interface that allows listeners to be notified about certain document events through its interface <idl>com.sun.star.document.XEventBroadcaster</idl>.
<source lang="idl">
void addEventListener ( [in] com::sun::star::document::XEventListener xListener)
void removeEventListener ( [in] com::sun::star::document::XEventListener xListener)
</source>
The <code>XEventListener</code> must implement a single method (besides <code>disposing()</code>):
<source lang="idl">
[oneway] void notifyEvent ( [in] com::sun::star::document::EventObject Event )
</source>
The struct <idl>com.sun.star.document.EventObject</idl> has a <code>string</code> member <code>EventName</code> that assumes one of the values specified in <idl>com.sun.star.document.Events</idl>. The corresponding events are found on the Events tab of the '''Tools - Configure''' dialog when the option {{PRODUCTNAME}} is selected.

The desktop broadcasts these events for all loaded documents.

The current version of {{PRODUCTNAME}} does not have a GUI element as a desktop. The redesign of the {{PRODUCTNAME}} GUI in StarOffice 5.x and later resulted in the <idl>com.sun.star.frame.Frame</idl> service part of the desktop service is now non-functional. While the <code>XFrame</code> interface can still be queried from the desktop, almost all of its methods are dummy implementations. The default implementation of the desktop object in {{PRODUCTNAME}} is not able to contain a component and refuses to be attached to it, because the desktop is still a frame that is the root for the common hierarchy of all frames in {{PRODUCTNAME}}. The desktop has to be a frame because its <idl>com.sun.star.frame.XFramesSupplier</idl> interface must be passed to [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XFrame.html#setCreator com.sun.star.frame.XFrame:setCreator]() at the child frames, therefore the desktop becomes the parent frame. However, the following functionality of <idl>com.sun.star.frame.Frame</idl> is still in place:

The desktop interface <idl>com.sun.star.frame.XFramesSupplier</idl> offers methods to access frames. This interface inherits from <idl>com.sun.star.frame.XFrame</idl>, and introduces the following methods:
<source lang="idl">
com::sun::star::frame::XFrames getFrames ()
com::sun::star::frame::XFrame getActiveFrame ()
void setActiveFrame ( [in] com::sun::star::frame::XFrame xFrame)
</source>
The method <code>getFrames()</code> returns a <idl>com.sun.star.frame.XFrames</idl> container, that is a <idl>com.sun.star.container.XIndexAccess</idl>, with additional methods to add and remove frames:
<source lang="idl">
void append ( [in] com::sun::star::frame::XFrame xFrame )
sequence < com::sun::star::frame::XFrame > queryFrames ( [in] long nSearchFlags )
void remove ( [in] com::sun::star::frame::XFrame xFrame )
</source>
This <code>XFrames</code> collection is used when frames are added to the desktop to become application windows.

Through <code>getActiveFrame()</code>, you access the active sub-frame of the desktop frame, whereas <code>setActiveFrame()</code> is called by a sub-frame to inform the desktop about the active sub-frame.


The object returned by <code>getFrames()</code> does not support <code>XTypeProvider</code>, therefore it cannot be used with {{PRODUCTNAME}} Basic.

The parent interface of <code>XFramesSupplier</code>, <idl>com.sun.star.frame.XFrame</idl> is functional by accessing the frame hierarchy below the desktop. These methods are discussed in the section [[Documentation/DevGuide/OfficeDev/Frames|Frames]] below:
<source lang="idl">
com::sun::star::frame::XFrame findFrame ( [in] string aTargetFrameName, [in] long nSearchFlags );
boolean isTop ();
</source>
The generic dispatch interface <idl>com.sun.star.frame.XDispatchProvider</idl> executes functions of the internal <code>Desktop</code> implementation that are not accessible through specialized interfaces. Dispatch functions are described by a command URL. The <code>XDispatchProvider</code> returns a dispatch object that dispatches a given command URL. A reference of command URLs supported by the desktop is available on OpenOffice ([http://www.openoffice.org/files/documents/25/60/commands_11beta.html http://www.openoffice.org/files/documents/25/60/commands_11beta.html]). Through the <idl>com.sun.star.frame.XDispatchProviderInterception</idl>, client code intercepts the command dispatches at the desktop. The dispatching process is described in section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]].

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Command URL

2008-10-04T19:16:51Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevDispatch=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Using the Dispatch Framework
|NextPage=Documentation/DevGuide/OfficeDev/Processing Chain
}}
{{DISPLAYTITLE:Command URL}}

In the dispatch framework, every possible user action is defined as an executable ''command'', and every possible visualization as a reflection of something that is exposed by the component is defined as an ''attribute''. Every executable command and every attribute is a feature of the office component, and the dispatch framework gives every feature a name called ''command URL''. It is represented by a <idl>com.sun.star.util.URL</idl> struct.

Command URLs are strings that follow the ''protocol_scheme:protocol_specific_part'' pattern. Public URL schemes, such as ''file:'' or ''http'' can be used here. Executing a request with a URL that points to a location of a document means that this document is loaded. In general, both parts of the command URL can be arbitrary strings, but a request cannot be executed if there is an object that does not know how to handle its command URL.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Dispatch Framework

2008-10-04T18:09:41Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block|OfficeDevFramework=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Windows
|NextPage=Documentation/DevGuide/OfficeDev/Using the Desktop
}}
{{DISPLAYTITLE:Dispatch Framework}}

The dispatch framework is designed to provide uniform access to components for a GUI by using command URLs that mirror menu items, such as '''Edit - Select All''', with various document components. Only the component knows how to execute a command. Similarly, different document components trigger changes in the UI by common commands. For example, a controller might create UI elements like a menu bar, or open a hyperlink.

Command dispatching follows a chain of responsibility. Calls to the dispatch API are moderated by the frame, so all dispatch API calls from the UI to the component and conversely are handled by the frame. The frame passes on the command until an object is found that can handle it. It is possible to restrict, extend or redirect commands at the frame through a different frame implementation or through other components connecting to the frame.

It has already been discussed that frames and controllers have an interface <idl>com.sun.star.frame.XDispatchProvider</idl>. The interface is used to query a dispatch object for a command URL from a frame and have the dispatch object execute the command. This interface is one element of the dispatch framework.

By offering the interception of dispatches through the interface <idl>com.sun.star.frame.XDispatchProviderInterception</idl>, the Frame service offers a method to modify a component's handling of GUI events while keeping its whole API available simultaneously.

{{Documentation/Note|Normally, command URL dispatches go to a target frame, which decides what to do with it. A component can use globally accessible objects like the desktop service to bypass restrictions set by a frame, but this is not recommended. It is impossible to prevent an implementation of components against the design principles, because the framework API is made for components that adhere to its design.}}

The usage of the Dispatch Framework is described in the section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]].

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Controllers

2008-10-04T18:01:15Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevFramework=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Frames
|NextPage=Documentation/DevGuide/OfficeDev/Windows
}}
{{DISPLAYTITLE:Controllers}}

Controllers in {{PRODUCTNAME}} are between a frame and document model. This is their basic role as expressed in <idl>com.sun.star.frame.XController</idl>, which has methods <code>getModel()</code> and <code>getFrame()</code>. The method <code>getFrame()</code> provides the frame that the controller is attached to. The method <code>getModel()</code> returns a document model, but it may return an empty reference if the component does not have a model.

Usually the controller objects support additional interfaces specific to the document type they control, such as <idl>com.sun.star.sheet.XSpreadsheetView</idl> for Calc document controllers or <idl>com.sun.star.text.XTextViewCursorSupplier</idl> for Writer document controllers.

[[Image:FCMController.png|none|thumb|400px|Controller with Model and Frame]]

There can be more than one controller instance with frames of their own controlling the same document model simultaneously. Multiple controllers and frames are created by {{PRODUCTNAME}} when the user clicks '''Window - New Window'''.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Frames

2008-10-04T17:48:31Z

Cking:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevFramework=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Frame-Controller-Model Paradigm in OpenOffice.org
|NextPage=Documentation/DevGuide/OfficeDev/Controllers
}}
{{DISPLAYTITLE:Frames}}
=== Linking Components and Windows ===

The main role of a frame in the Frame-Controller-Model paradigm is to act as a liaison between viewable components and the window system.

Frames can hold one component, or a component and one or more subframes. The following two illustrations depict both possibilities. The first illustration shows a frame containing only a component. It is connected with two window instances: the container window and component window.

[[Image:FCMFrame.png|none|thumb|400px|Frame containing a component]]

When a frame is constructed, the frame must be initialized with a container window using <idlml>com.sun.star.frame.XFrame:initialize</idlml>(). This method expects the <idl>com.sun.star.awt.XWindow</idl> interface of a surrounding window instance, which becomes the container window of the frame. The window instance passed to <code>initialize()</code> must also support <idl>com.sun.star.awt.XTopWindow</idl> to become a container window. The container window must broadcast window events, such as <code>windowActivated()</code>, and appear in front of other windows or be sent to the background. The fact that container windows support <idl>com.sun.star.awt.XTopWindow</idl> does not mean the container window is an independent window of the underlying window system with a title bar and a system menu. An <code>XTopWindow</code> acts as a window if necessary, but it can also be docked or depend on a surrounding application window.

After initializing the frame, a component is set into the frame by a frame loader implementation that loads a component into the frame. It calls <idlml>com.sun.star.frame.XFrame:setComponent</idlml>() that takes another <idl>com.sun.star.awt.XWindow</idl> instance and the <idl>com.sun.star.frame.XController</idl> interface of a controller.Usually the controller is holding a model, therefore the component gets a component window of its own, separate from the container window.

A frame with a component is associated with ''two'' windows: the ''container'' window which is an <code>XTopWindow</code> and the ''component'' window, which is the rectangular area that displays the component and receives GUI events for the component while it is active. When a frame is initialized with an instance of a window in a call to <code>initialize()</code>, this window becomes its container window. When a component is set into a frame using <code>setComponent()</code>, another <idl>com.sun.star.awt.XWindow</idl> instance is passed and becomes the component window.

When a frame is added to the desktop frame hierarchy, the desktop becomes the parent frame of our frame. For this purpose, the <idl>com.sun.star.frame.XFramesSupplier</idl> interface of the desktop is passed to the method <code>setCreator()</code> at the <code>XFrame</code> interface. This happens internally when the method <code>append()</code> is called at the <idl>com.sun.star.frame.XFrames</idl> interface supplied by the desktop.

{{Documentation/Note|A component window can have sub-windows, and that is the case with all documents in {{PRODUCTNAME}}. For instance, a text document has sub-windows for the toolbars and the editable text. Form controls are sub-windows, as well, however, these sub-windows depend on the component window and do not appear in the Frame-Controller-Model paradigm, as discussed above.}}

The second diagram shows a frame with a component and a sub-frame with another component. Each frame has a container window and component window.

[[Image:FCMSubframe.png|none|thumb|400px|Frame containing a component and a sub-frame]]

In the {{PRODUCTNAME}} GUI, sub-frames appear as dependent windows. The sub-frame in the illustration above could be a dockable window, such as the beamer showing the database browser or a floating frame in a document created with '''Insert - Frame'''.

Note that a frame with a component and sub-frame is associated with ''four'' windows. The frame and the sub-frame have a container window and a component window for the component.

When a sub-frame is added to a surrounding frame, the frame becomes the parent of the sub-frame by a call to <code>setCreator()</code> at the sub-frame. This happens internally when the method <code>append()</code> is called at the <idl>com.sun.star.frame.XFrames</idl> interface supplied by the surrounding frame.

The section [[Documentation/DevGuide/OfficeDev/Creating Frames Manually|Creating Frames Manually]] shows examples for the usage of the <code>XFrame</code> interface that creates frames in the desktop environment, constructs dockable and standalone windows, and inserts components into frames.

=== Communication through Dispatch Framework ===

Besides the main role of frames as expressed in the <idl>com.sun.star.frame.XFrame</idl> interface, frames play another role by providing a communication context for the component they contain, that is, every communication from a controller to the desktop environment and the user interface, and conversely, is done through the frame. This aspect of a frame is published through the <idl>com.sun.star.frame.XDispatchProvider</idl> interface, which uses special command requests to trigger actions.

The section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]] discusses the usage of the dispatch API.

=== Components in Frames ===

The desktop environment section discussed the three kinds of viewable components that can be inserted into a frame. If the component has a controller ''and'' a model like a document, or if it has only a controller, such as the bibliography and database browser, it implements the <idl>com.sun.star.frame.Controller</idl> service represented by the interface <idl>com.sun.star.frame.XController</idl>. In the call to <idlml>com.sun.star.frame.XFrame:setComponent</idlml>(), the controller is passed with the component window instance. If the component has no controller, it directly implements <idl>com.sun.star.lang.XComponent</idl> and <idl>com.sun.star.awt.XWindow</idl>. In this case, the component is passed as <code>XWindow</code> parameter, and the <code>XController</code> parameter must be an <code>XController</code> reference set to null.

If the viewable component is a ''trivial component'' (implementing <code>XWindow</code> only), the frame holds a reference to the component window, controls the lifetime of the component and propagates certain events from the container window to the component window. If the viewable component is an ''office component'' (having a controller), the frame adds to these basic functions a set of features for integration of the component into the environment by supporting additional command URLs for the component at its <idl>com.sun.star.frame.XDispatchProvider</idl> interface.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

File:AppEnvironment.png

2008-10-04T17:14:06Z

Cking: uploaded a new version of "Image:AppEnvironment.png": oops.

File:AppEnvironment.png

2008-10-04T17:09:26Z

Cking: uploaded a new version of "Image:AppEnvironment.png": Made smallest font size 12, instead of 14.

Documentation/DevGuide/OfficeDev/Frame-Controller-Model Paradigm in Apache OpenOffice

2008-10-04T16:39:53Z

Cking: dash, semicolons, & commas changed

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevFramework=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Framework API
|NextPage=Documentation/DevGuide/OfficeDev/Frames
}}
{{DISPLAYTITLE:Frame-Controller-Model Paradigm in OpenOffice.org}}

The well-known Model-View-Controller (MVC) paradigm separates three application areas: document data (''model''), presentation (''view'') and interaction (''controller''). {{PRODUCTNAME}} has a similar abstraction, called the Frame-Controller-Model (FCM) paradigm. The FCM paradigm shares certain aspects with MVC, but it has different purposes; therefore, it is best to approach FCM independently from MVC. The model and controller in MVC and FCM are quite different things.

The FCM paradigm in {{PRODUCTNAME}} separates three application areas: document object (''model''), screen interaction with the model (''controller'') and controller-window linkage (''frame'').

* The model holds the document data and has methods to change these data without using a controller object. Text, drawings, and spreadsheet cells are accessed directly at the model.
* The controller has knowledge about the current view status of the document and manipulates the screen presentation of the document, but not the document data. It observes changes made to the model, and can be duplicated to have multiple controllers for the same model.
* The frame contains the controller for a model and ''knows'' the windows that are used with it, but does not have window functionality.

The purpose of FCM is to have three exchangeable parts that are used with an exchangeable window system:

It is possible to write a new controller that presents an existing model in a different manner without changing the model or the frame. A controller depends on the model it presents; therefore, a new controller for a new model can be written.

Developers can introduce new models for new document types without taking care of the frame and underlying window management system. However, since there is no default controller, it is necessary to write a suitable controller also.

By keeping all window-related functionality separate from the frame, it is possible to use one single frame implementation for every possible window in the entire {{PRODUCTNAME}} application. Thus, the presentation of all visible components is customized by exchanging the frame implementation. At runtime you can access a frame and replace the controller, together with the model it controls, by a different controller instance.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/Desktop Environment

2008-10-04T16:30:34Z

Cking: Changed 'Tools-Configure-Events' to "Tools-Customize-Events".

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevUsing=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment
|NextPage=Documentation/DevGuide/OfficeDev/Framework API
}}
{{DISPLAYTITLE:Desktop Environment}}

The <idl>com.sun.star.frame.Desktop</idl> service is the central management instance for the {{PRODUCTNAME}} application framework. All {{PRODUCTNAME}} application windows are organized in a hierarchy of frames that contain viewable components. The desktop is the root frame for this hierarchy. From the desktop you can load viewable components, access frames and components, terminate the office, traverse the frame hierarchy and dispatch command requests.

The name of this service originates at StarOffice 5.x, where all document windows were embedded into a common application window that was occupied by the StarOffice desktop, mirroring the Windows desktop. The root frame of this hierarchy was called the desktop frame. The name of this service and the interface name <idl>com.sun.star.frame.XDesktop</idl> were kept for compatibility reasons.

The desktop object and frame objects use auxiliary services, such as the <idl>com.sun.star.document.TypeDetection</idl> service and other, opaque implementations that interact with the UNO-based office, but are not accessible through the {{PRODUCTNAME}} API. Examples for the latter are the global document event handling and its user interface ('''Tools - Customize - Events'''), and the menu bars that use the dispatch API without being UNO services themselves. The desktop service, together with these surrounding objects, is called the ''desktop environment''.

[[Image:DesktopOverview.png|none|thumb|400px|The Desktop terminates the office and manages components and frames]]

The viewable components managed by the desktop can be three different kinds of objects: full-blown office documents with a document model and controllers, components with a controller but no model, such as the bibliography and database browser, or simple windows without API-enabled controllers, for example, preview windows. The commonality between these types of components is the <idl>com.sun.star.lang.XComponent</idl> interface. Components with controllers are also called office components, whereas simple window components are called trivial components.

Frames in the {{PRODUCTNAME}} API are the connecting link between windows, components and the desktop environment. The relationship between frames and components is discussed in the next section, [[Documentation/DevGuide/OfficeDev/Framework API|Framework API]].

Like all other services, the <idl>com.sun.star.frame.Desktop</idl> service can be exchanged by another implementation that extends the functionality of {{PRODUCTNAME}}. By exchanging the desktop service it is possible to use different kinds of windows or to make {{PRODUCTNAME}} use MDI instead of SDI. This is not an easy thing to do, but it is possible without changing any code elsewhere in {{PRODUCTNAME}}.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment

2008-10-04T15:58:34Z

Cking: Made picture full size, instead of thumb, to the text is clearer.

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Office Development
|NextPage=Documentation/DevGuide/OfficeDev/Desktop Environment
}}
{{DISPLAYTITLE:{{PRODUCTNAME}} Application Environment}}
The {{PRODUCTNAME}} application environment is made up of the ''desktop environment'' and the ''framework API''.

[[Image:AppEnvironment.png|none|{{PRODUCTNAME}} Application Environment]]

The desktop environment consists of the desktop and auxiliary objects. It employs the framework API to carry out its functions. The framework API has two parts: the ''component framework'' and ''dispatch framework''. The component framework follows a special Frame-Controller-Model paradigm to manage components viewable in {{PRODUCTNAME}}. The dispatch framework handles command requests sent by the GUI.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

File:AppEnvironment.png

2008-10-04T15:51:30Z

Cking: uploaded a new version of "Image:AppEnvironment.png": Put the two main components inside the application environment, so they won't appear to be separate components.

Documentation/BASIC Guide/StarDesktop

2008-09-28T19:03:02Z

Cking: Replaced {{OOo}} with OpenOffice.org in filtername value (still seems wrong)

{{DISPLAYTITLE:The StarDesktop}}
{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Documents
|NextPage=Documentation/BASIC Guide/Templates
|docs=block
}}

When working with documents, there are two services which 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.

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. Unlike the old <tt>Application</tt> object however it 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/Note|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 ==
<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 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 <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. Alternatively, <tt>_hidden</tt> can also be specified, and this ensures that the corresponding document is loaded but remains invisible.

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>text.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/Note|<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> and <tt>_hidden</tt> values for the <tt>Frame</tt> parameter ensure 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>FilterOptions (String)</tt>:defines additional options for filters.
;<tt>JumpMark (String)</tt>:once a document has been opened, jumps to the position defined in JumpMark.
;<tt>Password (String)</tt>:transfers a password for a protected file.
;<tt>ReadOnly (Boolean)</tt>:loads a read-only document.

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(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 (OpenOffice.org Calc)"

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

The <tt>FileProperties</tt> data field covers precisely one value because it records one option. The <tt>Filtername</tt> property defines whether {{OOo}} uses a {{OOo}} Calc text filter to open files.

=== 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>FilterOptions (String)</tt>:defines additional options for 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 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(sUrl, mFileProperties())
</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).

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(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
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.

{{PDL1}}

Documentation/BASIC Guide/StarDesktop

2008-09-28T18:11:14Z

Cking: /* Compression of Files */

{{DISPLAYTITLE:The StarDesktop}}
{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Documents
|NextPage=Documentation/BASIC Guide/Templates
|docs=block
}}

When working with documents, there are two services which 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.

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. Unlike the old <tt>Application</tt> object however it 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/Note|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 ==
<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 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 <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. Alternatively, <tt>_hidden</tt> can also be specified, and this ensures that the corresponding document is loaded but remains invisible.

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() 'It is an (empty) array of PropertyValues

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

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

The preceding call opens the <tt>text.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/Note|<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> and <tt>_hidden</tt> values for the <tt>Frame</tt> parameter ensure 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>FilterOptions (String)</tt>:defines additional options for filters.
;<tt>JumpMark (String)</tt>:once a document has been opened, jumps to the position defined in JumpMark.
;<tt>Password (String)</tt>:transfers a password for a protected file.
;<tt>ReadOnly (Boolean)</tt>:loads a read-only document.

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(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 ({{OOo}} Calc)"

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

The <tt>FileProperties</tt> data field covers precisely one value because it records one option. The <tt>Filtername</tt> property defines whether {{OOo}} uses a {{OOo}} Calc text filter to open files.

=== 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>FilterOptions (String)</tt>:defines additional options for 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 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(sUrl, mFileProperties())
</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).

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(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
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.

{{PDL1}}

Documentation/BASIC Guide/StarDesktop

2008-09-28T18:05:24Z

Cking: /* XML File Format */

{{DISPLAYTITLE:The StarDesktop}}
{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Documents
|NextPage=Documentation/BASIC Guide/Templates
|docs=block
}}

When working with documents, there are two services which 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.

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. Unlike the old <tt>Application</tt> object however it 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/Note|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 ==
<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 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 <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]].

== 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. Alternatively, <tt>_hidden</tt> can also be specified, and this ensures that the corresponding document is loaded but remains invisible.

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() 'It is an (empty) array of PropertyValues

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

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

The preceding call opens the <tt>text.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/Note|<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> and <tt>_hidden</tt> values for the <tt>Frame</tt> parameter ensure 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>FilterOptions (String)</tt>:defines additional options for filters.
;<tt>JumpMark (String)</tt>:once a document has been opened, jumps to the position defined in JumpMark.
;<tt>Password (String)</tt>:transfers a password for a protected file.
;<tt>ReadOnly (Boolean)</tt>:loads a read-only document.

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(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 ({{OOo}} Calc)"

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

The <tt>FileProperties</tt> data field covers precisely one value because it records one option. The <tt>Filtername</tt> property defines whether {{OOo}} uses a {{OOo}} Calc text filter to open files.

=== 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>FilterOptions (String)</tt>:defines additional options for 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 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(sUrl, mFileProperties())
</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).

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(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
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.

{{PDL1}}

Documentation/DevGuide/Basic/OpenOffice.org Basic

2008-09-28T16:08:43Z

Cking:

{{Documentation/DevGuide/BasicTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Charts/How to Apply an Add-In to a Chart Document
|NextPage=Documentation/DevGuide/Basic/First Steps with OpenOffice.org Basic
}}
[[zh:Zh/Documentation/DevGuide/Basic/OpenOffice.org Basic]]
{{DISPLAYTITLE:{{OOo}} Basic}}
{{OOo}} Basic is used to create and manage macros and dialogs. The following sections examine the usage of the {{OOo}} Basic programming environment.

* [[Documentation/DevGuide/Basic/First Steps with OpenOffice.org Basic|First Steps with OpenOffice.org Basic]] guides you through the necessary steps to write {{OOo}} Basic UNO Programs.
* [[Documentation/DevGuide/Basic/OpenOffice.org Basic IDE|OpenOffice.org Basic IDE]] provides a reference to the functionality of the {{OOo}} Integrated Development Environment (IDE). It describes:
** The dialogs to manage Basic and dialog libraries.
** The functionality of the Basic IDE window: the Basic macro editor and debugger, and the Dialog editor.
** The assignment of macros to events
* [[Documentation/DevGuide/Basic/Features of OpenOffice.org Basic|Features of OpenOffice.org Basic]] describes the Basic programming language integrated in {{OOo}}, including
** Provides an overview about the general language features built into {{OOo}} Basic.
** Extends the UNO language binding chapter [[Documentation/DevGuide/ProUNO/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] by information on how to access the application specific UNO API.
** Points out threading and rescheduling characteristics of {{OOo}} Basic that differ from other languages, such as, from Java, which can be important under certain circumstances.
* [[Documentation/DevGuide/Basic/Advanced Library Organization|Advanced Library Organization]] describes how the Basic library system stores and manages Basic macros and dialogs in {{OOo}}, and how the user can access libraries and library elements using the appropriate interfaces.
* [[Documentation/DevGuide/Basic/Programming Dialogs and Dialog Controls|Programming Dialogs and Dialog Controls]] describes the toolkit controls used to create dialogs in the dialog editor. In this section the different types of controls and their specific properties are explained in detail.
* [[Documentation/DevGuide/Basic/Creating Dialogs at Runtime|Creating Dialogs at Runtime]] describes how UNO dialogs can be created at runtime without using the dialog editor. This is useful to show dialogs from UNO components. As this is an advanced way to create dialogs, this section goes deeply into the Toolkit interfaces and extends the section [[Documentation/DevGuide/Basic/Programming Dialogs and Dialog Controls|Programming Dialogs and Dialog Controls]].
* [[Documentation/DevGuide/Basic/Library File Structure|Library File Structure]] discusses the various files used by the Basic IDE.
* [[Documentation/DevGuide/Basic/Library Deployment|Library Deployment]] discusses the automatic deployment of Basic libraries into a local or a shared {{OOo}} installation.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Basic and Dialogs]]

Talk:Documentation/DevGuide/Basic/OpenOffice.org Basic

2008-09-28T02:51:51Z

Cking: Title Change

===Title Change===
The previous title of this page was OpenOffice.org Basic and dialogs. Dialogs are part of Basic, so there was no need to include dialogs in the title. Therefore, I renamed the page to just OpenOffice.org Basic, and changed all links on the wiki that referred to the old page. OpenOffice.org Basic. A name you can sink your teeth into.--[[User:Cking|Cking]] 04:51, 28 September 2008 (CEST)

Documentation/DevGuide/Scripting/Scripting Framework

2008-09-28T02:45:42Z

Cking: Updated link to OOo Basic

{{Documentation/DevGuide/ScriptingTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Accessibility/XAccessibleHyperlink
|NextPage=Documentation/DevGuide/Scripting/Using the Scripting Framework
}}
[[zh:Zh/Documentation/DevGuide/Scripting/Scripting Framework]]
{{DISPLAYTITLE:Scripting Framework}}
A {{PRODUCTNAME}} macro is a short program used to automate a number of steps. The Scripting Framework is a new feature in {{PRODUCTNAME}} [VERSION]. It allows users to write and run macros for {{PRODUCTNAME}} in a number of programming and scripting languages including:

* BeanShell (http://www.beanshell.org/)
* JavaScript (http://www.mozilla.org/rhino/)
* Java ([http://www.java.com/ http://www.java.com])
* {{PRODUCTNAME}} Basic [[Documentation/DevGuide/Basic/OpenOffice.org Basic|OpenOffice.org Basic]]
The framework is designed so that developers can add support for new languages.

{{Documentation/Note|In this chapter, the terms ''macro'' and ''script'' are interchangeable.}}

=== Structure of this Chapter ===

This chapter is organized into the following sections:

* Section [[Documentation/DevGuide/Scripting/Using the Scripting Framework|Using the Scripting Framework]] describes the user interface features of the Scripting Framework
** Describes how to run a macro using the Run Macro dialog.
** Describes how to use the Organizer dialogs to create, edit and manage macros.
* Section [[Documentation/DevGuide/Scripting/Writing Macros|Writing Macros]] provides a guide on how to get started with writing Scripting Framework macros
** Describes how to write a simple HelloWorld macro.
** Describes how Scripting Framework macros interact with {{PRODUCTNAME}} and the {{PRODUCTNAME}} API.
** Describes how to create a dialog from a Scripting Framework macro.
** Describes how to compile and deploy a Java macro.
* Section [[Documentation/DevGuide/Scripting/How the Scripting Framework Works|How the Scripting Framework Works]] describes how the plug-able architecture of the Scripting Framework allows support for new scripting languages to be added easily.
* Section [[Documentation/DevGuide/Scripting/Writing a LanguageScriptProvider UNO Component using the Java Helper Classes|Writing a LanguageScriptProvider UNO Component using the Java Helper Classes]] describes how to use the Scripting Framework Java helper classes to add support for a new scripting language
** Describes how to use the ScriptProvider abstract base class.
** Describes how to add editor and management support.
** Describes how to build and register a ScriptProvider.
* Section [[Documentation/DevGuide/Scripting/Writing a LanguageScriptProvider UNO Component From Scratch|Writing a LanguageScriptProvider UNO Component From Scratch]] describes how to write a LanguageScriptProvider UNO component.

=== Who Should Read this Chapter ===

If you are interested in automating {{PRODUCTNAME}} using BeanShell, JavaScript, Java or {{PRODUCTNAME}} Basic then you should read sections [[Documentation/DevGuide/Scripting/Using the Scripting Framework|Using the Scripting Framework]] and [[Documentation/DevGuide/Scripting/Writing Macros|Writing Macros]].

If you are interested in adding support to run and write macros in a language with a Java based interpreter then you should read section [[Documentation/DevGuide/Scripting/Writing a LanguageScriptProvider UNO Component using the Java Helper Classes|Writing a LanguageScriptProvider UNO Component using the Java Helper Classes]].

If you are interested in adding support for a scripting language from scratch then you should read section [[Documentation/DevGuide/Scripting/Writing a LanguageScriptProvider UNO Component From Scratch|Writing a LanguageScriptProvider UNO Component From Scratch]].

{{PDL1}}

[[Category:Documentation/Developer's Guide/Scripting]]

Documentation/DevGuide/Scripting/Basic and Dialogs

2008-09-28T02:44:39Z

Cking: Updated link to OOo Basic

{{Documentation/DevGuide/ScriptingTOC
|Scripting2b=block
|ScriptingEdit=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/JavaScript Editor
|NextPage=Documentation/DevGuide/Scripting/Macro Recording
}}
{{DISPLAYTITLE:Basic and Dialogs}}
The {{PRODUCTNAME}} Basic and Dialog Organizers are described in the [[Documentation/DevGuide/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] chapter.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Scripting]]

Documentation/DevGuide/GUI/Graphical User Interfaces

2008-09-28T02:43:34Z

Cking: Updated link to OOo Basic

{{Documentation/DevGuide/GUITOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Integration with Extension Manager
|NextPage=Documentation/DevGuide/GUI/Exception Handling
}}
[[zh:Zh/Documentation/DevGuide/GUI/Graphical User Interfaces]]
{{DISPLAYTITLE:Graphical User Interfaces}}
The <idlmodule>com.sun.star.awt</idlmodule> API-module is used to access and design user interface features. The concepts that this module are based on are similar to java.awt. This module provides services and interfaces to create and handle the large set of GUI elements that are demanded by today's modern components. This chapter is directed to extension developers who want to add functionality to their {{PRODUCTNAME}} application and want to create a consistent user interface.

=== Implementation Details ===

You can use the UNO module Abstract Window Toolkit (UNO-AWT) to create a graphical user interface. The concept of UNO-AWT is based on Java/AWT. Java provides the AWT and Swing user interface design packages within its Java Foundation Classes class library. The implementation of java.awt components is based on the implementation of the peer components of the operating system. This is known as a "heavyweight" implementation. <idlmodule>com.sun.star.awt</idlmodule> components are lightweight controls because their implementation is based solely on {{PRODUCTNAME}}. This gives you platform independence. The functionality of heavyweight controls may only be as high as the lowest common denominator of all involved operating systems, however, OpenOffice UI components are meant to emulate the design of the corresponding components of the operating system. The layer responsible for this is called VCL or Visual Class Library. The layer on top of the VCL is the Toolkit layer. This layer maps all interfaces of <idlmodule>com.sun.star.awt</idlmodule> to VCL.

=== Basic Concepts ===

The basic concepts that are used in <idlmodule>com.sun.star.awt</idlmodule> are described in previous chapters:

* [[Documentation/DevGuide/ProUNO/Event Model|Event Model]] describes how to use event listeners at controls. With Event-Listeners at controls you can determine how a window reacts to mouse or keyboard driven events.
* [[Documentation/DevGuide/ProUNO/Exceptions|Exceptions]] explains how to handle errors as Exceptions.
* [[Documentation/DevGuide/ProUNO/Introduction|Introduction]] describes factories.
* [[Documentation/DevGuide/ProUNO/Data Types|Data Types]] describes the basic UNO types, and provides information about how to convert these types to and from various target languages.
* [[Documentation/DevGuide/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] provides information for developers who want to implement Basic macros.
* [[Documentation/DevGuide/WritingUNO/Accessing Dialogs|Accessing Dialogs]] explains how dialogs created with the dialog engine can be embedded within {{PRODUCTNAME}} extensions.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Graphical User Interfaces]]