Apache OpenOffice Wiki - User contributions [en]

Documentation/DevGuide/OfficeDev/Frames

2009-06-14T06:40:54Z

OOoLerner:

{{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
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
{{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]]

Documentation/DevGuide/OfficeDev/Desktop Environment

2009-06-13T16:19:21Z

OOoLerner:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|OfficeDevUsing=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/OpenOffice.org Application Environment
|NextPage=Documentation/DevGuide/OfficeDev/Framework API
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
{{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/FirstSteps/Objects, Interfaces, and Services

2009-03-15T12:05:33Z

OOoLerner: /* Interfaces */

{{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 { interface XResourceBundle: 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

2009-03-15T11:21:25Z

OOoLerner:

{{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 and build 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 a Java IDE or source editor, and enter the source code for the [[#FirstUnoContactClass|<tt>FirstUnoContact</tt>]] class. In order to automate the build process one may use an [[#AntBuildScript|Ant build script]] as shown below.

==== Using the NetBeans IDE ====

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 [[#FirstUnoContractClass|shown below]] 
# Build the project by pressing '''F11''' and run it by pressing '''F6'''

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

==== Using the Eclipse IDE ====

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

# From the '''File''' menu, select '''New > Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab, where you may add the necessary libraries as described in section [[Documentation/DevGuide/FirstSteps/Configuration#Prepare the Eclipse IDE|Prepare the Eclipse IDE]]. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New > Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as [[#FirstUnoContractClass|shown below]].
# Right click on the project node '''FirstUnoContact''', select '''New > File''' to create the '''build.xml''' file.
# Enter the code for the Ant build script as [[#AntBuildScript|shown below]].
# From the '''Run''' menu, select '''External Tools > Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Press '''Apply''' and '''Close'''. This option is necessary for the Ant property '''eclipse.running''' to be set when the Ant build script is run.
# Build an run the project by using the build script.

==== An Ant build script<span id="AntBuildScript"></span> ====

An example Ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/FirstUnoContact.jar" />
</target>

</project>
</source>

This build script has been tested stand-alone and with the Eclipse IDE. For use with other IDEs it may have to be adapted. The comments and all targets that have an <tt>unless</tt> attribute with the value <tt>eclipse.running</tt> should give an idea about what might be necessary.

The script works with a standard installation on unix, which is rooted at <tt>/opt</tt>. For other installations the property <tt>OFFICE_ROOT</tt> has to be set accordingly.

=== The FirstUnoContact class<span id="FirstUnoContactClass"></span> ===

The FirstUnoContact example that connects to the office with java: 

<source lang="java">
package de.ooo.devguide.example1;

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>

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:

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

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

''<idl>com.sun.star.sdb.DatabaseContext</idl>''
: holds databases registered with {{PRODUCTNAME}}

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

''<idl>com.sun.star.text.GlobalSettings</idl>''
: 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 <tt>FirstUnoContact</tt> 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 [http://api.openoffice.org/docs/java/ref/com/sun/star/comp/helper/Bootstrap.html <tt>com.sun.star.comp.helper.Bootstrap.bootstrap()</tt>] 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]]

Filter Dialog (new)

2009-03-13T18:06:58Z

OOoLerner: /* Introduction */

==Introduction==

The purpose of this project is to specify the new functionality for OpenOffice.org Base to filter records of a table or query. It is originating from the description of the
[http://dba.openoffice.org/development/projects.html#new_filter New Filter Dialog] developer project.

=== Goals ===

One of the two main goals of the specification is to describe a filter dialog for use in all contexts in order harmonize the user interface. Currently (OpenOffice.org 3.0.1) OpenOffice.org Base uses two different filter dialogs in different circumstances.

The other of the two main objectives is to enhance the current functionality so that more complex filter conditions can be specified.

A third goal is to provide a dialog that is easier to use and more intuitive to the user.

=== How to Help ===

A [[#SpecDraft|first draft]] of the specification is provided below. Please feel encouraged to send feedback to the [mailto:users@dba.openoffice.org users@dba.openoffice.org] mailing list.

==Status==

New project starting: 16 March 2009<br>

Specification Draft: <span id="SpecDraft">[http://specs.openoffice.org/files/documents/138/4488/NewFilterDialog_1.odt Filter for Tables and Queries]</span>

==Team and Contact==

Please use the [mailto:dev@dba.openoffice.org dev@dba.openoffice.org] mailing list for
questions, comments, problem reports or if you want help develop the new Filter Dialog.

The following people are working on the project:
* [mailto:karl.weber99@gmx.net?subject:OOoWiki Karl Weber] (iTeam Lead & Specification Owner)
* [http://wiki.services.openoffice.org/wiki/User:Frank_Sch%C3%B6nheit Frank Schönheit] ([http://dba.openoffice.org/ Development], [http://www.sun.com Sun Microsystems])
* [http://wiki.services.openoffice.org/wiki/User:Clu Christoph Lukasiak] ([http://ux.openoffice.org/ User Experience], [http://www.sun.com Sun Microsystems])
* [http://wiki.services.openoffice.org/wiki/User:DrewJensen/DBDoc Andrew Jenson] ([http://qa.openoffice.org/ Quality Assurance])

----
----
''Autors: [mailto:Christoph.Lukasiak@Sun.com?subject:OOoWiki Christoph Lukasiak] ([http://wiki.services.openoffice.org/wiki/User:Clu Clu]), [mailto:karl.weber99@gmx.net?subject:OOoWiki Karl Weber] 10 March 2009''<br>

''Please do not change the logical content of this site without
acknowledge of the authors, the [http://wiki.services.openoffice.org/wiki/Database_Docu_Coordinator Database Docu Coordinator] or the [http://wiki.services.openoffice.org/wiki/Project_Lead OOo QA Project Lead/Co-Leads].''

[[Category:Database]]

Filter Dialog (new)

2009-03-13T18:03:48Z

OOoLerner:

==Introduction==

The purpose of this project is to specify the new functionality OpenOffice.org Base is going to provide to filter records of a table or query. It is originating from the description of the
[http://dba.openoffice.org/development/projects.html#new_filter New Filter Dialog] developer project.

=== Goals ===

One of the two main goals of the specification is to describe a filter dialog for use in all contexts in order harmonize the user interface. Currently (OpenOffice.org 3.0.1) OpenOffice.org Base uses two different filter dialogs in different circumstances.

The other of the two main objectives is to enhance the current functionality so that more complex filter conditions can be specified.

A third goal is to provide a dialog that is easier to use and more intuitive to the user.

=== How to Help ===

A [[#SpecDraft|first draft]] of the specification is provided below. Please feel encouraged to send feedback to the [mailto:users@dba.openoffice.org users@dba.openoffice.org] mailing list.

==Status==

New project starting: 16 March 2009<br>

Specification Draft: <span id="SpecDraft">[http://specs.openoffice.org/files/documents/138/4488/NewFilterDialog_1.odt Filter for Tables and Queries]</span>

==Team and Contact==

Please use the [mailto:dev@dba.openoffice.org dev@dba.openoffice.org] mailing list for
questions, comments, problem reports or if you want help develop the new Filter Dialog.

The following people are working on the project:
* [mailto:karl.weber99@gmx.net?subject:OOoWiki Karl Weber] (iTeam Lead & Specification Owner)
* [http://wiki.services.openoffice.org/wiki/User:Frank_Sch%C3%B6nheit Frank Schönheit] ([http://dba.openoffice.org/ Development], [http://www.sun.com Sun Microsystems])
* [http://wiki.services.openoffice.org/wiki/User:Clu Christoph Lukasiak] ([http://ux.openoffice.org/ User Experience], [http://www.sun.com Sun Microsystems])
* [http://wiki.services.openoffice.org/wiki/User:DrewJensen/DBDoc Andrew Jenson] ([http://qa.openoffice.org/ Quality Assurance])

----
----
''Autors: [mailto:Christoph.Lukasiak@Sun.com?subject:OOoWiki Christoph Lukasiak] ([http://wiki.services.openoffice.org/wiki/User:Clu Clu]), [mailto:karl.weber99@gmx.net?subject:OOoWiki Karl Weber] 10 March 2009''<br>

''Please do not change the logical content of this site without
acknowledge of the authors, the [http://wiki.services.openoffice.org/wiki/Database_Docu_Coordinator Database Docu Coordinator] or the [http://wiki.services.openoffice.org/wiki/Project_Lead OOo QA Project Lead/Co-Leads].''

[[Category:Database]]

Documentation/DevGuide/ProUNO/Interfaces

2009-02-22T09:52:20Z

OOoLerner:

{{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 <tt>XPower</tt> and an <tt>XChannel</tt> interface. The illustration below shows a <tt>RemoteControl</tt> object with these interfaces:

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

The <tt>XPower</tt> interface has the functions <tt>turnOn()</tt> and <tt>turnOff()</tt> to control the power and the <tt>XChannel</tt> interface has the functions <tt>select()</tt>, <tt>next()</tt>, <tt>previous()</tt> 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 <tt>interface</tt> 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. <tt>XInterface</tt> is explained in [[Documentation/DevGuide/ProUNO/Using UNO Interfaces|Using UNO Interfaces]]. The <tt>interface</tt> 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 <tt>[oneway]</tt> 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:

* <tt>in</tt> specifies that the parameter will be used as an input parameter only
* <tt>out</tt> specifies that the parameter will be used as an output parameter only
* <tt>inout</tt> 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 <tt>[out]</tt> or <tt>[inout]</tt> 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]]

Documentation/DevGuide/ProUNO/The Any Type

2009-02-22T09:14:29Z

OOoLerner:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2a=block
|ProUNO2aDTypes=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Simple Types
|NextPage=Documentation/DevGuide/ProUNO/Interfaces
}}
[[zh:Zh/Documentation/DevGuide/ProUNO/The Any Type]]
{{DISPLAYTITLE:The Any Type}}
The special type <code>any</code> can represent values of all other UNO types. In the target languages, the <code>any</code> type requires special treatment. There is an <tt>AnyConverter</tt> in Java and special operators in C++. For details, see [[Documentation/DevGuide/ProUNO/UNO Language Bindings|UNO Language Bindings]].

{{PDL1}}

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

Documentation/DevGuide/ProUNO/Simple Types

2009-02-22T09:07:05Z

OOoLerner:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2a=block
|ProUNO2aDTypes=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Data Types
|NextPage=Documentation/DevGuide/ProUNO/The Any Type
}}
[[zh:Zh/Documentation/DevGuide/ProUNO/Simple Types]]
{{DISPLAYTITLE:Simple Types}}
UNO provides a set of predefined, simple types which are listed in the following table:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!UNO Type!!Description
|-
|<tt>void</tt>||Empty type, used only as method return type and in any.
|-
|<tt>boolean</tt>||Can be true or false.
|-
|<tt>byte</tt>||Signed 8-bit integer type (ranging from -128 to 127, inclusive).
|-
|<tt>short</tt>||Signed 16-bit integer type (ranging from −32768 to 32767, inclusive).
|-
|<tt>unsigned short</tt>||Unsigned 16-bit integer type (deprecated).
|-
|<tt>long</tt>||Signed 32-bit integer type (ranging from −2147483648 to 2147483647, inclusive).
|-
|<tt>unsigned long</tt>||Unsigned 32-bit integer type (deprecated).
|-
|<tt>hyper</tt>||Signed 64-bit integer type (ranging from −9223372036854775808 to 9223372036854775807, inclusive).
|-
|<tt>unsigned hyper</tt>||Unsigned 64-bit integer type (deprecated).
|-
|<tt>float</tt>||IEC 60559 single precision floating point type.
|-
|<tt>double</tt>||IEC 60559 double precision floating point type.
|-
|<tt>char</tt>||Represents individual Unicode characters (more precisely: individual UTF-16 code units).
|-
|<tt>string</tt>||Represents Unicode strings (more precisely: strings of Unicode scalar values).
|-
|<tt>type</tt>||Meta type that describes all UNO types.
|-
|<tt>any</tt>||Special type that can represent values of all other types.
|-
|}

The chapters about language bindings [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]], [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]], [[Documentation/DevGuide/ProUNO/Basic/OpenOffice.org Basic|OpenOffice.org Basic]] and [[Documentation/DevGuide/ProUNO/Bridge/Automation Bridge|Automation Bridge]] describe how these types are mapped to the types of your target language.

{{PDL1}}

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

Documentation/DevGuide/Forms/Model-View Interaction

2009-02-21T18:41:42Z

OOoLerner:

{{Documentation/DevGuide/FormsTOC
|Forms2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Forms/Models and Views for Form Controls
|NextPage=Documentation/DevGuide/Forms/Form Layer Views
}}
{{DISPLAYTITLE:Model-View Interaction}}
When model and view collaborate, data transfer is usually required in both directions, from model to view and backwards.

Consider a simple text field. The model for a control implements a <idl>com.sun.star.form.component.TextField</idl> service. This means it has a property Text, containing the current content of the field, and a property <tt>BackgroundColor</tt> specifying the color that should be used as background when drawing the text of the control.

First, if the value of the <tt>BackgroundColor</tt> property is changed, the control is notified of the change. This is done by UNO listener mechanisms, such as the <idl>com.sun.star.beans.XPropertyChangeListener</idl> allowing the control to listen for changes to model properties and react accordingly. Here the control would have to redraw itself using the new background color.

In fact this is a common mechanism for the communication between model and view: The view adds itself as listener for any aspect of the model which could affect it, and when it is notified of changes, it adjusts itself to the new model state. This means that the model is always the passive part. The model does not know its views, or at least not as views, but only their role as listeners, while the views know their model.

On the other hand, if the view is used for interaction with the user, the data needs to be propagated from the view to the model. The user enters data in a text field, and the change is reflected in the model. Remember that the user sees the control only, and everything affects the ''control'' in the first step. If the user interacts with the view with the intention of modifying the model, the view propagates changes to the model.

In our example, the user enters text into the control, the control ''automatically'' updates the respective property at the model (Text), thus modifying the document containing the model.

{{PDL1}}

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

Documentation/DevGuide/Forms/The Model-View Paradigm

2009-02-21T18:28:46Z

OOoLerner:

{{Documentation/DevGuide/FormsTOC
|Forms2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Forms/Models and Views
|NextPage=Documentation/DevGuide/Forms/Models and Views for Form Controls
}}
{{DISPLAYTITLE:The Model-View Paradigm}}
A basic concept to understand about forms and controls in {{PRODUCTNAME}} is the model-view paradigm. For a given element in your document,for example, a text field in your HTML form, it says that you have ''exactly one'' model and an arbitrary number of views.

The model is what is part of your document in that it describes how this element looks, and how it behaves. The model even exists when you do not have an open instance of your document. If it is stored in a file, the file contains a description of the model of your element.

{{Documentation/Note|In UNO, the simplest conceivable model is a component implementing <idl>com.sun.star.beans.XPropertySet</idl> only. Every aspect of the view could then be described by a single property. In fact, as you will see later, models for form controls are basically property sets.}}

The view is a visual representation of your model. It is the component which looks and behaves according to the requirements of the model. You can have multiple views for one model, and they would all look alike as the model describes it. The view is visible to the user. It is for visualizing the model and handles interactions with the user. The model, however, is merely a "dumb" container of data.

A good example to illustrate this is available in {{PRODUCTNAME}}. Open an arbitrary document and choose the menu item '''Window > New Window'''. A second window is opened showing the same document displayed in the first window. This does not mean that the document was opened twice, it means you opened a second view of the same document, which is a difference. In particular, if you type some text in one of the windows, this change is visible in ''both'' windows. That is what the model-view paradigm is about: Keep your document data once in the model, and when you need to visualize the data to the user, or need interaction from the user that modifies the document, create views to the model as needed.

Between model and view a 1:n relationship exists:

[[Image:Model_View_Paradigm.png|none|thumb|400px|The Model View Paradigm]]

{{Documentation/Note|Note that the relation is directed. Usually, a view knows its model, but the model itself does not know about the views which visualize it.}}

{{PDL1}}

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

Documentation/DevGuide/Forms/Models and Views

2009-02-21T18:22:10Z

OOoLerner:

{{Documentation/DevGuide/FormsTOC
|Forms2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Forms/Forms
|NextPage=Documentation/DevGuide/Forms/The Model-View Paradigm
}}
{{DISPLAYTITLE:Models and Views}}
The model describes appearance and behaviour of the element. The view is the visual representation of the element. The relationship between models and views is important to understand and is described in detail in this section.

{{PDL1}}

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

Documentation/DevGuide/Forms/Forms

2009-02-21T18:17:41Z

OOoLerner:

{{Documentation/DevGuide/FormsTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Database/Handling Unsupported Functionality
|NextPage=Documentation/DevGuide/Forms/Models and Views
}}
[[zh:Zh/Documentation/DevGuide/Forms/Forms]]
{{DISPLAYTITLE:Forms}}
{{Download Collection|MediaWiki:Collections/Developer's Guide - Forms}}
Forms offer a method of control-based data input. A form or ''form document'' consists of a set of controls, where each one enters a single piece of data. In a simple case, this could be a plain text field allowing you to insert some text without any word breaks. When we speak of forms, we mean forms and controls, because these cannot be divided.

If an internet site asks you for information, for example, for a product registration you are presented with fields to enter your name, your address and other information. These are HTML forms.

Basically, this is what {{PRODUCTNAME}} forms do. They enhance nearly every document with controls for data input. This additional functionality put into a document is called the ''form layer'' within the scope of this chapter.

The most basic functionality provides the controls for HTML form documents mentioned above: If you open an HTML document with form elements in {{PRODUCTNAME}} Writer, these elements are represented by components from <idlmodule>com.sun.star.form</idlmodule>.

The more enhanced functionality provides support for data-aware forms. These are forms and controls that are bound to a data source registered in {{PRODUCTNAME}} to enter data into tables of a database. For more information about data sources and data access in general, refer to the [[Documentation/DevGuide/Database/Database Access|Database Access]].

Since {{PRODUCTNAME}} {{OO2.0.0}}, form controls also feature a generalization of this concept. They can be bound to external components, which supply an own value. Both values - the one of the external component, and the current value of the control - are synchronized, so that a change in one of them is immediately propagated to the other. This allows new features, where the most notable is that you can bind form controls to spreadsheet cells.

When discussing forms, ''form documents'' and ''logical forms'' have to be distinguished. The phrase ''form document'' refers to a document as a whole, while a ''logical form'' is basically a set of controls with additional properties. Within the scope of this chapter, when a "form" is referred to, the logical form is meant.

{{PDL1}}

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

Documentation/DevGuide/Extensions/Location of Installed Extensions

2009-02-21T15:12:29Z

OOoLerner:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/unopkg
|NextPage=Documentation/DevGuide/Extensions/Extension Layers
}}
[[zh:Zh/Documentation/DevGuide/Extensions/Location of Installed Extensions]]
{{DISPLAYTITLE:Location of Installed Extensions}}
Sometimes an extension developer needs to know the path to the root of his installed extension e.g. to load some additional data. You can use the singleton <tt>PackageInformationProvider</tt> to get an URL for an installed extension with a given Extension Identifier. For more information about Extension Identifiers see [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]. For more information see <idl>com.sun.star.deployment.PackageInformationProvider</idl> and have a look at <idl>com.sun.star.deployment.XPackageInformationProvider</idl>.
<source lang="cpp">
...
namespace css = com::sun::star;
css::uno::Reference< css::uno::XComponentContext > mxContext;
...
css::uno::Reference< css::deployment::XPackageInformationProvider >
xInfoProvider( css::deployment::PackageInformationProvider::get( mxContext ) );

// "MY_PACKAGE_ID" is the identifier of the package whose location we want
rtl::OUString sLocation = xInfoProvider->getPackageLocation(
rtl::OUString::createFromAscii( "MY_PACKAGE_ID" ) );
...
</source>
{{PDL1}}

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

Documentation/DevGuide/Extensions/unopkg

2009-02-21T15:10:23Z

OOoLerner:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org
|NextPage=Documentation/DevGuide/Extensions/Location of Installed Extensions
}}
[[zh:Zh/Documentation/DevGuide/Extensions/unopkg]]
{{DISPLAYTITLE:unopkg}}
The ''unopkg'' executable offers another way to start the Extension Manager. It supersedes the ''pkgchk'' executable which was used in {{PRODUCTNAME}} {{OO1.1.0}} and older versions and which no longer works.

In contrast to the Extension Manager in {{PRODUCTNAME}} ''unopkg'' can also manage shared extensions. For example:

[<OfficePath>/program] $ unopkg add --shared my_extension.oxt

installs ''my_extension.oxt'' for all users.

''unopkg'' offers a windowless mode in which all interactions occurs through the console. This is the default. If ''unopkg'' is started with the subcommand <tt>gui</tt> then the Extension Manager dialog appears which is exactly the same as the one in {{PRODUCTNAME}}.

[<OfficePath>/program] $ unopkg gui

The difference is that in the dialog all items deployed under '''{{PRODUCTNAME}} Extensions''' can be modified and new items can be added there as well. All actions, that is, adding, removing, etc. can be done in the dialog. Therefore <tt>unopkg gui</tt> does not require any more parameters.

It follows a short overview what can be done with ''unopkg''. Since there are many more commands, have a look at the help text that can be obtained by calling <tt>unopkg -h</tt>.

First of all open a console and change into the program directory of the office installation.

Adding an extension for a single user:

[<OfficePath>/program] $ unopkg add my_extension.oxt

Adding an extension for all users:

[<OfficePath>/program] $ unopkg add --shared my_extension.oxt

Removing a user extension is done via the identifier of the extension (see [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]):

[<OfficePath>/program] $ unopkg remove my.domain.my_extension-id

Remove a shared extension:

[<OfficePath>/program] $ unopkg remove --shared my.domain.my_extension-id

Before you install an extension or other item for all users, make absolutely sure there are no running instances of {{PRODUCTNAME}}. ''unopkg'' cannot recognize if there are running instances of {{PRODUCTNAME}} from different users. Installing into a running office installation might cause inconsistencies and destroy your installation!

When a user starts {{PRODUCTNAME}} and then starts ''unopkg'', then the Extension Manager from the office is used and ''unopkg'' terminates. Then, however, no shared extensions and other shared items can be modified.

{{Documentation/Caution|Although it is now possible to deploy “live” into a running {{PRODUCTNAME}} process, there are some limitations you should be aware of: Removing a type library from a running process is not possible, because this may lead to crashes when the type is needed. Thus if you, for example, uninstall a package that comes with a UNO type library, these types will vanish upon next process startup, but not before.

There may also be problems with cached configuration data, because parts of the running process do not listen for configuration updates (for example, menu bars). Most often, those parts read the configuration just once upon startup.}}

{{PDL1}}

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

Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org

2009-02-21T15:04:23Z

OOoLerner:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User
|NextPage=Documentation/DevGuide/Extensions/unopkg
}}
[[zh:Zh/Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org]]
{{DISPLAYTITLE:Extension Manager in OpenOffice.org}}
Within a running office the Extension Manager is started through the menu item '''Tools > Extension Manager...'''. When started in this way, extensions can only be installed as user extensions. All items deployed under '''{{PRODUCTNAME}} Extensions''' cannot be modified. But it is possible to export them.

{{PDL1}}

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

Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User

2009-02-21T14:43:24Z

OOoLerner:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Deployment Items
|NextPage=Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org
}}
[[zh:Zh/Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User]]
{{DISPLAYTITLE:Installing Extensions for All or a Single User}}
When installing an extension, one has to decide if all possible users can use it (shared extension) or only oneself (user extension). In the first case, users cannot modify (enable, disable, remove) the extension unless they have write access to the share directory in the office installation.

A shared extension may change the appearance of the GUI (toolbars, menu bar, etc.) for all users. They can, however, configure their office so that particular menu or toolbar items are not shown. There is currently no way to centrally install an extension for particular user groups.

Whether an extension is to be installed for all users, or only for the single user, is determined during installation. The person performing the install must select, in the Extension Manager dialog, either '''My Extensions''' or '''{{PRODUCTNAME}} Extensions''' before pressing the '''Add...''' button. In the first case, the extension will only be installed for the current user, whereas in the latter case it will be installed for all users.

When running ''unopkg'' in a windowless mode, the option <tt>--shared</tt> determines if an extension can be used by all users. For example:

[<OfficePath>/program] $ unopkg add --shared my_extension.oxt

would install <tt>my_extension</tt> so that it can be used by all users.

{{PDL1}}

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

Documentation/DevGuide/Extensions/Extension Manager

2009-02-21T11:27:18Z

OOoLerner:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extensions
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
[[zh:Zh/Documentation/DevGuide/Extensions/Extension Manager]]
{{DISPLAYTITLE:Extension Manager}}
The Extension Manager is a tool for managing extensions and other deployable items, such as separate libraries, JARs, configuration data files. This includes adding, removing, enabling and disabling of these items.

The Extension Manager can be started from within the office by pressing the menu item '''Tools > Extension Manager''' or by running the ''unopkg'' executable, which is contained in the program directory of the office installation.

When an extension is installed, then a copy is created which is kept either in the user installation or the shared installation (''<office-directory>/share''). The original extension can therefore be (re) moved after installation.

{{PDL1}}

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

Documentation/DevGuide/Basic/Adding Event Handlers

2009-02-16T21:04:30Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/Creating Dialogs
|NextPage=Documentation/DevGuide/Basic/AutoPilot Dialogs
}}
{{DISPLAYTITLE:Adding Event Handlers}}
Now we will write code to open the dialog and add functionality to the buttons. To show a dialog, create a dialog object using <tt>createUnoDialog()</tt> and call its <tt>execute()</tt> method. A dialog can be closed while it is shown by calling <tt>endExecute()</tt>.

{{Documentation/Tip|It is possible to configure the '''Finish''' button and the '''Cancel''' button to close the dialog by setting the button property PushButtonType to OK and Cancel respectively. The method <tt>execute()</tt> returns 0 for Cancel and 1 for OK.}}

To add functionality to GUI elements, develop Subs to handle GUI events, then hook them to the GUI elements. To add functionality to the buttons of our dialog, click the '''Module1''' tab in the lower part of the Basic IDE and enter the following Subs above the previous Sub Main to open, close and process the dialog. Note that a <tt>Private</tt> variable <tt>oDialog</tt> is defined outside of the Subs. After loading the dialog, this variable is visible from all Subs and Functions of Module1.


Private oDialog as Variant ' private, module-wide variable

Sub RunGraphicsWizard
oDialog = createUnoDialog(DialogLibraries.Standard.Dialog1)
oDialog.execute
End Sub

Sub CancelGraphicsDialog
oDialog.endExecute()
End Sub

Sub FinishGraphicsDialog
Dim sFile as String, sGraphicURL as String

oDialog.endExecute()

sFile = oDialog.Model.FileControl1.Text

' the FileControl contains a system path, we have to transform it to a file URL
' We use the built-in Basic runtime function ConvertToURL for this purpose
sGraphicURL = ConvertToURL(sFile)

' insert the graphics
' access the document model
oDoc = ThisComponent
' get the Text service of the document
oText = oDoc.getText()
' create an instance of a graphic object using the document service factory
oGraphicObject = oDoc.createInstance("com.sun.star.text.GraphicObject")
' set the URL of the graphic
oGraphicObject.GraphicURL = sGraphicURL
' get the current cursor position in the GUI and create a text cursor from it
oViewCursor = oDoc.getCurrentController().getViewCursor()
oCursor = oText.createTextCursorByRange(oViewCursor.getStart())
' insert the graphical object at the cursor position
oText.insertTextContent(oCursor.getStart(), oGraphicObject, false)
End Sub

Sub Main
...
End Sub

Select the '''Cancel''' button in our dialog in the dialog editor, and click the '''Events''' tab of the '''Properties Dialog''', then click the ellipsis button on the right-hand side of the Event '''When Initiating'''. As shown in the next illustration the '''Assign Action''' dialog appears.

[[Image:CancelButtonEvent.png|none|thumb|400px|Assign Action dialog]]

In the '''Assign Action''' dialog press the '''Macro ...''' button to open the '''Macro Selector''' dialog shown in the illustration below. Navigate to <tt>FirstStepsBasic.Standard.Module1</tt>, select the Sub CancelGraphicsDialog and press the '''OK''' button to link this sub to the wizard dialog's '''Cancel''' button.

[[Image:MacroSelector.png|none|thumb|400px|The Macro Selector dialog]]

The next illustration shows how the new assignment is shown in the '''Assign Action''' dialog.

[[Image:AssignedAction.png|none|thumb|400px|The Assign Action dialog]]

Pressing the '''OK''' button in the Assign Action dialog finishes the assignment process.

{{Documentation/Note|In the '''Assign Action''' dialog there's also a '''Component ...''' button. This button is only needed in the context of dialogs used by UNO components, see [[Documentation/DevGuide/WritingUNO/Accessing Dialogs|Accessing Dialogs]]. In the Basic context this button is not relevant.}}

Using the same method, hook the Finish button to <tt>FinishGraphicsDialog</tt>.

{|
|[[Image:MacroRun.png]]
|If the '''Run''' icon is selected now, the dialog is displayed, and the '''Finish''' and '''Cancel''' buttons are functional.
|}

{{PDL1}}

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

Documentation/DevGuide/Basic/Creating Dialogs

2009-02-16T19:02:45Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/Calling a Sub from the User Interface
|NextPage=Documentation/DevGuide/Basic/Adding Event Handlers
}}
{{DISPLAYTITLE:Creating Dialogs}}
To create a dialog in the Basic IDE, right-click the Module1 tab at the bottom of the Basic source editor and select '''Insert > Basic Dialog'''. The IDE creates a new page named Dialog1:

[[Image:DialogIDE.png|none|thumb|400px|The Basic GUI Editor]]

{| cellpadding=4
|[[Image:Controls.png]]
|To add controls to the dialog, we require the dialog design tools. Click the '''Controls''' icon to pop up the design tools window. The title bar of the tools window can be used to drag the window away from the toolbar to keep it open permanently.
|}

Our dialog shall offer a more convenient way to select a file than the simple input box of our first example. Furthermore, the user shall be able to control how the picture is anchored in the text after inserting it. For this, we will create a wizard dialog with two steps.

{| cellpadding=4
|[[Image:FileSelection.png]]
|In the design tools window, select '''File Selection''' and define the size of the '''Browse''' control by dragging a rectangle in the dialog using the left-mouse button.
|-
|[[Image:ControlProperties.png]]
|The '''Properties''' icon displays the '''Properties Dialog''' that is used to edit controls and hook up event handling code to events occurring at dialog controls.
|-
|[[Image:ButtonControl.png]]
|Next, add '''<< Back''' and '''Next >>''' Buttons to move between the dialog steps, and a '''Finish''' and '''Cancel''' button. Select the '''Button''' icon and define the button size using the left-mouse button. Buttons are labeled with a default text, such as <tt>CommandButton1</tt>. If the '''Properties Dialog''' is not open, double click the newly inserted button controls to display it. Enter new labels in the Label field as suggested, and name the dialog step buttons Back and Next. Set the property '''Enabled''' for the '''<< Back''' button to <tt>false</tt>.
|-
|[[Image:LabelControl.png]]
|Use the Label tool to create a label "Select Graphics File:" in the same manner.
|}

Now the dialog looks similar to the illustration below:

[[Image:DialogStep1.png|none|thumb|500px|The custom dialog]]

{| cellpadding=4
|[[Image:ActivateTestMode.png]]
|Test the dialog using the '''Activate Test Mode''' icon from the design tool window. After you have finished the test, click the '''Close''' button of the test dialog window.
|}

To edit the dialog, such as setting the title and changing the size, select it by clicking the outer border of the dialog. Green handles appear around the dialog. The green handles can be used to alter the dialog size. The '''Properties Dialog''' is used to define a dialog title and other dialog properties.

{{PDL1}}

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

Documentation/DevGuide/Basic/Calling a Sub from the User Interface

2009-02-15T23:38:58Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/Writing and Debugging a Basic UNO program
|NextPage=Documentation/DevGuide/Basic/Creating Dialogs
}}
{{DISPLAYTITLE:Calling a Sub from the User Interface}}
A Sub can be called from customized icons, menu entries, upon keyboard shortcuts and on certain application or document events. The entry point for all these settings is the '''Customize''' dialog accessible through the '''Assign''' button in the Macro dialog or the '''Tools > Customize''' command.

To assign the Sub Main to a toolbar icon, select '''Tools > Customize''' and click the '''Toolbars''' tab The '''Toolbars''' tab looks like this:

[[Image:CustomizeToolbars.png|none|thumb|400px|Customize Toolbars]]

Click the '''Add''' button in the '''Toolbars''' tab. In the Add Commands dialog that pops up, scroll down the '''Category''' list until you see the {{PRODUCTNAME}} Macros node. Expand it and the '''FirstStepsBasic.odt''' node. Navigate to the Module <tt>FirstStepsBasic.Standard.Module1</tt> and select it. When <tt>Module1</tt> is selected, the Commands list shows an entry "Main" for the Sub Main in <tt>Module1</tt>. Clicking '''Add''' will add it to a toolbar.

You can now click the new toolbar item to launch the example macros.

The section [[Documentation/DevGuide/Basic/Assigning Macros to GUI Events|Assigning Macros to GUI Events]] describes other options to make your Sub accessible from the user interface.

{{PDL1}}

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

Documentation/DevGuide/Basic/Writing and Debugging a Basic UNO program

2009-02-15T23:29:45Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/Creating a Module in a Standard Library
|NextPage=Documentation/DevGuide/Basic/Calling a Sub from the User Interface
}}
{{DISPLAYTITLE:Writing and Debugging a Basic UNO program}}
Enter the following source code in the Basic editor window. The example asks the user for the location of a graphics file and inserts it at the current cursor position of our document. Later, the example will be extended by a small insert graphics autopilot.


Sub Main
' ask the user for a graphics file
sGraphicUrl = InputBox("Please enter the URL of a graphic file", _
"Import Graphics", _
"file:///")
if sGraphicURL = "" then ' User clicked Cancel
exit sub
endif

' access the document model
oDoc = ThisComponent

' get the Text service of the document
oText = oDoc.getText()

' create an instance of a graphic object using the document service factory
oGraphicObject = oDoc.createInstance("com.sun.star.text.GraphicObject")

' set the URL of the graphic
oGraphicObject.GraphicURL = sGraphicURL

' get the current cursor position in the GUI and create a text cursor from it
oViewCursor = oDoc.getCurrentController().getViewCursor()
oCursor = oText.createTextCursorByRange(oViewCursor.getStart())

' insert the graphical object at the cursor position
oText.insertTextContent(oCursor.getStart(), oGraphicObject, false)
End Sub

If help is required on Basic keywords, press F1 while the text cursor is on a keyword. The {{PRODUCTNAME}} online help contains descriptions of the Basic language as supported by {{PRODUCTNAME}}.

Starting with the line <tt>oDoc = ThisComponent</tt>, where the document model is accessed, we use the UNO integration of {{PRODUCTNAME}} Basic. <tt>ThisComponent</tt> is a shortcut to access a document model from the Basic code contained in it. Earlier, you created <tt>Module1</tt> in ''FirstStepsBasic.odt'', that is, your Basic code is embedded in the document ''FirstStepsBasic.odt'', not in a global library below the '''My Macros''' container. The property <tt>ThisComponent</tt> therefore contains the document model of ''FirstStepsBasic.odt''.

{{Documentation/Tip|Outside document libraries use <tt>ThisComponent</tt> or <tt>StarDesktop.CurrentComponent</tt> to retrieve the current document. If access to an open document is required, even if it is not the current document, you have to iterate over the components in <tt>StarDesktop.Components</tt>, checking their URL property with code similar to the following:

<nowiki>oComps = StarDesktop.Components
oCompsEnum = oComps.createEnumeration()

while oCompsEnum.hasMoreElements()
oComp = oCompsEnum.nextElement()
' not all desktop components are necessarily models with a URL
if HasUnoInterfaces(oComp, "com.sun.star.frame.XModel") then
print oComp.getURL()
endif
wend</nowiki>
}}

{| cellpadding=4
|[[Image:Breakpoint.png]]
|To debug the program, put the cursor into the line <tt>oDoc = ThisComponent</tt> and click the '''Breakpoint''' icon in the macro bar.
|-
|[[Image:MacroRun.png]]
|The '''Run''' icon launches the first Sub in the current module. Execution stops with the first breakpoint.
|-
|[[Image:SingleStep.png]]
|Now step through the program by clicking the '''Single Step''' icon.
|-
|[[Image:Macros.png]]
|Click the '''Macros''' icon if you need to run a Sub other than the first Sub in the module.. In the '''{{PRODUCTNAME}} Basic Macros''' dialog, navigate to the appropriate module, select the Sub to run and press the '''Run''' button.
|}

To observe the values of Basic variables during debugging, enter a variable name in the '''Watch''' field of the Basic editor and press the '''Enter''' key to add the watch, or point at a variable name with the mouse cursor without clicking it. In the example below, we can observe the variables <tt>sGraphicUrl</tt> and <tt>oGraphicObject</tt>:

[[Image:Watch.png|none|thumb|500px|A macro in the source editor window]]

Since {{PRODUCTNAME}} {{OO2.0.0}} it is also possible to inspect the values of UNO objects in the Basic debugger during runtime.

{{PDL1}}

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

Talk:Documentation/DevGuide/Basic/Creating a Module in a Standard Library

2009-02-15T23:02:32Z

OOoLerner:

The page states: '''Additionally each loaded document can contain Basic libraries.''' This does not apply to base documents. (Ooo 3.0.1)
[[User:OOoLerner|OOoLerner]] 23:02, 15 February 2009 (UTC)

Documentation/DevGuide/Basic/Creating a Module in a Standard Library

2009-02-15T23:00:24Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/First Steps with OpenOffice.org Basic
|NextPage=Documentation/DevGuide/Basic/Writing and Debugging a Basic UNO program
}}
{{DISPLAYTITLE:Creating a Module in a Standard Library}}
# Create a new Writer document and save the document, for example, ''FirstStepsBasic.odt''.
# Click '''Tools > Macros > Organize Macros > {{PRODUCTNAME}} Basic'''.

The '''{{PRODUCTNAME}} Basic Macros''' dialog appears. The '''Macro from''' list shows macro containers where Basic source code (macros) can come from. There is always a '''My Macros''' and a '''{{PRODUCTNAME}} Macros''' container for Basic libraries. Additionally each loaded document can contain Basic libraries.

[[Image:MacroNew.png|none|thumb|400px|Macro dialog]]

The illustration above shows that the document ''FirstStepsBasic.odt'' is the only document loaded. Therefore, the '''My Macros''', '''{{PRODUCTNAME}} Macros''' and '''FirstStepsBasic.odt''' containers are displayed in the illustration above. Both containers, '''My Macros''' and '''FirstStepsBasic.odt''', contain a library named '''Standard'''. The {{PRODUCTNAME}} Macros container contains the libraries that come with a default {{PRODUCTNAME}} installation – most of them are AutoPilots. The '''Standard''' libraries of the application and for all open documents are always loaded. They appear enabled in the dialog. Other libraries have to be loaded before they can be used.

The libraries contain modules with the actual Basic source code. Our next step will create a new module for source code in the '''Standard''' library of our ''FirstStepsBasic.odt'' document.

# Scroll to the document node '''FirstStepsBasic.odt''' in the '''Macro from''' list.
# Select the '''Standard''' entry below the document node and click '''New'''.

{{PRODUCTNAME}} shows a small dialog that suggests to create a new module named <tt>Module1</tt>.

# Click '''OK''' to confirm.

The Basic source editor window appears containing a Sub (subroutine) Main.

[[Image:MainNew.png|none|thumb|500px|Basic source editor window]]

The status bar of the Basic editor window shows that the Sub Main is part of <tt>FirstStepsBasic.Standard.Module1</tt>. If you click '''Tools > Macros > {{PRODUCTNAME}} Basic''' in the Basic editor, you will see that {{PRODUCTNAME}} created a module <tt>Module1</tt> below the Standard library in ''FirstStepsBasic.odt''.

[[Image:ModuleNew.png|none|thumb|400px|The New Module window]]

When a module is selected, the '''Macro name''' list box on the left shows the Subs and Functions in that module. In this case, Sub Main. If you click '''Edit''' while a Sub or Function is selected, the Basic editor opens and scrolls to the selected Sub or Function.

{{PDL1}}

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

Talk:Documentation/DevGuide/Basic/Creating a Module in a Standard Library

2009-02-15T22:48:38Z

OOoLerner: New page: The page states: '''Additionally each loaded document can contain Basic libraries.''' This does not apply to base documents. (Ooo 3.0.1)

The page states: '''Additionally each loaded document can contain Basic libraries.''' This does not apply to base documents. (Ooo 3.0.1)

Documentation/DevGuide/Basic/Creating a Module in a Standard Library

2009-02-15T22:32:23Z

OOoLerner:

{{Documentation/DevGuide/BasicTOC
|BasicTutorial=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/First Steps with OpenOffice.org Basic
|NextPage=Documentation/DevGuide/Basic/Writing and Debugging a Basic UNO program
}}
{{DISPLAYTITLE:Creating a Module in a Standard Library}}
# Create a new Writer document and save the document, for example, ''FirstStepsBasic.odt''.
# Click '''Tools > Macros > Organize Macros > {{PRODUCTNAME}} Basic'''.

The '''{{PRODUCTNAME}} Basic Macros''' dialog appears. The '''Macro from''' list shows macro containers where Basic source code (macros) can come from. There is always a '''My Macros''' and a '''{{PRODUCTNAME}} Macros''' container for Basic libraries. Additionally each loaded document can contain Basic libraries.

[[Image:MacroNew.png|none|thumb|400px|Macro dialog]]

The illustration above shows that the document ''FirstStepsBasic.odt'' is the only document loaded. Therefore, the '''My Macros''', '''{{PRODUCTNAME}} Macros''' and '''FirstStepsBasic.odt''' containers are displayed in the illustration above. Both containers, '''My Macros''' and '''FirstStepsBasic.odt''', contain a library named '''Standard'''. The {{PRODUCTNAME}} Macros container contains the libraries that come with a default {{PRODUCTNAME}} installation – most of them are AutoPilots. The '''Standard''' libraries of the application and for all open documents are always loaded. They appear enabled in the dialog. Other libraries have to be loaded before they can be used.

The libraries contain modules with the actual Basic source code. Our next step will create a new module for source code in the '''Standard''' library of our ''FirstStepsBasic.odt'' document.

# Scroll to the document node '''FirstStepsBasic.odt''' in the '''Macro from''' list.
# Select the '''Standard''' entry below the document node and click '''New'''.

{{PRODUCTNAME}} shows a small dialog that suggests to create a new module named <tt>Module1</tt>.

# Click OK to confirm.

The Basic source editor window appears containing a Sub (subroutine) Main.

[[Image:MainNew.png|none|thumb|500px|Basic source editor window]]

The status bar of the Basic editor window shows that the Sub Main is part of <tt>FirstStepsBasic.Standard.Module1</tt>. If you click '''Tools > Macros > {{PRODUCTNAME}} Basic''' in the Basic editor, you will see that {{PRODUCTNAME}} created a module <tt>Module1</tt> below the Standard library in ''FirstStepsBasic.odt''.

[[Image:ModuleNew.png|none|thumb|400px|The New Module window]]

When a module is selected, the '''Macro name''' list box on the left shows the Subs and Functions in that module. In this case, Sub Main. If you click '''Edit''' while a Sub or Function is selected, the Basic editor opens and scrolls to the selected Sub or Function.

{{PDL1}}

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

Documentation/DevGuide/WritingUNO/Using Dialogs in Components

2009-02-15T14:59:46Z

OOoLerner: /* Instantiate and display a dialog */

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2Accessing=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Assigning Component Methods to Control Events
|NextPage=Documentation/DevGuide/Extensions/Extensions
}}
[[zh:Zh/Documentation/DevGuide/WritingUNO/Using Dialogs in Components]]
{{DISPLAYTITLE:Using Dialogs in Components}}
In general components using dialogs are like any other component. But they need some additional code to instantiate and display the dialog(s) to be used and to accept the events created by the dialog controls.

=== Instantiate and display a dialog ===

To do this an extended version of the <idl>com.sun.star.awt.DialogProvider</idl> service - described in chapter [[Documentation/DevGuide/Scripting/Scripting Framework|Scripting Framework]] - has to be used. The extended service version <idl>com.sun.star.awt.DialogProvider2</idl> supports <idl>com.sun.star.awt.XDialogProvider2</idl> providing an additional method <idl>com.sun.star.awt.XDialog</idl> <tt>createDialogWithHandler(...)</tt> that allows to pass an interface when creating the dialog. This interface will be used as event handler and called if events are bound to the component.

The following code is taken from the DialogComponent SDK example that can be found in ''SDK/examples/DevelopersGuide/Components'' and shows how a dialog is created and displayed using the <tt>DialogProvider2</tt> service:
<source lang="java">
// XTestDialogHandler
public String createDialog( String DialogURL, XModel xModel, XFrame xFrame ) {
m_xFrame = xFrame;

try {
XMultiComponentFactory xMCF = m_xCmpCtx.getServiceManager();
Object obj;

// If valid we must pass the XModel when creating a DialogProvider object
if( xModel != null ) {
Object[] args = new Object[1];
args[0] = xModel;

obj = xMCF.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider2", args, m_xCmpCtx );
}
else {
obj = xMCF.createInstanceWithContext(
"com.sun.star.awt.DialogProvider2", m_xCmpCtx );
}

XDialogProvider2 xDialogProvider = (XDialogProvider2)
UnoRuntime.queryInterface( XDialogProvider2.class, obj );

XDialog xDialog = xDialogProvider.createDialogWithHandler( DialogURL, this );
if( xDialog != null )
xDialog.execute();
}
catch (Exception e) {
e.printStackTrace();
}
return "Created dialog \"" + DialogURL + "\"";
}
</source>
The variable <code>m_xCmpCtx</code> is the <idl>com.sun.star.uno.XComponentContext</idl> interface passed to the component while initialisation. If the dialog that should be created is placed inside a document a <idl>com.sun.star.frame.XModel</idl> interface <code>xModel</code> representing this document has to be passed. It's used as argument to initialise the DialogProvider service enabling the access to the document's Dialog Libraries. If <code>xModel</code> is null the dialog has to be placed in the application library container. This also has to be reflected in the DialogURL passed to the method.

Example code for a Basic/Dialog library <code>Library1</code> placed in a document:

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=document", _
ThisComponent, StarDesktop.getActiveFrame() )
End Sub

Example code for a Basic/Dialog library <code>Library1</code> placed in "My Macros":

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=application", _
null, StarDesktop.getActiveFrame() )
End Sub

The dialog contained in the ''DialogComponent.odt'' sample document in ''SDK/examples/DevelopersGuide/Components/DialogComponent'' looks like this.

[[Image:TestDialog.png|none|thumb|398px|Sample dialog with controls]]

The button labels show which component method is called in each case. The next chapter explains how these methods can be implemented inside the component. Method "doit3" isn't implemented at all. It's called in the sample dialog to show the resulting error message:

[[Image:ErrorMessage.png|none|thumb|264px|Error message for Component method not found]]

=== Accept events created by dialog controls ===

The event handling functionality can be implemented in two different ways. The test component described here uses both ways.

The first way is to implement the generic handler interface <idl>com.sun.star.awt.XDialogEventHandler</idl> containing two methods:
<source lang="idl">
interface XDialogEventHandler: com::sun::star::uno::XInterface
{
bool callHandlerMethod
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any Event,
[in] string MethodName
)

sequence<string> getSupportedMethodNames();
}
</source>
If an event occurs that is bound to a component method and the component implements this interface, the method <code>callHandlerMethod</code> will be called first, with the method name used in the event binding passed as <code>MethodName</code> parameter. In this example this would be:
<source lang="java">
xHandler.callHandlerMethod( xDialog, aEvent, "handleEvent" );
</source>
<code>xDialog</code> points to the same dialog instance that has been returned by the <code>createDialogWithHandler()</code> method. Event represents the event object originally passed to the awt listener method. E.g. in case of the "When initiating" event used in this example the corresponding awt listener interface is <idl>com.sun.star.awt.XActionListener</idl> and an <idl>com.sun.star.awt.ActionEvent</idl> is passed to its <code>actionPerformed</code> method when the event occurs. This <code>ActionEvent</code> object will also be passed to <code>callHandlerMethod</code>. The Event object has to be passed as any, because other events use different listener interfaces with other event object types. <code>callHandlerMethod</code> returns a bool value. Returning true means that the event has been handled.

The method <code>getSupportedMethodNames()</code> should return the names of all methods handled by <code>callHandlerMethod()</code>. It's intended for later use, especially to expand the user interface to allow browsing a component's methods.

If the event has not been handled, because <code>callHandlerMethod</code> returns false or <idl>com.sun.star.awt.XDialogEventHandler</idl> isn't supported at all by the component, the DialogProvider uses the <idl>com.sun.star.beans.Introspection</idl> service to detect if one of the following methods is provided by one of the interfaces supported by the component:
<source lang="idl">
void [MethodName]
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any aEvent
);
</source>
or
<source lang="idl">
void [MethodName]( void );
</source>
The second method is only used if the first one is not available. In this example the component would have to support an interface containing a method <code>handleEvent</code> with one of these signatures. It also has to support <idl>com.sun.star.lang.XTypeProvider</idl> because otherwise the introspection mechanism does not work.

As already mentioned the sample component supports both ways to implement handler methods. <idl>com.sun.star.awt.XDialogEventHandler</idl> is implemented like this:
<source lang="java">
private String aHandlerMethod1 = "doit1";
private String aHandlerMethod2 = "doit2";

//XDialogEventHandler
public boolean callHandlerMethod( /*IN*/XDialog xDialog, /*IN*/Object EventObject,
/*IN*/String MethodName ) {
if ( MethodName.equals( aHandlerMethod1 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod1 + "\"" );
return true;
}
else if ( MethodName.equals( aHandlerMethod2 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod2 + "\"" );
return true;
}
return false;
}

public String[] getSupportedMethodNames() {
String[] retValue= new String[1];
retValue[0]= aHandlerMethod1;
retValue[1]= aHandlerMethod2;
return retValue;
}
</source>
The implementation is very simple to show only the logic. For the two handled method names the method displays a MessageBox and return true. Otherwise false is returned.

The other methods bound to the sample dialog control events are implemented using the other way. The interface <idl>com.sun.star.test.XTestDialogHandler</idl> looks like this:
<source lang="idl">
module com { module sun { module star { module test {
interface XTestDialogHandler {
string createDialog( [in] string DialogURL, [in] ::com::sun::star::frame::XModel xModel,
[in] ::com::sun::star::frame::XFrame xFrame );
void copyText( [in] ::com::sun::star::awt::XDialog xDialog, [in] any aEventObject );
void handleEvent();
void handleEventWithArguments( [in] ::com::sun::star::awt::XDialog xDialog,
[in] any aEventObject );
};
}; }; }; };
</source>
Besides the already described <code>createDialog</code> method three methods are defined to handle events. <code>handleEvent</code> and <code>handleEventWithArguments</code> are implemented very simple and only display a message box:
<source lang="java">
public void handleEvent() {
showMessageBox( "DialogComponent", "handleEvent() called" );
}

public void handleEventWithArguments( XDialog xDialog, Object aEventObject ) {
showMessageBox( "DialogComponent", "handleEventWithArguments() called\n\n" +
"Event Object = " + aEventObject );
}
</source>
The method copy text shows, how the passed XDialog interface can be used to access controls on the dialog itself. The details are not described here. For more information see [[Documentation/DevGuide/Basic/Creating Dialogs at Runtime|Creating Dialogs at Runtime]].
<source lang="java">
public void copyText( XDialog xDialog, Object aEventObject ) {
XControlContainer xControlContainer = (XControlContainer)UnoRuntime.queryInterface(
XControlContainer.class, xDialog );

String aTextPropertyStr = "Text";
String aText = "";
XControl xTextField1Control = xControlContainer.getControl( "TextField1" );
XControlModel xControlModel1 = xTextField1Control.getModel();
XPropertySet xPropertySet1 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel1 );
try {
aText = (String)xPropertySet1.getPropertyValue( aTextPropertyStr );
}
catch (Exception e) {
e.printStackTrace();
}

XControl xTextField2Control = xControlContainer.getControl( "TextField2" );
XControlModel xControlModel2 = xTextField2Control.getModel();
XPropertySet xPropertySet2 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel2 );
try {
xPropertySet2.setPropertyValue( aTextPropertyStr, aText );
}
catch (Exception e) {
e.printStackTrace();
}

showMessageBox( "DialogComponent", "copyText() called" );
}
</source>
Simple components using dialogs can be realized very easily by supporting <code>XDialogEventHandler</code> as then no own interfaces have to be created. For complex components it could make more sense to define handler interfaces to avoid a huge switch/case blocks in <code>XDialogEventHandler:: callHandlerMethod</code>.

{{PDL1}}

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

Documentation/DevGuide/WritingUNO/Using Dialogs in Components

2009-02-15T14:55:00Z

OOoLerner: /* Instantiate and display a dialog */

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2Accessing=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Assigning Component Methods to Control Events
|NextPage=Documentation/DevGuide/Extensions/Extensions
}}
[[zh:Zh/Documentation/DevGuide/WritingUNO/Using Dialogs in Components]]
{{DISPLAYTITLE:Using Dialogs in Components}}
In general components using dialogs are like any other component. But they need some additional code to instantiate and display the dialog(s) to be used and to accept the events created by the dialog controls.

=== Instantiate and display a dialog ===

To do this an extended version of the <idl>com.sun.star.awt.DialogProvider</idl> service - described in chapter [[Documentation/DevGuide/Scripting/Scripting Framework|Scripting Framework]] - has to be used. The extended service version <idl>com.sun.star.awt.DialogProvider2</idl> supports <idl>com.sun.star.awt.XDialogProvider2</idl> providing an additional method <idl>com.sun.star.awt.XDialog</idl> <tt>createDialogWithHandler(...)</tt> that allows to pass an interface when creating the dialog. This interface will be used as event handler and called if events are bound to the component.

The following code is taken from the DialogComponent SDK example that can be found in ''SDK/examples/DevelopersGuide/Components'' and shows how a dialog is created and displayed using the <code>DialogProvider2</code> service:
<source lang="java">
// XTestDialogHandler
public String createDialog( String DialogURL, XModel xModel, XFrame xFrame ) {
m_xFrame = xFrame;

try {
XMultiComponentFactory xMCF = m_xCmpCtx.getServiceManager();
Object obj;

// If valid we must pass the XModel when creating a DialogProvider object
if( xModel != null ) {
Object[] args = new Object[1];
args[0] = xModel;

obj = xMCF.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider2", args, m_xCmpCtx );
}
else {
obj = xMCF.createInstanceWithContext(
"com.sun.star.awt.DialogProvider2", m_xCmpCtx );
}

XDialogProvider2 xDialogProvider = (XDialogProvider2)
UnoRuntime.queryInterface( XDialogProvider2.class, obj );

XDialog xDialog = xDialogProvider.createDialogWithHandler( DialogURL, this );
if( xDialog != null )
xDialog.execute();
}
catch (Exception e) {
e.printStackTrace();
}
return "Created dialog \"" + DialogURL + "\"";
}
</source>
The variable <code>m_xCmpCtx</code> is the <idl>com.sun.star.uno.XComponentContext</idl> interface passed to the component while initialisation. If the dialog that should be created is placed inside a document a <idl>com.sun.star.frame.XModel</idl> interface <code>xModel</code> representing this document has to be passed. It's used as argument to initialise the DialogProvider service enabling the access to the document's Dialog Libraries. If <code>xModel</code> is null the dialog has to be placed in the application library container. This also has to be reflected in the DialogURL passed to the method.

Example code for a Basic/Dialog library <code>Library1</code> placed in a document:

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=document", _
ThisComponent, StarDesktop.getActiveFrame() )
End Sub

Example code for a Basic/Dialog library <code>Library1</code> placed in "My Macros":

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=application", _
null, StarDesktop.getActiveFrame() )
End Sub

The dialog contained in the ''DialogComponent.odt'' sample document in ''SDK/examples/DevelopersGuide/Components/DialogComponent'' looks like this.

[[Image:TestDialog.png|none|thumb|398px|Sample dialog with controls]]

The button labels show which component method is called in each case. The next chapter explains how these methods can be implemented inside the component. Method "doit3" isn't implemented at all. It's called in the sample dialog to show the resulting error message:

[[Image:ErrorMessage.png|none|thumb|264px|Error message for Component method not found]]

=== Accept events created by dialog controls ===

The event handling functionality can be implemented in two different ways. The test component described here uses both ways.

The first way is to implement the generic handler interface <idl>com.sun.star.awt.XDialogEventHandler</idl> containing two methods:
<source lang="idl">
interface XDialogEventHandler: com::sun::star::uno::XInterface
{
bool callHandlerMethod
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any Event,
[in] string MethodName
)

sequence<string> getSupportedMethodNames();
}
</source>
If an event occurs that is bound to a component method and the component implements this interface, the method <code>callHandlerMethod</code> will be called first, with the method name used in the event binding passed as <code>MethodName</code> parameter. In this example this would be:
<source lang="java">
xHandler.callHandlerMethod( xDialog, aEvent, "handleEvent" );
</source>
<code>xDialog</code> points to the same dialog instance that has been returned by the <code>createDialogWithHandler()</code> method. Event represents the event object originally passed to the awt listener method. E.g. in case of the "When initiating" event used in this example the corresponding awt listener interface is <idl>com.sun.star.awt.XActionListener</idl> and an <idl>com.sun.star.awt.ActionEvent</idl> is passed to its <code>actionPerformed</code> method when the event occurs. This <code>ActionEvent</code> object will also be passed to <code>callHandlerMethod</code>. The Event object has to be passed as any, because other events use different listener interfaces with other event object types. <code>callHandlerMethod</code> returns a bool value. Returning true means that the event has been handled.

The method <code>getSupportedMethodNames()</code> should return the names of all methods handled by <code>callHandlerMethod()</code>. It's intended for later use, especially to expand the user interface to allow browsing a component's methods.

If the event has not been handled, because <code>callHandlerMethod</code> returns false or <idl>com.sun.star.awt.XDialogEventHandler</idl> isn't supported at all by the component, the DialogProvider uses the <idl>com.sun.star.beans.Introspection</idl> service to detect if one of the following methods is provided by one of the interfaces supported by the component:
<source lang="idl">
void [MethodName]
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any aEvent
);
</source>
or
<source lang="idl">
void [MethodName]( void );
</source>
The second method is only used if the first one is not available. In this example the component would have to support an interface containing a method <code>handleEvent</code> with one of these signatures. It also has to support <idl>com.sun.star.lang.XTypeProvider</idl> because otherwise the introspection mechanism does not work.

As already mentioned the sample component supports both ways to implement handler methods. <idl>com.sun.star.awt.XDialogEventHandler</idl> is implemented like this:
<source lang="java">
private String aHandlerMethod1 = "doit1";
private String aHandlerMethod2 = "doit2";

//XDialogEventHandler
public boolean callHandlerMethod( /*IN*/XDialog xDialog, /*IN*/Object EventObject,
/*IN*/String MethodName ) {
if ( MethodName.equals( aHandlerMethod1 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod1 + "\"" );
return true;
}
else if ( MethodName.equals( aHandlerMethod2 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod2 + "\"" );
return true;
}
return false;
}

public String[] getSupportedMethodNames() {
String[] retValue= new String[1];
retValue[0]= aHandlerMethod1;
retValue[1]= aHandlerMethod2;
return retValue;
}
</source>
The implementation is very simple to show only the logic. For the two handled method names the method displays a MessageBox and return true. Otherwise false is returned.

The other methods bound to the sample dialog control events are implemented using the other way. The interface <idl>com.sun.star.test.XTestDialogHandler</idl> looks like this:
<source lang="idl">
module com { module sun { module star { module test {
interface XTestDialogHandler {
string createDialog( [in] string DialogURL, [in] ::com::sun::star::frame::XModel xModel,
[in] ::com::sun::star::frame::XFrame xFrame );
void copyText( [in] ::com::sun::star::awt::XDialog xDialog, [in] any aEventObject );
void handleEvent();
void handleEventWithArguments( [in] ::com::sun::star::awt::XDialog xDialog,
[in] any aEventObject );
};
}; }; }; };
</source>
Besides the already described <code>createDialog</code> method three methods are defined to handle events. <code>handleEvent</code> and <code>handleEventWithArguments</code> are implemented very simple and only display a message box:
<source lang="java">
public void handleEvent() {
showMessageBox( "DialogComponent", "handleEvent() called" );
}

public void handleEventWithArguments( XDialog xDialog, Object aEventObject ) {
showMessageBox( "DialogComponent", "handleEventWithArguments() called\n\n" +
"Event Object = " + aEventObject );
}
</source>
The method copy text shows, how the passed XDialog interface can be used to access controls on the dialog itself. The details are not described here. For more information see [[Documentation/DevGuide/Basic/Creating Dialogs at Runtime|Creating Dialogs at Runtime]].
<source lang="java">
public void copyText( XDialog xDialog, Object aEventObject ) {
XControlContainer xControlContainer = (XControlContainer)UnoRuntime.queryInterface(
XControlContainer.class, xDialog );

String aTextPropertyStr = "Text";
String aText = "";
XControl xTextField1Control = xControlContainer.getControl( "TextField1" );
XControlModel xControlModel1 = xTextField1Control.getModel();
XPropertySet xPropertySet1 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel1 );
try {
aText = (String)xPropertySet1.getPropertyValue( aTextPropertyStr );
}
catch (Exception e) {
e.printStackTrace();
}

XControl xTextField2Control = xControlContainer.getControl( "TextField2" );
XControlModel xControlModel2 = xTextField2Control.getModel();
XPropertySet xPropertySet2 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel2 );
try {
xPropertySet2.setPropertyValue( aTextPropertyStr, aText );
}
catch (Exception e) {
e.printStackTrace();
}

showMessageBox( "DialogComponent", "copyText() called" );
}
</source>
Simple components using dialogs can be realized very easily by supporting <code>XDialogEventHandler</code> as then no own interfaces have to be created. For complex components it could make more sense to define handler interfaces to avoid a huge switch/case blocks in <code>XDialogEventHandler:: callHandlerMethod</code>.

{{PDL1}}

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

Documentation/DevGuide/WritingUNO/Using Dialogs in Components

2009-02-15T14:54:23Z

OOoLerner: /* Instantiate and display a dialog */

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2Accessing=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Assigning Component Methods to Control Events
|NextPage=Documentation/DevGuide/Extensions/Extensions
}}
[[zh:Zh/Documentation/DevGuide/WritingUNO/Using Dialogs in Components]]
{{DISPLAYTITLE:Using Dialogs in Components}}
In general components using dialogs are like any other component. But they need some additional code to instantiate and display the dialog(s) to be used and to accept the events created by the dialog controls.

=== Instantiate and display a dialog ===

To do this an extended version of the <idl>com.sun.star.awt.DialogProvider</idl> service - described in chapter [[Documentation/DevGuide/Scripting/Scripting Framework|Scripting Framework]] - has to be used. The extended service version <idl>com.sun.star.awt.DialogProvider2</idl> supports <idl>com.sun.star.awt.XDialogProvider2</idl> providing an additional method <idl>com.sun.star.awt.XDialog</idl> <tt>createDialogWithHandler(...)</tt> that allows to pass an interface when creating the dialog. This interface will be used as event handler and called if events are bound to the component.

The following code is take from the DialogComponent SDK example that can be found in ''SDK/examples/DevelopersGuide/Components'' and shows how a dialog is created and displayed using the <code>DialogProvider2</code> service:
<source lang="java">
// XTestDialogHandler
public String createDialog( String DialogURL, XModel xModel, XFrame xFrame ) {
m_xFrame = xFrame;

try {
XMultiComponentFactory xMCF = m_xCmpCtx.getServiceManager();
Object obj;

// If valid we must pass the XModel when creating a DialogProvider object
if( xModel != null ) {
Object[] args = new Object[1];
args[0] = xModel;

obj = xMCF.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider2", args, m_xCmpCtx );
}
else {
obj = xMCF.createInstanceWithContext(
"com.sun.star.awt.DialogProvider2", m_xCmpCtx );
}

XDialogProvider2 xDialogProvider = (XDialogProvider2)
UnoRuntime.queryInterface( XDialogProvider2.class, obj );

XDialog xDialog = xDialogProvider.createDialogWithHandler( DialogURL, this );
if( xDialog != null )
xDialog.execute();
}
catch (Exception e) {
e.printStackTrace();
}
return "Created dialog \"" + DialogURL + "\"";
}
</source>
The variable <code>m_xCmpCtx</code> is the <idl>com.sun.star.uno.XComponentContext</idl> interface passed to the component while initialisation. If the dialog that should be created is placed inside a document a <idl>com.sun.star.frame.XModel</idl> interface <code>xModel</code> representing this document has to be passed. It's used as argument to initialise the DialogProvider service enabling the access to the document's Dialog Libraries. If <code>xModel</code> is null the dialog has to be placed in the application library container. This also has to be reflected in the DialogURL passed to the method.

Example code for a Basic/Dialog library <code>Library1</code> placed in a document:

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=document", _
ThisComponent, StarDesktop.getActiveFrame() )
End Sub

Example code for a Basic/Dialog library <code>Library1</code> placed in "My Macros":

Sub TestDialogComponent()
oComp = CreateUnoService( "com.sun.star.test.TestDialogHandler" )
oComp.createDialog( "vnd.sun.star.script:Library1.Dialog1?location=application", _
null, StarDesktop.getActiveFrame() )
End Sub

The dialog contained in the ''DialogComponent.odt'' sample document in ''SDK/examples/DevelopersGuide/Components/DialogComponent'' looks like this.

[[Image:TestDialog.png|none|thumb|398px|Sample dialog with controls]]

The button labels show which component method is called in each case. The next chapter explains how these methods can be implemented inside the component. Method "doit3" isn't implemented at all. It's called in the sample dialog to show the resulting error message:

[[Image:ErrorMessage.png|none|thumb|264px|Error message for Component method not found]]

=== Accept events created by dialog controls ===

The event handling functionality can be implemented in two different ways. The test component described here uses both ways.

The first way is to implement the generic handler interface <idl>com.sun.star.awt.XDialogEventHandler</idl> containing two methods:
<source lang="idl">
interface XDialogEventHandler: com::sun::star::uno::XInterface
{
bool callHandlerMethod
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any Event,
[in] string MethodName
)

sequence<string> getSupportedMethodNames();
}
</source>
If an event occurs that is bound to a component method and the component implements this interface, the method <code>callHandlerMethod</code> will be called first, with the method name used in the event binding passed as <code>MethodName</code> parameter. In this example this would be:
<source lang="java">
xHandler.callHandlerMethod( xDialog, aEvent, "handleEvent" );
</source>
<code>xDialog</code> points to the same dialog instance that has been returned by the <code>createDialogWithHandler()</code> method. Event represents the event object originally passed to the awt listener method. E.g. in case of the "When initiating" event used in this example the corresponding awt listener interface is <idl>com.sun.star.awt.XActionListener</idl> and an <idl>com.sun.star.awt.ActionEvent</idl> is passed to its <code>actionPerformed</code> method when the event occurs. This <code>ActionEvent</code> object will also be passed to <code>callHandlerMethod</code>. The Event object has to be passed as any, because other events use different listener interfaces with other event object types. <code>callHandlerMethod</code> returns a bool value. Returning true means that the event has been handled.

The method <code>getSupportedMethodNames()</code> should return the names of all methods handled by <code>callHandlerMethod()</code>. It's intended for later use, especially to expand the user interface to allow browsing a component's methods.

If the event has not been handled, because <code>callHandlerMethod</code> returns false or <idl>com.sun.star.awt.XDialogEventHandler</idl> isn't supported at all by the component, the DialogProvider uses the <idl>com.sun.star.beans.Introspection</idl> service to detect if one of the following methods is provided by one of the interfaces supported by the component:
<source lang="idl">
void [MethodName]
(
[in] com::sun::star::awt::XDialog xDialog,
[in] any aEvent
);
</source>
or
<source lang="idl">
void [MethodName]( void );
</source>
The second method is only used if the first one is not available. In this example the component would have to support an interface containing a method <code>handleEvent</code> with one of these signatures. It also has to support <idl>com.sun.star.lang.XTypeProvider</idl> because otherwise the introspection mechanism does not work.

As already mentioned the sample component supports both ways to implement handler methods. <idl>com.sun.star.awt.XDialogEventHandler</idl> is implemented like this:
<source lang="java">
private String aHandlerMethod1 = "doit1";
private String aHandlerMethod2 = "doit2";

//XDialogEventHandler
public boolean callHandlerMethod( /*IN*/XDialog xDialog, /*IN*/Object EventObject,
/*IN*/String MethodName ) {
if ( MethodName.equals( aHandlerMethod1 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod1 + "\"" );
return true;
}
else if ( MethodName.equals( aHandlerMethod2 ) ) {
showMessageBox( "DialogComponent", "callHandlerMethod() handled \"" + aHandlerMethod2 + "\"" );
return true;
}
return false;
}

public String[] getSupportedMethodNames() {
String[] retValue= new String[1];
retValue[0]= aHandlerMethod1;
retValue[1]= aHandlerMethod2;
return retValue;
}
</source>
The implementation is very simple to show only the logic. For the two handled method names the method displays a MessageBox and return true. Otherwise false is returned.

The other methods bound to the sample dialog control events are implemented using the other way. The interface <idl>com.sun.star.test.XTestDialogHandler</idl> looks like this:
<source lang="idl">
module com { module sun { module star { module test {
interface XTestDialogHandler {
string createDialog( [in] string DialogURL, [in] ::com::sun::star::frame::XModel xModel,
[in] ::com::sun::star::frame::XFrame xFrame );
void copyText( [in] ::com::sun::star::awt::XDialog xDialog, [in] any aEventObject );
void handleEvent();
void handleEventWithArguments( [in] ::com::sun::star::awt::XDialog xDialog,
[in] any aEventObject );
};
}; }; }; };
</source>
Besides the already described <code>createDialog</code> method three methods are defined to handle events. <code>handleEvent</code> and <code>handleEventWithArguments</code> are implemented very simple and only display a message box:
<source lang="java">
public void handleEvent() {
showMessageBox( "DialogComponent", "handleEvent() called" );
}

public void handleEventWithArguments( XDialog xDialog, Object aEventObject ) {
showMessageBox( "DialogComponent", "handleEventWithArguments() called\n\n" +
"Event Object = " + aEventObject );
}
</source>
The method copy text shows, how the passed XDialog interface can be used to access controls on the dialog itself. The details are not described here. For more information see [[Documentation/DevGuide/Basic/Creating Dialogs at Runtime|Creating Dialogs at Runtime]].
<source lang="java">
public void copyText( XDialog xDialog, Object aEventObject ) {
XControlContainer xControlContainer = (XControlContainer)UnoRuntime.queryInterface(
XControlContainer.class, xDialog );

String aTextPropertyStr = "Text";
String aText = "";
XControl xTextField1Control = xControlContainer.getControl( "TextField1" );
XControlModel xControlModel1 = xTextField1Control.getModel();
XPropertySet xPropertySet1 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel1 );
try {
aText = (String)xPropertySet1.getPropertyValue( aTextPropertyStr );
}
catch (Exception e) {
e.printStackTrace();
}

XControl xTextField2Control = xControlContainer.getControl( "TextField2" );
XControlModel xControlModel2 = xTextField2Control.getModel();
XPropertySet xPropertySet2 = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xControlModel2 );
try {
xPropertySet2.setPropertyValue( aTextPropertyStr, aText );
}
catch (Exception e) {
e.printStackTrace();
}

showMessageBox( "DialogComponent", "copyText() called" );
}
</source>
Simple components using dialogs can be realized very easily by supporting <code>XDialogEventHandler</code> as then no own interfaces have to be created. For complex components it could make more sense to define handler interfaces to avoid a huge switch/case blocks in <code>XDialogEventHandler:: callHandlerMethod</code>.

{{PDL1}}

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

Documentation/DevGuide/OpenOffice.org Developers Guide

2009-02-15T14:10:33Z

OOoLerner: /* How This Book is Organized */

{{Documentation/DevGuide/DevGuideTOC
|ShowPrevNext=block
|ShowPrevPage=none
|NextPage=Documentation/DevGuide/FirstSteps/First Steps
}}
[[zh:Zh/Documentation/DevGuide/OpenOffice.org Developers Guide]]
{{DISPLAYTITLE:OpenOffice.org Developer's Guide}}
__NOTOC__
[[Documentation/DevGuide/Contributing_to_the_Developers_Guide|Contributing to the Developer's Guide]]
=== What This Manual Covers ===

This manual describes how to write programs using the component technology UNO (Universal Network Objects) with {{PRODUCTNAME}}.

Most examples provided are written in Java. As well as Java, the language binding for C++, the UNO access for {{PRODUCTNAME}} Basic and the OLE Automation bridge that uses {{PRODUCTNAME}} through Microsoft's component technology COM/DCOM is described.

=== How This Book is Organized ===

Every page of this book has a Table of Contents at the right side of the page. This TOC shows the content of the current part and navigation links to browse parts and pages of this book.

[[Documentation/DevGuide/FirstSteps/First_Steps|'''First Steps''']]
:The First Steps chapter describes the setting up of a Java UNO development environment to achieve the solutions you need. At the end of this chapter, you will be equipped with the essentials required for the following chapters about the {{PRODUCTNAME}} applications.

[[Documentation/DevGuide/ProUNO/Professional_UNO|''' Professional UNO''']]
:This chapter introduces API and UNO concepts and explains the specifics of the programming languages and technologies that can be used with UNO. It will help you to write industrial strength UNO programs, use one of the languages besides Java or improve your understanding of the API reference.

[[Documentation/DevGuide/WritingUNO/Writing_UNO_Components|''' Writing UNO Components ''']]
: This chapter describes how to write UNO components. It also provides an insight into the UNOIDL (UNO Interface Definition Language) language and the inner workings of the service manager. Before beginning this chapter, you should be familiar with the First Steps and Professional UNO chapters.

[[Documentation/DevGuide/Extensions/Extensions|''' Extensions ''']]
: This chapter describes the various aspects of OpenOffice.org Extensions. It explains the specifics of how Extensions can be developed, and provides an overview of the various things that you must do to develop your own Extension.

[[Documentation/DevGuide/AdvUNO/Advanced_UNO|''' Advanced UNO ''']]
:This chapter describes the technical basis of UNO, how the language bindings and bridges work, how the service manager goes about its tasks and what the core reflection actually does.

[[Documentation/DevGuide/OfficeDev/Office_Development|''' Office Development ''']]
:This chapter describes the application framework of the {{PRODUCTNAME}} application that includes how the {{PRODUCTNAME}} API deals with the {{PRODUCTNAME}} application and the features available across all parts of {{PRODUCTNAME}}.

[[Documentation/DevGuide/Text/Text_Documents|'''Text Documents''']]

[[Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents|'''Spreadsheet Documents''']]

[[Documentation/DevGuide/Drawings/Drawing_Documents_and_Presentation_Documents|'''Drawings and Presentations''']]

[[Documentation/DevGuide/Charts/Charts|'''Charts''']]

:These chapters describe how {{PRODUCTNAME}} revolves around documents. These chapters teach you what to do with these documents programmatically.

[[Documentation/DevGuide/Basic/OpenOffice.org_Basic|''' OpenOffice.org Basic ''']]
:This chapter provides the functionality to create and manage Basic macros and dialogs.

[[Documentation/DevGuide/Database/Database_Access|''' Database Access ''']]
:This chapter describes how you can take advantage of this capability in your own projects. {{PRODUCTNAME}} can connect to databases in a universal manner.

[[Documentation/DevGuide/Forms/Forms|''' Forms ''']]
:This chapter describes how {{PRODUCTNAME}} documents contain form controls that are programmed using an event-driven programming model. The Forms chapter shows you how to enhance your documents with controls for data input.

[[Documentation/DevGuide/UCB/Universal_Content_Broker|''' Universal Content Broker ''']]
:This chapter describes how the Universal Content Broker is the generic resource access service used by the entire office application. It handles not only files and directories, but hierarchic and non-hierarchic contents, in general.

[[Documentation/DevGuide/Config/Configuration_Management|''' Configuration Management ''']]
:This chapter describes how the {{PRODUCTNAME}} API offers access to the office configuration options that are found in the '''Tools > Options''' dialog.

[[Documentation/DevGuide/JavaBean/JavaBean_for_Office_Components|''' JavaBean for Office Components ''']]
:This chapter describes how the OfficeBean JavaBean component allows the developer to integrate office functionality in Java applications.

[[Documentation/DevGuide/Accessibility/Accessibility|'''Accessibility''']]
: This chapter explains the Accessibility API, and how you can work to bring your applications in line with accessibility requirements.

[[Documentation/DevGuide/Scripting/Scripting_Framework|'''Scripting Framework''']]
: This chapter describes the user interface features of the Scripting Framework, and provides a guide on how to get started with writing Scripting Framework macros.

[[Documentation/DevGuide/GUI/Graphical_User_Interfaces|'''Graphical User Interfaces''']]
: This chapter is for extension developers who want to add functionality to their {{PRODUCTNAME}} application and want to create a consistent user interface. It explains how you can add your own GUI to your {{PRODUCTNAME}} applications.

[[Documentation/DevGuide/AppendixA/{{PRODUCTNAME}}_API-Design-Guidelines|'''Guidelines and Specifications''']]
:The guidelines and specifications provide extra information about the {{PRODUCTNAME}} API.

=== Appendices ===

[[Documentation/DevGuide/AppendixB/IDL_Documentation_Guidelines|'''IDL Documentation Guidelines''']]
:How IDL files are used to create correct online documentation for the OpenOffice.org API.

[[Documentation/DevGuide/AppendixC/Universal_Content_Providers|'''Universal Content Providers''']]
:A listing of universal content providers.

[[Documentation/DevGuide/AppendixD/UNOIDL_Syntax_Specification|'''UNOIDL Syntax Specification''']]
:A listing of the language specification for UNOIDL in pseudo BNF notation (the IDL grammar).

[[Documentation/DevGuide/Glossary/Glossary|'''Glossary''']]
:Definition and explanation of {{PRODUCTNAME}} terms, concepts and abbreviations.

=== OpenOffice.org Version History ===
OpenOffice.org exists in two versions:

* OpenOffice.org - an open source edition [http://www.openoffice.org www.openoffice.org]
* StarOffice and StarSuite - "branded" editions derived from OpenOffice.org

In 2000, Sun Microsystems released the source code of their current developer version of StarOffice on [http://www.openoffice.org www.openoffice.org], and made the ongoing development process public. Sun's development team, which developed StarOffice, continued its work on [http://www.openoffice.org www.openoffice.org], and developers from all over the world joined them to port, translate, repair bugs and discuss future plans. StarOffice 6.0 and OpenOffice.org 1.0, which were released in spring 2002, share the same code basis.

=== Related documentation ===

The api and udk projects on [http://www.openoffice.org www.openoffice.org] have related documentation, examples and FAQs (frequently asked questions) on the {{PRODUCTNAME}} API. Most important are probably the references, you can find them at [http://api.openoffice.org api.openoffice.org] or [http://udk.openoffice.org udk.openoffice.org].
* The API Reference covers the programmable features of {{PRODUCTNAME}}.
* The Java Reference describes the features of the Java UNO runtime environment.
* The C++ Reference is about the C++ language binding.

=== Conventions ===
This book uses the following formatting conventions:
* '''Bold''' refers to the keys on the keyboard or elements of a user interface, such as the OK button or File menu.
* ''Italics'' are used for emphasis and to signify the first use of a term. Italics are also used for web sites, file and directory names and email addresses.
* <code>Courier New</code> is used in all Code Listings and for everything that is typed when programming.

=== Acknowledgments ===
A publication like this can never be the work of a single person – it is the result of tremendous team effort. Of course, the OpenOffice.org/StarOffice development team played the most important role by creating the API in the first place. The knowledge and experience of this team will be documented here. Furthermore, there were several devoted individuals who contributed to making this documentation reality.

First of all, we would like to thank Ralf Kuhnert and Dietrich Schulten. Using their technical expertise and articulate mode of expression, they accomplished the challenging task of gathering the wealth of API knowledge from the minds of the developers and transforming it into an understandable document.

Many reviewers were involved in the creation of this documentation. Special thanks go to Michael Hönnig who was one of the few who reviewed almost every single word. His input also played a decisive role in how the documentation was structured. A big thank you also goes to Diane O'Brien for taking on the daunting task of reviewing the final draft and providing us with extensive feed back at such short notice.

When looking at the diagrams and graphics, it is clear that a creative person with the right touch for design and aesthetics was involved. Many thanks, therefore, are due Stella Schulze who redrew all of the diagrams and graphics from the originals supplied by various developers. We also thank Svante Schubert who converted the original XML file format into HTML pages and was most patient with us in spite of our demands and changes. Special thanks also to Jörg Heilig, who made this whole project possible.

Jürgen would like to thank Götz Wohlberg for all his help in getting the right people involved and making sure things ran smoothly.

Götz would like to thank Jürgen Schmidt for his never-ending energy to hold everything together and for pushing the contributors in the right direction. He can be considered as the heart of the opus because of his guidance and endurance throughout the entire project.

We would like to take this opportunity to thank all these people – and anyone else we forgot! – for their support.

Jürgen Schmidt, Götz Wohlberg

[[Category: Documentation/Developer's Guide]]
[[Category:Development]]
[[Category:Documentation]]
{{PDL1}}

Documentation/DevGuide/Scripting/Writing Macros

2009-02-15T13:28:23Z

OOoLerner: /* The HelloWorld macro */

{{Documentation/DevGuide/ScriptingTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Macro Recording
|NextPage=Documentation/DevGuide/Scripting/How the Scripting Framework Works
}}
{{DISPLAYTITLE:Writing Macros}}
__NOTOC__
=== The HelloWorld macro ===

When the user creates a new macro in BeanShell or JavaScript, the default content of the macro is the HelloWorld. Here is what the code looks like for BeanShell:

import com.sun.star.uno.UnoRuntime;

import com.sun.star.text.XTextDocument;
import com.sun.star.text.XText;
import com.sun.star.text.XTextRange;

oDoc = context.getDocument();
xTextDoc = (XTextDocument) UnoRuntime.queryInterface(XTextDocument.class,oDoc);
xText = xTextDoc.getText();
xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in BeanShell)" );

// BeanShell OpenOffice.org scripts should always return 0
return 0;

Here is the same code in JavaScript:
<source lang="javascript">
importClass(Packages.com.sun.star.uno.UnoRuntime);
importClass(Packages.com.sun.star.text.XTextDocument);
importClass(Packages.com.sun.star.text.XText);
importClass(Packages.com.sun.star.text.XTextRange);

oDoc = XSCRIPTCONTEXT.getDocument();
xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc);
xText = xTextDoc.getText();
xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in JavaScript)" );
</source>
Here is the code for HelloWorld in Java:
<source lang="java">
import com.sun.star.uno.UnoRuntime;
import com.sun.star.frame.XModel;
import com.sun.star.text.XTextDocument;
import com.sun.star.text.XTextRange;
import com.sun.star.text.XText;
import com.sun.star.script.provider.XScriptContext;

public class HelloWorld {
public static void printHW(XScriptContext xScriptContext)
{
XModel xDocModel = xScriptContext.getDocument();

// getting the text document object
XTextDocument xtextdocument = (XTextDocument) UnoRuntime.queryInterface(
XTextDocument.class, xDocModel);

XText xText = xtextdocument.getText();
XTextRange xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in Java)" );
}
}
</source>
The table below outlines some of the features of macro development in the different languages:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Language
!Interpreted
!Typeless
!Editor
!Debugger
|-
|BeanShell
|Yes
|Yes
|Yes
|No
|-
|JavaScript
|Yes
|Yes
|Yes
|Yes
|-
|Java
|No
|No
|No
|No
|}

{{Documentation/Note|Instructions on compiling and deploying Java macros can be found later in this chapter.}}

=== Using the {{PRODUCTNAME}} API from macros ===

All BeanShell, JavaScript and Java macros are supplied with a variable of type <idl>com.sun.star.script.provider.XScriptContext</idl> which can be used to access the {{PRODUCTNAME}} API. This type has three methods:

* <idl>com.sun.star.frame.XModel</idl> <code>getDocument( )</code>
:Returns the <code>XModel</code> interface of the document for which the macro was invoked (see [[Documentation/DevGuide/OfficeDev/Using the Component Framework|Using the Component Framework]])
* <idl>com.sun.star.frame.XDesktop</idl> <code>getDesktop( )</code>
:Returns the <code>XDesktop</code> interface for the application which can be used to access open document, and load documents (see [[Documentation/DevGuide/OfficeDev/Using the Desktop|Using the Desktop]])
* <idl>com.sun.star.uno.XComponentContext</idl> <code>getComponentContext( )</code>
:Returns the <code>XComponentContext</code> interface which is used to create instances of services (see [[Documentation/DevGuide/ProUNO/Service Manager and Component Context|Service Manager and Component Context]])

Depending on the language the macro accesses the <code>XScriptContext</code> type in different ways:

* '''BeanShell''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''JavaScript''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''Java''': The first parameter passed to the macro method is always of type <code>XScriptContext</code>
Xmodel xDocModel = xScriptContext.getDocument();

=== Handling arguments passed to macros ===

In certain cases arguments may be passed to macros, for example, when a macro is assigned to a button in a document. In this case the arguments are passed to the macro as follows:

* '''BeanShell''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = (ActionEvent) ARGUMENTS[0];

* '''JavaScript''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = ARGUMENTS[0];

* '''Java''': The arguments are passed as an <code>Object[]</code> in the second parameter to the macro method
public void handleButtonPress(
XScriptContext xScriptContext, Object[] args)

Each of the arguments in the <code>Object[]</code> are of the UNO type Any. For more information on how the Any type is used in Java see [[Documentation/DevGuide/ProUNO/Java/Type Mappings|Type Mappings]].

The ButtonPressHandler macros in the Highlight library of a {{PRODUCTNAME}} installation show how a macro can handle arguments.

=== Creating dialogs from macros ===

Dialogs which have been built in the Dialog Editor can be loaded by macros using the <idl>com.sun.star.awt.XDialogProvider</idl> API. The <code>XDialogProvider</code> interface has one method <code>createDialog()</code> which takes a string as a parameter. This string is the URL to the dialog. The URL is formed as follows:

vnd.sun.star.script:DIALOGREF?location=[application|document]

where <code>DIALOGREF</code> is the name of the dialog that you want to create, and location is either application or document depending on where the dialog is stored.

For example if you wanted to load dialog called MyDialog, which is in a Dialog Library called MyDialogLibrary in the {{PRODUCTNAME}} dialogs area of your installation then the URL would be:

vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application

If you wanted to load a dialog called MyDocumentDialog which in a library called MyDocumentLibrary which is located in a document then the URL would be:

vnd.sun.star.script:MyDocumentLibrary.MyDocumentDialog?location=document

The following code shows how to create a dialog from a Java macro:
<source lang="java">
public XDialog getDialog(XScriptContext context)
{
XDialog theDialog;

// We must pass the XModel of the current document when creating a DialogProvider object
Object[] args = new Object[1];
args[0] = context.getDocument();

Object obj;
try {
obj = xmcf.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider", args, context.getComponentContext());
}
catch (com.sun.star.uno.Exception e) {
System.err.println("Error getting DialogProvider object");
return null;
}

XDialogProvider xDialogProvider = (XDialogProvider)
UnoRuntime.queryInterface(XDialogProvider.class, obj);

// Got DialogProvider, now get dialog
try {
theDialog = xDialogProvider.createDialog(
"vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application");
}
catch (java.lang.Exception e) {
System.err.println("Got exception on first creating dialog: " + e.getMessage());
}
return theDialog;
}
</source>
=== Compiling and Deploying Java macros ===

Because Java is a compiled language it is not possible to execute Java source code as a macro directly from within {{PRODUCTNAME}}. The code must first be compiled and then deployed within a {{PRODUCTNAME}} installation or document. The following steps show how to create a Java macro using the HelloWorld example code:

* Create a ''HelloWorld'' directory for your macro
* Create a ''HelloWorld.java'' file using the HelloWorld source code
* Compile the ''HelloWorld.java'' file. The following jar files from the ''program/classes'' directory of a {{PRODUCTNAME}} installation must be in the classpath: ''ridl.jar'', ''unoil.jar'', ''jurt.jar''
* Create a ''HelloWorld.jar'' file containing the ''HelloWorld.class'' file
* Create a ''parcel-descriptor.xml'' file for your macro
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<parcel language="Java" xmlns:parcel="scripting.dtd">
<script language="Java">
<locale lang="en">
<displayname value="HelloWorld"/>
<description>
Prints "Hello World".
</description>
</locale>
<functionname value="HelloWorld.printHW"/>
<logicalname value="HelloWorld.printHW"/>
<languagedepprops>
<prop name="classpath" value="HelloWorld.jar"/>
</languagedepprops>
</script>
</parcel>
</source>
The ''parcel-descriptor.xml'' file is used by the Scripting Framework to find macros. The functionname element indicates the name of the Java method which should be executed as a macro. The classpath element can be used to indicate any jar or class files which are used by the macro. If the classpath element is not included, then the directory in which the ''parcel-desciptor.xml'' file is found and any jar files in that directory will be used as the classpath. The necessary Java UNO classes are available automatically.

* Copy the HelloWorld directory into the ''share/Scripts/java'' directory of a {{PRODUCTNAME}} installation or into the ''user/Scripts/java'' directory of a user installation. If you want to deploy the macro to a document you need to place it in a ''Scripts/java'' directory within the document zip file.
* If {{PRODUCTNAME}} is running, you will need to restart it in order for the macro to appear in the Macro Selector dialog.

{{Documentation/Note|The ''parcel-descriptor.xml'' file is also used to detect BeanShell and JavaScript macros. It is created automatically when creating macros using the Organizer dialogs for BeanShell and JavaScript.}}

{{PDL1}}

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

Documentation/DevGuide/Scripting/Macro Recording

2009-02-15T13:05:32Z

OOoLerner:

{{Documentation/DevGuide/ScriptingTOC
|Scripting2b=block
|ScriptingEdit=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Basic and Dialogs
|NextPage=Documentation/DevGuide/Scripting/Writing Macros
}}
{{DISPLAYTITLE:Macro Recording}}
Macro Recording is only supported for {{PRODUCTNAME}} Basic and is accessible via the '''Tools > Macro > Record Macro''' menu item.

{{PDL1}}

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

Documentation/DevGuide/Scripting/JavaScript Editor

2009-02-15T13:04:43Z

OOoLerner:

{{Documentation/DevGuide/ScriptingTOC
|Scripting2b=block
|ScriptingEdit=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/BeanShell Editor
|NextPage=Documentation/DevGuide/Scripting/Basic and Dialogs
}}
{{DISPLAYTITLE:JavaScript Editor}}
Clicking the Edit button in the JavaScript Organizer will open the Rhino JavaScript Debugger:

[[Image:JavaScriptEditorNoTabs.png|none|thumb|400px|JavaScript Debugger]]

The source of the JavaScript macro is displayed in the main window. The line numbers are shown in the left-hand sidebar. Clicking in the sidebar will set and remove breakpoints in the macro. There is currently a bug in the debugger which is not clearing the symbol in the sidebar when breakpoints are removed.

The contents of the text window can be saved by selecting the '''File > Save''' menu item. The macro can be run by selecting the '''File > Run''' menu item. This activates the four buttons above the main text window:

* Break
:Sets a breakpoint at the line where the cursor is.
* Go
:Runs the macro, stopping at the next breakpoint (if one is set).
* Step Into
:Runs a single line of code, stepping into functions if they exist and then stop.
* Step Over
:Runs a single line of code, without stepping into functions and then stop.
* Step Out
:Continues the execution of the macro until it exits the current function.
There are two other panes in the debugger which are hidden by default. These allow the developer to view the stack and watch variables:

[[Image:JavaScriptEditorWithTabs.png|none|thumb|400px|JavaScript Debugger with Stack and Watch tabs displayed]]

For more information on the Rhino JavaScript Debugger see [http://www.mozilla.org/rhino/debugger.html http://www.mozilla.org/rhino/debugger.html].

{{PDL1}}

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

Documentation/DevGuide/Scripting/Editing, Creating and Managing Macros

2009-02-15T13:03:32Z

OOoLerner:

{{Documentation/DevGuide/ScriptingTOC
|Scripting2b=block
|ScriptingEdit=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Running Macros
|NextPage=Documentation/DevGuide/Scripting/The Organizer dialogs for BeanShell and JavaScript
}}
{{DISPLAYTITLE:Editing, Creating and Managing Macros}}
The Scripting Framework provides support for editing, creating and managing macros via the '''Tools > Macro > Organize Macros''' menu. From there you can open a macro management dialog for BeanShell, JavaScript or {{PRODUCTNAME}} Basic macros.

{{PDL1}}

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

Documentation/DevGuide/Scripting/Running Macros

2009-02-15T13:02:48Z

OOoLerner:

{{Documentation/DevGuide/ScriptingTOC
|Scripting2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Using the Scripting Framework
|NextPage=Documentation/DevGuide/Scripting/Editing, Creating and Managing Macros
}}
{{DISPLAYTITLE:Running Macros}}
To run a macro use the menu item '''Tools > Macros > Run Macro...''' This opens the Macro Selector dialog:

[[Image:MacroSelectorDialog.png|none|thumb|400px|Macro Selector dialog]]

The Library list box contains a tree representation of all macro libraries. At the top level, there are three entries:

* My Macros (macros belonging to the current user)
* {{PRODUCTNAME}} Macros (macros available to all users of the installation)
* DocumentName Macros (macros contained in the currently active document)
Each of these entries can be expanded to show any macro libraries they contain. When a library has been selected, the macros contained in that library are displayed in the Macro name list box. When a macro is selected its description, if one exists, is displayed at the bottom of the dialog. Selecting a macro and clicking Run will close the dialog and run the macro. Clicking Cancel will close the dialog without running a macro.

Macros can also be run directly from the Macro Organizer [[Documentation/DevGuide/Scripting/Editing, Creating and Managing Macros|Editing, Creating and Managing Macros]] and from some of the macro editors.

{{PDL1}}

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

Documentation/OOo3 User Guides/Getting Started/Choosing language settings

2009-02-15T12:39:31Z

OOoLerner:

{{DISPLAYTITLE:Choosing language settings}}
{{Documentation/SetupOOo3TOC
|ShowPrevNext=block
|PrevPage=Documentation/OOo3_User_Guides/Getting Started/Choosing options for loading and saving documents
|NextPage=Documentation/OOo3_User_Guides/Getting Started/Internet options}}
You may need to do several things to set the language settings to what you want:

* Install the required dictionaries
* Change some locale and language settings
* Choose spelling options

== Install the required dictionaries ==
OOo 3.0 automatically installs several dictionaries with the program. To add other dictionaries, use '''Tools > Language > More Dictionaries Online'''. OOo will open your default web browser to a page containing links to additional dictionaries that you can install. Follow the prompts to install them.

== Change locale and language settings ==
You can change some details of the locale and language settings that OOo uses for all documents, or for specific documents.

In the Options dialog, click '''Language Settings > Languages'''.

[[Image:Options-LangSet.png|thumb|none|500px|''Language Setting Options.'']]

On the right-hand side of the ''Language Settings – Languages'' page, change the ''User interface, Locale setting'', ''Default currency'', and ''Default languages for documents'' as required. In the example, English (UK) has been chosen for all the appropriate settings.

If you want the language (dictionary) setting to apply to the current document only, instead of being the default for all new documents, select the option labelled ''For the current document only''.

[[Image:Options-languages.png|thumb|none|500px|''Choosing language options.'']]

If necessary, select the options to enable support for Asian languages (Chinese, Japanese, Korean) and support for CTL (complex text layout) languages such as Hindi, Thai, Hebrew, and Arabic. If you choose either of these options, the next time you open this dialog, you will see some extra choices under Language Settings, as shown below. These choices (''Searching in Japanese'', ''Asian Layout'', and ''Complex Text Layout'') are not discussed here.

[[Image:Options-languages2.png|thumb|none|500px|''Extra pages when enhanced language support options are selected.'']]

== Choose spelling options ==
To choose the options for checking spelling, click '''Language Settings > Writing Aids'''. In the ''Options'' section of the page, choose the settings that are useful for you. Some considerations:

* If you do not want spelling checked while you type, deselect ''Check spelling as you type ''and select ''Do not mark errors''. (To find the second item, scroll down in the Options list.)
* If you use a custom dictionary that includes words in all upper case and words with numbers (for example, AS/400), select ''Check uppercase words'' and ''Check words with numbers''.
* ''Check special regions'' includes headers, footers, frames, and tables when checking spelling.

Here you can also check which user-defined (custom) dictionaries are active by default, and add or remove dictionaries, by clicking the '''New''' or '''Delete''' buttons.

[[Image:Options-spelling.png|thumb|none|500px|''Choosing languages, dictionaries, and options for checking spelling.'']]

{{CCBY}}
[[Category:Getting Started (Documentation)]]

Template:Documentation/MasterTOC

2009-02-14T14:51:25Z

OOoLerner:

<div id="tocwrapper" class="docooo_tocwrapper" style="float:right; width: 200px; padding: 0px; border: 3px solid #fff; border-left: 20px solid #fff; border-bottom: 20px solid #fff; margin-left: 40px; margin-bottom: 20px; margin-top: -5px;">

<div id="{{{bookid}}}" style="border:1px solid #9BC0F5; padding: 0px; font-size: xx-small; background-color: #FFF;">
<div id="doc_toctitle" class="docooo_toctitle docsection">{{{booktitle}}}</div>
<div id="parttitle" class="docooo_parttitle" style="padding: 1px;font-weight: bold; text-align: left; border-bottom: 1px solid #9099a8; display:{{{ShowParttitle|none}}}">
: {{{parttitle}}}
<div id="tocfooter" class="docooo_tocfooter" style="padding: 1px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPart|none}}}">[[{{{PrevPart}}}|< Previous Section]]</span>
|style="text-align:right;"|<span style="display: {{{ShowNextPart|none}}}">[[{{{NextPart}}}|Next Section >]]</span>
|}
</div>
</div>
<div id="tocbody" class="docooo_tocbody" style="padding: 6px;">
{{{toccontent}}}
</div>
<div id="PrevNextPage" class="docooo_prevnextpage" style="font-size: xx-small!important; margin-bottom: 3px; margin-top: 3px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPage|none}}}">[[{{{PrevPage}}}|< Previous Page]]</span>
|style="text-align:right;"|<span style="display: {{{ShowNextPage|none}}}">[[{{{NextPage}}}|Next Page >]]</span>
|}
</div>
</div>
</div>

<noinclude>

==Usage of Parameters==
;ShowPrevPage:set to "block" to show the "previous page" link, set to "none" to hide it. This parameter is not set in the TOC based on this template, but rather in the file containing that TOC. So the parameter value is "passed through" the TOC to this template and therefore '''must explicitly''' be set to none to hide the link. The TOC must use <nowiki>{{{ShowPrevPage}}}</nowiki> as the parameter value to ensure passing along.
;PrevPage:the path to the previous page (no surrounding "[")
;ShowNextPage:set to "block" to show the "next page" link, set to "none" to hide it. This parameter is not set in the TOC based on this template, but rather in the file containing that TOC. So the parameter value is "passed through" the TOC to this template and therefore '''must explicitly''' be set to none to hide the link. The TOC must use <nowiki>{{{ShowNextPage}}}</nowiki> as the parameter value to ensure passing along.
;NextPage:the path to the previous page (no surrounding "[")
;bookid:The id for the book (not yet evaluated)
;booktitle:The book title that appears at the top of the TOC in full wiki syntax (i.e. as a link: <nowiki>[[MyGuide|My Great Manual]]</nowiki>
;ShowParttitle:set to "block" to show the part title. This will be used in Sub-TOCs. It will default to hidden when not specified.
;parttitle:The title of the part that this Sub-TOC covers in full wiki syntax (i.e. as a link: <nowiki>[[MyGuide/MyPart|Part 1: My Great Part]]</nowiki>
;toccontent:The content of the TOC as lists and divs.
;ShowPrevPart:set to "block" in to show the "previous part" link at the bottom of the TOC. If this parameter is set at the TOC level (and not on the file level like the prev/next page parameter), it will default to hidden when not specified.
;PrevPart:the path to the first page of the previous part (no surrounding "[")
;ShowNextPart:set to "block" in to show the "previous part" link at the bottom of the TOC. If this parameter is set at the TOC level (and not on the file level like the prev/next page parameter), it will default to hidden when not specified.
;NextPart:the path to the first page of the next part (no surrounding "[")

{{Documentation/Note|The style classes are not yet created in the css file}}

=== Simulated example ===

* '''ShowPrevPage''' set to '''none'''
* '''ShowNextPage''' set to '''block'''
* '''NextPage''' set to '''The Next Page'''
* '''bookid''' set to '''1234'''
* '''booktitle''' set to '''<nowiki>[[My Manual]]</nowiki>'''
* '''ShowParttitle''' set to '''block'''
* '''parttitle''' set to '''<nowiki>[[The First Part]]</nowiki>'''
* '''ShowPrevPart''' set to '''none'''
* '''ShowNextPart''' set to '''block'''
* '''NextPart''' set to '''The Second Part'''
* '''toccontent''' set to '''* Chapter<br /> * Chapter<br /> * Chapter'''

<div style="border: 1px dotted #000; padding: 20px; width: 400px; margin: 20px;">

<div id="tocwrapper" class="docooo_tocwrapper" style="width: 200px; padding: 0px; border: 5px solid #fff;">
<div id="icon" style="float:right; margin-right: -10px; margin-top: -10px;">[[Image:Book.png]]</div>
<div id="1234" style="border:1px solid #9099a8; padding: 0px; font-size: xx-small; background-color: #FFF;">
<div id="toctitle" class="docooo_toctitle" style="background-color: #c5d0e1; border: 0px solid #9099a8; padding: 1px;font-weight: bold; text-align: left; font-size:120%;">[[My Manual]]</div>
<div id="parttitle" class="docooo_parttitle" style="padding: 1px;font-weight: bold; text-align: left; border-bottom: 1px solid #9099a8; display:block">
: [[The First Part]]
</div>
<div id="tocfooter" class="docooo_tocfooter" style="padding: 1px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPart|none}}}">[[{{{PrevPart}}}|< Previous Part]]</span>
|style="text-align:right;"|<span style="display: block">[[The Second Part|Next Part >]]</span>
|}
</div>
<div id="tocbody" class="docooo_tocbody" style="padding: 6px;">
* Chapter
* Chapter
* Chapter
</div>
<div id="PrevNextPage" class="docooo_prevnextpage" style="font-size: small; margin-bottom: 10px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: none">[[{{{PrevPage}}}|< Previous Page]]</span>
|style="text-align:right;"|<span style="display: block">[[The Next Page|Next Page >]]</span>
|}
</div>
</div>
</div>

</div>

===Calculated example===
(note: not usable in preview mode while editing this template):

<pre>{{Documentation/MasterTOC
|ShowPrevPage=none
|ShowNextPage=block
|NextPage=The Next Page
|bookid=1234'''
|booktitle=[[My Manual]]
|ShowParttitle=block
|parttitle=[[The First Part]]
|ShowPrevPart=none
|ShowNextPart=block
|NextPart=The Second Part
|toccontent=* Chapter
* Chapter
* Chapter
}}
</pre>

will be:

<div style="border: 1px dotted #000; padding: 20px; width: 400px; height: 200px; margin: 20px;">

{{Documentation/MasterTOC
|ShowPrevPage=none
|ShowNextPage=block
|NextPage=The Next Page
|bookid=1234'''
|booktitle=[[My Manual]]
|ShowParttitle=block
|parttitle=[[The First Part]]
|ShowPrevPart=none
|ShowNextPart=block
|NextPart=The Second Part
|toccontent=* Chapter
* Chapter
* Chapter
}}
</div>
</noinclude>

Template:Documentation/MasterTOC

2009-02-14T14:47:58Z

OOoLerner:

<div id="tocwrapper" class="docooo_tocwrapper" style="float:right; width: 200px; padding: 0px; border: 3px solid #fff; border-left: 20px solid #fff; border-bottom: 20px solid #fff; margin-left: 40px; margin-bottom: 20px; margin-top: -5px;">

<div id="{{{bookid}}}" style="border:1px solid #9BC0F5; padding: 0px; font-size: xx-small; background-color: #FFF;">
<div id="doc_toctitle" class="docooo_toctitle docsection">{{{booktitle}}}</div>
<div id="parttitle" class="docooo_parttitle" style="padding: 1px;font-weight: bold; text-align: left; border-bottom: 1px solid #9099a8; display:{{{ShowParttitle|none}}}">
: {{{parttitle}}}
<div id="tocfooter" class="docooo_tocfooter" style="padding: 1px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPart|none}}}">[[{{{PrevPart}}}|< Previous Section]]</span>
|style="text-align:right;"|<span style="display: {{{ShowNextPart|none}}}">[[{{{NextPart}}}|Next Section >]]</span>
|}
</div>
</div>
<div id="tocbody" class="docooo_tocbody" style="padding: 6px;">
{{{toccontent}}}
</div>
<div id="PrevNextPage" class="docooo_prevnextpage" style="font-size: xx-small!important; margin-bottom: 3px; margin-top: 3px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPage|none}}}">[[{{{PrevPage}}}|< Previous Page]]</span>
|style="text-align:right;"|<span style="display: {{{ShowNextPage|none}}}">[[{{{NextPage}}}|Next Page >]]</span>
|}
</div>
</div>
</div>

<noinclude>

==Usage of Parameters==
;ShowPrevPage:set to "block" to show the "previous page" link, set to "none" to hide it. This parameter is not set in the TOC based on this template, but rather in the file containing that TOC. So the parameter value is "passed through" the TOC to this template and therefore '''must explicitly''' be set to none to hide the link. The TOC must use <nowiki>{{{ShowPrevPage}}}</nowiki> as the parameter value to ensure passing along.
;PrevPage:the path to the previous page (no surrounding "[")
;ShowNextPage:set to "block" to show the "next page" link, set to "none" to hide it. This parameter is not set in the TOC based on this template, but rather in the file containing that TOC. So the parameter value is "passed through" the TOC to this template and therefore '''must explicitly''' be set to none to hide the link. The TOC must use <nowiki>{{{ShowNextPage}}}</nowiki> as the parameter value to ensure passing along.
;NextPage:the path to the previous page (no surrounding "[")
;bookid:The id for the book (not yet evaluated)
;booktitle:The book title that appears at the top of the TOC in full wiki syntax (i.e. as a link: <nowiki>[[MyGuide|My Great Manual]]</nowiki>
;ShowParttitle:set to "block" to show the part title. This will be used in Sub-TOCs. It will default to hidden when not specified.
;parttitle:The title of the part that this Sub-TOC covers in full wiki syntax (i.e. as a link: <nowiki>[[MyGuide/MyPart|Part 1: My Great Part]]</nowiki>
;toccontent:The content of the TOC as lists and divs.
;ShowPrevPart:set to "block" in to show the "previous part" link at the bottom of the TOC. If this parameter is set at the TOC level (and not on the file level like the prev/next page parameter), it will default to hidden when not specified.
;PrevPart:the path to the first page of the previous part (no surrounding "[")
;ShowNextPart:set to "block" in to show the "previous part" link at the bottom of the TOC. If this parameter is set at the TOC level (and not on the file level like the prev/next page parameter), it will default to hidden when not specified.
;NextPart:the path to the first page of the next part (no surrounding "[")

{{Documentation/Note|The style classes are not yet created in the css file}}

----
'''Bold text'''[[[[Link title]][[[Image:http://www.example.com link title]][[Media:<math>Example.ogg</math>--[[User:PYRATE XCHANGE|PYRATE XCHANGE]] 11:15, 7 June 2008 (CEST)--[[User:PYRATE XCHANGE|PYRATE XCHANGE]] 11:15, 7 June 2008 (CEST)]]]]]

=== Simulated example ===

* '''ShowPrevPage''' set to '''none'''
* '''ShowNextPage''' set to '''block'''
* '''NextPage''' set to '''The Next Page'''
* '''bookid''' set to '''1234'''
* '''booktitle''' set to '''<nowiki>[[My Manual]]</nowiki>'''
* '''ShowParttitle''' set to '''block'''
* '''parttitle''' set to '''<nowiki>[[The First Part]]</nowiki>'''
* '''ShowPrevPart''' set to '''none'''
* '''ShowNextPart''' set to '''block'''
* '''NextPart''' set to '''The Second Part'''
* '''toccontent''' set to '''* Chapter<br /> * Chapter<br /> * Chapter'''

<div style="border: 1px dotted #000; padding: 20px; width: 400px; margin: 20px;">

<div id="tocwrapper" class="docooo_tocwrapper" style="width: 200px; padding: 0px; border: 5px solid #fff;">
<div id="icon" style="float:right; margin-right: -10px; margin-top: -10px;">[[Image:Book.png]]</div>
<div id="1234" style="border:1px solid #9099a8; padding: 0px; font-size: xx-small; background-color: #FFF;">
<div id="toctitle" class="docooo_toctitle" style="background-color: #c5d0e1; border: 0px solid #9099a8; padding: 1px;font-weight: bold; text-align: left; font-size:120%;">[[My Manual]]</div>
<div id="parttitle" class="docooo_parttitle" style="padding: 1px;font-weight: bold; text-align: left; border-bottom: 1px solid #9099a8; display:block">
: [[The First Part]]
</div>
<div id="tocfooter" class="docooo_tocfooter" style="padding: 1px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: {{{ShowPrevPart|none}}}">[[{{{PrevPart}}}|< Previous Part]]</span>
|style="text-align:right;"|<span style="display: block">[[The Second Part|Next Part >]]</span>
|}
</div>
<div id="tocbody" class="docooo_tocbody" style="padding: 6px;">
* Chapter
* Chapter
* Chapter
</div>
<div id="PrevNextPage" class="docooo_prevnextpage" style="font-size: small; margin-bottom: 10px;">
{|border=0 width=100%
|-
|style="text-align:left;"|<span style="display: none">[[{{{PrevPage}}}|< Previous Page]]</span>
|style="text-align:right;"|<span style="display: block">[[The Next Page|Next Page >]]</span>
|}
</div>
</div>
</div>

</div>

===Calculated example===
(note: not usable in preview mode while editing this template):

<pre>{{Documentation/MasterTOC
|ShowPrevPage=none
|ShowNextPage=block
|NextPage=The Next Page
|bookid=1234'''
|booktitle=[[My Manual]]
|ShowParttitle=block
|parttitle=[[The First Part]]
|ShowPrevPart=none
|ShowNextPart=block
|NextPart=The Second Part
|toccontent=* Chapter
* Chapter
* Chapter
}}
</pre>

will be:

<div style="border: 1px dotted #000; padding: 20px; width: 400px; height: 200px; margin: 20px;">

{{Documentation/MasterTOC
|ShowPrevPage=none
|ShowNextPage=block
|NextPage=The Next Page
|bookid=1234'''
|booktitle=[[My Manual]]
|ShowParttitle=block
|parttitle=[[The First Part]]
|ShowPrevPart=none
|ShowNextPart=block
|NextPart=The Second Part
|toccontent=* Chapter
* Chapter
* Chapter
}}
</div>
</noinclude>

Documentation/DevGuide/JavaBean/API Overview

2009-02-14T13:26:09Z

OOoLerner:

{{Documentation/DevGuide/JavaBeanTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/JavaBean/The OOoBean by Example
|NextPage=Documentation/DevGuide/JavaBean/Configuring the Office Bean
}}
{{DISPLAYTITLE:API Overview}}
The <tt>OOoBean</tt> offers methods that can be applied to all {{PRODUCTNAME}} document types.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Methods of <code>com.sun.star.comp.beans.OOoBean</code>
|-
|<code>OOoBean()</code>
|<code>constructor</code> - creates an OOoBean with an implicit connection
|-
|<code>OOoBean(OfficeConnection)</code>
|<code>constructor</code> - creates an OOoBean with an explicit connection
|-
|<code>setOOoStartTimeOut(...)</code>
|<code>void</code> - sets the timeout for methods which start {{PRODUCTNAME}}
|-
|<code>setOOoCallTimeOut(...)</code>
|<code>void</code> - sets the timeout for other methods
|-
|<code>SetOOoCheckCycle(...)</code>
|<code>void</code> - sets repeat period for cyclic {{PRODUCTNAME}} alive check
|-
|<code>setOOoConnection(...)</code>
|<code>void</code> - sets an explicit connection to a {{PRODUCTNAME}} instance
|-
|<code>startOOoConnection(...)</code>
|<code>void</code> - starts a connection with an explicit connection URL
|-
|<code>isOOoConnected()</code>
|<code>boolean</code> - returns whether the OOoBean is connected to a {{PRODUCTNAME}}
|-
|<code>stopOOoConnection()</code>
|<code>void</code> - stops the current connection to {{PRODUCTNAME}}
|-
|<code>getOOoConnection()</code>
|<code>OfficeConnection</code> - returns the current connection to {{PRODUCTNAME}}
|-
|<code>getMultiServiceFactory()</code>
|<idls>com.sun.star.lang.XMultiServiceFactory</idls> -- returns the service factory of the connected {{PRODUCTNAME}}
|-
|<code>getOOoDesktop()</code>
|<idls>com.sun.star.frame.XDesktop</idls> - returns the desktop object of the connected {{PRODUCTNAME}}
|-
|<code>clearDocument()</code>
|<code>void</code> -- resets the Bean to an empty document
|-
|<code>clear()</code>
|<code>void</code> - removes the document from the Bean
|-
|<code>aquireSystemWindow()</code>
|<code>void</code> - has to be called when the Bean has a parent component which has a valid system window
|-
|<code>releaseSystemWindow()</code>
|<code>void</code> -- has to be called before the parent component loses its system window, e.g. before it is removed from its parent omponent
|-
|<code>loadFromURL()</code>
|<code>void</code> -- loads a document into the Bean
|-
|<code>loadFromStream()</code>
|<code>void</code> -- loads a document from a Java stream int o the Bean
|-
|<code>loadFromByteArray()</code>
|<code>void</code> -- loads a document from a byte array into the Bean
|-
|<code>storeToURL()</code>
|<code>void</code> - stores the document in the Bean to an URL
|-
|<code>storeToStream()</code>
|<code>void</code> - stores the document in the Bean to a stream
|-
|<code>storeToByteArray()</code>
|<code>void</code> - stores the document in the Bean to a byte array
|-
|<code>getFrame()</code>
|<code>Frame</code> -- returns a wrapper for <idls>com.sun.star.frame.Frame</idls>
|-
|<code>getController()</code>
|<code>Controller</code> -- returns a wrapper for <idls>com.sun.star.frame.Controller</idls>
|-
|<code>getDocument()</code>
|<code>Document</code> -- returns a wrapper for <idls>com.sun.star.model.OfficeDocument</idls>
|-
|<code>setAllBarsVisible()</code>
|<code>void</code> - sets visibility of all tool bars, known by this Bean
|-
|<code>set...BarVisible()</code>
|<code>void</code> - sets visibility of a specific tool bar
|-
|<code>is...BarVisible()</code>
|<code>boolean</code> - returns visibility of a specific tool bar
|}

{{PDL1}}

[[Category:Documentation/Developer's Guide/JavaBean for Office Components]]

Documentation/DevGuide/FirstSteps/First Contact

2009-02-13T22:50:25Z

OOoLerner:

{{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 and build 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 a Java IDE or source editor, and enter the source code for the [[#FirstUnoContactClass|<tt>FirstUnoContact</tt>]] class. In order to automate the build process one may use an [[#AntBuildScript|Ant build script]] as shown below.

==== Using the NetBeans IDE ====

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 [[#FirstUnoContractClass|shown below]] 
# Build the project by pressing '''F11''' and run it by pressing '''F6'''

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

==== Using the Eclipse IDE ====

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

# From the '''File''' menu, select '''New > Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab, where you may add the necessary libraries as described in section [[Documentation/DevGuide/FirstSteps/Configuration#Prepare the Eclipse IDE|Prepare the Eclipse IDE]]. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New > Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as [[#FirstUnoContractClass|shown below]].
# Right click on the project node '''FirstUnoContact''', select '''New > File''' to create the '''build.xml''' file.
# Enter the code for the Ant build script as [[#AntBuildScript|shown below]].
# From the '''Run''' menu, select '''External Tools > Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Press '''Apply''' and '''Close'''. This option is necessary for the Ant property '''eclipse.running''' to be set when the Ant build script is run.
# Build an run the project by using the build script.

==== An Ant build script<span id="AntBuildScript"></span> ====

An example Ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/FirstUnoContact.jar" />
</target>

</project>
</source>

This build script has been tested stand-alone and with the Eclipse IDE. For use with other IDEs it may have to be adapted. The comments and all targets that have an <tt>unless</tt> attribute with the value <tt>eclipse.running</tt> should give an idea about what might be necessary.

The script works with a standard installation on unix, which is rooted at <tt>/opt</tt>. For other installations the property <tt>OFFICE_ROOT</tt> has to be set accordingly.

=== The FirstUnoContact class<span id="FirstUnoContactClass"></span> ===

The FirstUnoContact example that connects to the office with java: 

<source lang="java">
package de.ooo.devguide.example1;

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>

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:

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

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

''<idl>com.sun.star.sdb.DatabaseContext</idl>''
: holds databases registered with {{PRODUCTNAME}}

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

''<idl>com.sun.star.text.GlobalSettings</idl>''
: 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 <tt>FirstUnoContact</tt> 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 [http://api.openoffice.org/docs/java/ref/com/sun/star/comp/helper/Bootstrap.html <tt>com.sun.star.comp.helper.Bootstrap.bootstrap()</tt>] 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/FirstSteps/Configuration

2009-02-13T21:41:07Z

OOoLerner:

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Installation Sets
|NextPage=Documentation/DevGuide/FirstSteps/First Contact
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Configuration]]
{{DISPLAYTITLE:Configuration}}
===Enable Java in {{PRODUCTNAME}}===

{{PRODUCTNAME}} uses a Java Virtual Machine to instantiate components written in Java. From {{PRODUCTNAME}} {{OOo2.x}} on, Java is found automatically during startup, or latest when Java functionality is required. If you prefer to preselect a JRE or JDK, or if no Java is found, you can configure Java using the '''Tools – Options''' dialog in {{PRODUCTNAME}} and select the section '''{{PRODUCTNAME}} – Java''' section. In older versions of {{PRODUCTNAME}} you can also easily tell the office which JVM to use: launch the jvmsetup executable from the programs folder under the {{PRODUCTNAME}}, select an installed JRE or JDK and click '''OK'''. Close the {{PRODUCTNAME}} including the Quickstarter in the taskbar and restart {{PRODUCTNAME}}. Furthermore, open the '''Tools - Options''' dialog in {{PRODUCTNAME}}, select the section '''{{PRODUCTNAME}} - Security''' and make sure that the Java enable option is checked.

===Using the Java UNO runtime and API in your IDE===

Next, the {{PRODUCTNAME}} API and Java UNO runtime class files must be made known to the Java IDE.

==== Prepare the NetBeans IDE ====

For NetBeans the necessary jar files are made available by simply installing the [[OpenOffice_NetBeans_Integration| OpenOffice.org API Plugin for NetBeans]]. After the configuration the plugin installs a new library in NetBeans that can be used in projects directly. The library will be automatically added to new projects created with the project wizards coming with the plugin. The following steps show how to install the plugin in NetBeans 5.5 or higher and how to create a new UNO client application project.

# Install and start NetBeans.
# From the '''Tools''' menu, select '''Update center'''. check mark at least the '''NetBeans Update Center''' and press '''Next'''. Under '''Features''' search for the entry '''OpenOffice.org API Plugin''', select the entry, '''Add''' it, press '''Next''', accept the license and follow the next steps to install it completely.
# A plugin specific configuration dialog comes up and required the input of a PATH to a valid office and SDK installation . After completion of this dialog the plugin is installed and configured correctly.
# From the '''File''' menu, select '''New Project'''. Select '''OpenOffice.org''' category and select the '''OpenOffice.org Client Application'''. Follow the next step and finish the project wizard.
# A new project with your specified name is created. The main function of a generated JAVA skeleton contains already the UNO bootstrap function that gives you access to an office context object as main entry point to get started with the {{PRODUCTNAME}} API. The context object is from a remote office instance that is connected over a named pipe connection and the default office is started automatically if no instance is running.

==== Prepare the Eclipse IDE ====

For Eclipse the necessary jar files may be made available by defining a '''User Library'''.

# Install and start Eclipse.
# From the '''Window''' menu, select '''Preferences'''. On the dialog window, select '''Java > Build Path > User Libraries'''. Press '''New''' to create a new User Library. The library's name might be '''OpenOffice.org Libraries [SDK 3.0.1]'''. Press '''OK'''.
# Select the library and press '''Add JARs'''. On the JAR-Selection dialog you should add the necessary libraries. For a standard installation of {{PRODUCTNAME}} 3.0.1 on unix, these are
## /opt/openoffice.org/ure/share/java/juh.jar
## /opt/openoffice.org/ure/share/java/jurt.jar
## /opt/openoffice.org/ure/share/java/ridl.jar
## /opt/openoffice.org/basis3.0/program/classes/unoil.jar
#Press '''OK''' to save the User Library.
# From the '''File''' menu, select '''New > Java Project'''. On the wizard's page for '''Java Settings''' select the '''Libraries''' tab. Press '''Add Library''', select '''User Library''' and press '''Next'''. Select the User Library you defined before and press '''Finish'''. Continue the dialog of the '''New Project''' wizard.

A standard installation of {{PRODUCTNAME}} on unix is rooted as <code>/opt</code>. For other installations the libraries should be found at corresponding locations.

===Add the API Reference to your IDE===

We recommend to add the API and the Java UNO reference to your Java IDE to get online help for the {{PRODUCTNAME}} API and the Java UNO runtime. The generated reference documentation provides Javadoc conform index files that can be integrated in most Java IDEs. In NetBeans the IDL reference is automatically integrated with the installation of the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin].

Using the reference in NetBeans is quite simple, type an IDL type in the editor and press '''ALT ＋ F1'''. A further useful feature is the code completion feature that you get also automatically when you install the plugin.

{{PDL1}}

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

Documentation/DevGuide/FirstSteps/First Contact

2009-02-13T21:28:44Z

OOoLerner:

{{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 and build 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 a Java IDE or source editor, and enter the source code for the [[#FirstUnoContactClass|<code>FirstUnoContact</code>]] class. In order to automate the build process one may use an [[#AntBuildScript|Ant build script]] as shown below.

==== Using the NetBeans IDE ====

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 [[#FirstUnoContractClass|shown below]] 
# Build the project by pressing '''F11''' and run it by pressing '''F6'''

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

==== Using the Eclipse IDE ====

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

# From the '''File''' menu, select '''New > Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab, where you may add the necessary libraries as described in section [[Documentation/DevGuide/FirstSteps/Configuration#Prepare the Eclipse IDE|Prepare the Eclipse IDE]]. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New > Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as [[#FirstUnoContractClass|shown below]].
# Right click on the project node '''FirstUnoContact''', select '''New > File''' to create the '''build.xml''' file.
# Enter the code for the Ant build script as [[#AntBuildScript|shown below]].
# From the '''Run''' menu, select '''External Tools > Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Press '''Apply''' and '''Close'''. This option is necessary for the Ant property '''eclipse.running''' to be set when the Ant build script is run.
# Build an run the project by using the build script.

==== An Ant build script<span id="AntBuildScript"></span> ====

An example Ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/FirstUnoContact.jar" />
</target>

</project>
</source>

This build script has been tested stand-alone and with the Eclipse IDE. It should also work with the NetBeans IDEs as it is. For use with other IDEs it may have to be adapted. The comments and all targets that have an <code>unless</code> attribute with the value <code>eclipse.running</code> should give an idea about what might be necessary.

The script works with a standard installation on unix, which is rooted at <code>/opt</code>. For other installations the property <code>OFFICE_ROOT</code> has to be set accordingly.

=== The FirstUnoContact class<span id="FirstUnoContactClass"></span> ===

The FirstUnoContact example that connects to the office with java: 

<source lang="java">
package de.ooo.devguide.example1;

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>

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:

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

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

''<idl>com.sun.star.sdb.DatabaseContext</idl>''
: holds databases registered with {{PRODUCTNAME}}

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

''<idl>com.sun.star.text.GlobalSettings</idl>''
: 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 [http://api.openoffice.org/docs/java/ref/com/sun/star/comp/helper/Bootstrap.html <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/FirstSteps/First Contact

2009-02-12T23:10:21Z

OOoLerner: /* Service Managers */

{{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 Eclipse IDE, use the following steps:

# From the '''File''' menu, select '''New > Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab, where you may add the necessary libraries as described in section [[Documentation/DevGuide/FirstSteps/Configuration#Set up the Eclipse IDE|Set up the Eclipse IDE]]. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New > Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as shown below. 
# Right click on the project node '''FirstUnoContact''', select '''New > File''' to create the '''build.xml''' file.
# Enter the code for the ant build script as shown below. 
# From the '''Run''' menu, select '''External Tools > Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Press '''Apply''' and '''Close'''. This option is necessary for the ant property '''eclipse.running''' to be set when the ant build script is run.
# Build an run the project by running the build script. 

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">
package de.ooo.devguide.example1;

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 easily possible to integrate the necessary steps in other IDEs as well or run an ant script directly.

An example ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/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:

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

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

''<idl>com.sun.star.sdb.DatabaseContext</idl>''
: holds databases registered with {{PRODUCTNAME}}

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

''<idl>com.sun.star.text.GlobalSettings</idl>''
: 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 [http://api.openoffice.org/docs/java/ref/com/sun/star/comp/helper/Bootstrap.html <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/FirstSteps/First Contact

2009-02-12T22:08:39Z

OOoLerner:

{{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 Eclipse IDE, use the following steps:

# From the '''File''' menu, select '''New > Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab, where you may add the necessary libraries as described in section [[Documentation/DevGuide/FirstSteps/Configuration#Set up the Eclipse IDE|Set up the Eclipse IDE]]. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New > Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as shown below. 
# Right click on the project node '''FirstUnoContact''', select '''New > File''' to create the '''build.xml''' file.
# Enter the code for the ant build script as shown below. 
# From the '''Run''' menu, select '''External Tools > Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Press '''Apply''' and '''Close'''. This option is necessary for the ant property '''eclipse.running''' to be set when the ant build script is run.
# Build an run the project by running the build script. 

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">
package de.ooo.devguide.example1;

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 easily possible to integrate the necessary steps in other IDEs as well or run an ant script directly.

An example ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/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/FirstSteps/First Contact

2009-02-12T21:51:03Z

OOoLerner: /* Getting Started */

{{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 Eclipse IDE, use the following steps:

# From the '''File''' menu, select '''New''', then select '''Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab. On this tab add the following external JARs: '''/opt/openoffice.org/ure/share/java/juh.jar''', '''/opt/openoffice.org/ure/share/java/jurt.jar''', '''/opt/openoffice.org/ure/share/java/ridl.jar''' and '''/opt/openoffice.org/base3.0/program/classes/unoil.jar'''. [[/Documentation/DevGuide/FirstSteps/Configuration#Set up the Eclipse IDE|AAA]] Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New''', then select '''File''' to create the file '''build.xml'''.
# Enter the ant build script shown below. 
# From the '''Run''' menu, select '''External Tools''', then select '''Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Click '''Apply''' and '''Close'''. This option is necessary for the ant property '''eclipse.running''' to be set when the ant build script is run.
# Right click on the project node '''FirstUnoContact''', select '''New''', then select '''Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as shown below .
# Build an run the project by running the build script shown below .

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">
package de.ooo.devguide.example1;

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 easily possible to integrate the necessary steps in other IDEs as well or run an ant script directly.

An example ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/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/FirstSteps/Configuration

2009-02-12T20:42:29Z

OOoLerner: /* Set up the Eclipse IDE */

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Installation Sets
|NextPage=Documentation/DevGuide/FirstSteps/First Contact
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Configuration]]
{{DISPLAYTITLE:Configuration}}
===Enable Java in {{PRODUCTNAME}}===

{{PRODUCTNAME}} uses a Java Virtual Machine to instantiate components written in Java. From {{PRODUCTNAME}} {{OOo2.x}} on, Java is found automatically during startup, or latest when Java functionality is required. If you prefer to preselect a JRE or JDK, or if no Java is found, you can configure Java using the '''Tools – Options''' dialog in {{PRODUCTNAME}} and select the section '''{{PRODUCTNAME}} – Java''' section. In older versions of {{PRODUCTNAME}} you can also easily tell the office which JVM to use: launch the jvmsetup executable from the programs folder under the {{PRODUCTNAME}}, select an installed JRE or JDK and click '''OK'''. Close the {{PRODUCTNAME}} including the Quickstarter in the taskbar and restart {{PRODUCTNAME}}. Furthermore, open the '''Tools - Options''' dialog in {{PRODUCTNAME}}, select the section '''{{PRODUCTNAME}} - Security''' and make sure that the Java enable option is checked.

===Using the Java UNO runtime and API in your IDE===

Next, the {{PRODUCTNAME}} API and Java UNO runtime class files must be made known to the Java IDE.

==== Set up the NetBeans IDE ====

For NetBeans the necessary jar files are made available by simply installing the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin for NetBeans]. After the configuration the plugin installs a new library in NetBeans that can be used in projects directly. The library will be automatically added to new projects created with the project wizards coming with the plugin. The following steps show how to install the plugin in NetBeans 5.5 or higher and how to create a new UNO client application project.

# Install and start NetBeans.
# From the '''Tools''' menu, select '''Update center'''. check mark at least the '''NetBeans Update Center''' and press '''Next'''. Under '''Features''' search for the entry '''OpenOffice.org API Plugin''', select the entry, '''Add''' it, press '''Next''', accept the license and follow the next steps to install it completely.
# A plugin specific configuration dialog comes up and required the input of a PATH to a valid office and SDK installation . After completion of this dialog the plugin is installed and configured correctly.
# From the '''File''' menu, select '''New Project'''. Select '''OpenOffice.org''' category and select the '''OpenOffice.org Client Application'''. Follow the next step and finish the project wizard.
# A new project with your specified name is created. The main function of a generated JAVA skeleton contains already the UNO bootstrap function that gives you access to an office context object as main entry point to get started with the {{PRODUCTNAME}} API. The context object is from a remote office instance that is connected over a named pipe connection and the default office is started automatically if no instance is running.

==== Set up the Eclipse IDE ====

For Eclipse the necessary jar files may be made available by defining a '''User Library'''.

# Install and start Eclipse.
# From the '''Window''' menu, select '''Preferences'''. On the dialog window, select '''Java > Build Path > User Libraries'''. Press '''New''' to create a new User Library. The library's name might be '''OpenOffice.org Libraries [SDK 3.0.1]'''. Press '''OK'''.
# Select the library and press '''Add JARs'''. On the JAR-Selection dialog you should add the necessary libraries. For a standard installation of OpenOffice.org 3.0.1 on unix, these are
## /opt/openoffice.org/ure/share/java/juh.jar
## /opt/openoffice.org/ure/share/java/jurt.jar
## /opt/openoffice.org/ure/share/java/ridl.jar
## /opt/openoffice.org/basis3.0/program/classes/unoil.jar
#Press '''OK''' to save the User Library.
# From the '''File''' menu, select '''New > Java Project'''. On the wizard's page for '''Java Settings''' select the '''Libraries''' tab. Press '''Add Library''', select '''User Library''' and press '''Next'''. Select the User Library you defined before and press '''Finish'''. Continue the dialog of the '''New Project''' wizard.

===Add the API Reference to your IDE===

We recommend to add the API and the Java UNO reference to your Java IDE to get online help for the {{PRODUCTNAME}} API and the Java UNO runtime. The generated reference documentation provides Javadoc conform index files that can be integrated in most Java IDEs. In NetBeans the IDL reference is automatically integrated with the installation of the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin].

Using the reference in NetBeans is quite simple, type an IDL type in the editor and press '''ALT ＋ F1'''. A further useful feature is the code completion feature that you get also automatically when you install the plugin.

{{PDL1}}

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

Documentation/DevGuide/FirstSteps/Configuration

2009-02-12T20:40:35Z

OOoLerner: /* Set up the Eclipse IDE */

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Installation Sets
|NextPage=Documentation/DevGuide/FirstSteps/First Contact
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Configuration]]
{{DISPLAYTITLE:Configuration}}
===Enable Java in {{PRODUCTNAME}}===

{{PRODUCTNAME}} uses a Java Virtual Machine to instantiate components written in Java. From {{PRODUCTNAME}} {{OOo2.x}} on, Java is found automatically during startup, or latest when Java functionality is required. If you prefer to preselect a JRE or JDK, or if no Java is found, you can configure Java using the '''Tools – Options''' dialog in {{PRODUCTNAME}} and select the section '''{{PRODUCTNAME}} – Java''' section. In older versions of {{PRODUCTNAME}} you can also easily tell the office which JVM to use: launch the jvmsetup executable from the programs folder under the {{PRODUCTNAME}}, select an installed JRE or JDK and click '''OK'''. Close the {{PRODUCTNAME}} including the Quickstarter in the taskbar and restart {{PRODUCTNAME}}. Furthermore, open the '''Tools - Options''' dialog in {{PRODUCTNAME}}, select the section '''{{PRODUCTNAME}} - Security''' and make sure that the Java enable option is checked.

===Using the Java UNO runtime and API in your IDE===

Next, the {{PRODUCTNAME}} API and Java UNO runtime class files must be made known to the Java IDE.

==== Set up the NetBeans IDE ====

For NetBeans the necessary jar files are made available by simply installing the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin for NetBeans]. After the configuration the plugin installs a new library in NetBeans that can be used in projects directly. The library will be automatically added to new projects created with the project wizards coming with the plugin. The following steps show how to install the plugin in NetBeans 5.5 or higher and how to create a new UNO client application project.

# Install and start NetBeans.
# From the '''Tools''' menu, select '''Update center'''. check mark at least the '''NetBeans Update Center''' and press '''Next'''. Under '''Features''' search for the entry '''OpenOffice.org API Plugin''', select the entry, '''Add''' it, press '''Next''', accept the license and follow the next steps to install it completely.
# A plugin specific configuration dialog comes up and required the input of a PATH to a valid office and SDK installation . After completion of this dialog the plugin is installed and configured correctly.
# From the '''File''' menu, select '''New Project'''. Select '''OpenOffice.org''' category and select the '''OpenOffice.org Client Application'''. Follow the next step and finish the project wizard.
# A new project with your specified name is created. The main function of a generated JAVA skeleton contains already the UNO bootstrap function that gives you access to an office context object as main entry point to get started with the {{PRODUCTNAME}} API. The context object is from a remote office instance that is connected over a named pipe connection and the default office is started automatically if no instance is running.

==== Set up the Eclipse IDE ====

For Eclipse the necessary jar files may be made available by defining a '''User Library'''.

# Install and start Eclipse.
# From the '''Window''' menu, select '''Preferences'''. On the dialog window, select '''Java > Build Path > User Libraries'''. Press '''New''' to create a new User Library. The library's name might be '''OpenOffice.org Libraries [SDK 3.0.1]'''. Press '''OK'''.
# Select the library and press '''Add JARs'''. On the JAR-Selection dialog you should add the necessary libraries. For a standard installation of OpenOffice.org 3.0.1 on unix, these are
## /opt/openoffice.org/ure/share/java/juh.jar
## /opt/openoffice.org/ure/share/java/jurt.jar
## /opt/openoffice.org/ure/share/java/ridl.jar
## /opt/openoffice.org/basis3.0/program/classes/unoil.jar
#Press '''OK''' to save the User Library.
# From the '''File''' menu, select '''New > Java Project'''. On the wizard's page for '''Java Settings''' select the '''Libraries''' tab. Press '''Add Library''', select '''User Library''' and press '''Next'''. Select the User Library you defined before and press '''Finish'''. Continue the dialog of the new project wizard.

===Add the API Reference to your IDE===

We recommend to add the API and the Java UNO reference to your Java IDE to get online help for the {{PRODUCTNAME}} API and the Java UNO runtime. The generated reference documentation provides Javadoc conform index files that can be integrated in most Java IDEs. In NetBeans the IDL reference is automatically integrated with the installation of the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin].

Using the reference in NetBeans is quite simple, type an IDL type in the editor and press '''ALT ＋ F1'''. A further useful feature is the code completion feature that you get also automatically when you install the plugin.

{{PDL1}}

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

Documentation/DevGuide/FirstSteps/Configuration

2009-02-12T20:28:29Z

OOoLerner: /* Using the Java UNO runtime and API in your IDE */

{{Documentation/DevGuide/FirstStepsTOC
|FirstSteps2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/FirstSteps/Installation Sets
|NextPage=Documentation/DevGuide/FirstSteps/First Contact
}}
[[zh:Zh/Documentation/DevGuide/FirstSteps/Configuration]]
{{DISPLAYTITLE:Configuration}}
===Enable Java in {{PRODUCTNAME}}===

{{PRODUCTNAME}} uses a Java Virtual Machine to instantiate components written in Java. From {{PRODUCTNAME}} {{OOo2.x}} on, Java is found automatically during startup, or latest when Java functionality is required. If you prefer to preselect a JRE or JDK, or if no Java is found, you can configure Java using the '''Tools – Options''' dialog in {{PRODUCTNAME}} and select the section '''{{PRODUCTNAME}} – Java''' section. In older versions of {{PRODUCTNAME}} you can also easily tell the office which JVM to use: launch the jvmsetup executable from the programs folder under the {{PRODUCTNAME}}, select an installed JRE or JDK and click '''OK'''. Close the {{PRODUCTNAME}} including the Quickstarter in the taskbar and restart {{PRODUCTNAME}}. Furthermore, open the '''Tools - Options''' dialog in {{PRODUCTNAME}}, select the section '''{{PRODUCTNAME}} - Security''' and make sure that the Java enable option is checked.

===Using the Java UNO runtime and API in your IDE===

Next, the {{PRODUCTNAME}} API and Java UNO runtime class files must be made known to the Java IDE.

==== Set up the NetBeans IDE ====

For NetBeans the necessary jar files are made available by simply installing the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin for NetBeans]. After the configuration the plugin installs a new library in NetBeans that can be used in projects directly. The library will be automatically added to new projects created with the project wizards coming with the plugin. The following steps show how to install the plugin in NetBeans 5.5 or higher and how to create a new UNO client application project.

# Install and start NetBeans.
# From the '''Tools''' menu, select '''Update center'''. check mark at least the '''NetBeans Update Center''' and press '''Next'''. Under '''Features''' search for the entry '''OpenOffice.org API Plugin''', select the entry, '''Add''' it, press '''Next''', accept the license and follow the next steps to install it completely.
# A plugin specific configuration dialog comes up and required the input of a PATH to a valid office and SDK installation . After completion of this dialog the plugin is installed and configured correctly.
# From the '''File''' menu, select '''New Project'''. Select '''OpenOffice.org''' category and select the '''OpenOffice.org Client Application'''. Follow the next step and finish the project wizard.
# A new project with your specified name is created. The main function of a generated JAVA skeleton contains already the UNO bootstrap function that gives you access to an office context object as main entry point to get started with the {{PRODUCTNAME}} API. The context object is from a remote office instance that is connected over a named pipe connection and the default office is started automatically if no instance is running.

==== Set up the Eclipse IDE ====

For Eclipse the necessary jar files may be made available by defining a '''User Library'''.

# Install and start Eclipse.
# From the '''Window''' menu, select '''Preferences'''. On the dialog window, select '''Java > Build Path > User Libraries'''. Press '''New''' to create a new User Library. The library's name might be '''OpenOffice.org Libraries [SDK 3.0.1]'''. Press '''OK'''.
# Select the library and press '''Add JARs'''. On the JAR-Selection dialog you should add the necessary libraries. Press '''OK''' to save the User Library.
# From the '''File''' menu select '''New > Java Project'''. On the wizard's page for '''Java Settings''' select the '''Libraries''' tab. Press '''Add Library''', select '''User Library''' and press '''Next'''. Select the User Library you defined before and press '''Finish'''. Continue the dialog of the new project wizard.

===Add the API Reference to your IDE===

We recommend to add the API and the Java UNO reference to your Java IDE to get online help for the {{PRODUCTNAME}} API and the Java UNO runtime. The generated reference documentation provides Javadoc conform index files that can be integrated in most Java IDEs. In NetBeans the IDL reference is automatically integrated with the installation of the [http://wiki.services.openoffice.org/wiki/OpenOffice_NetBeans_Integration OpenOffice.org API Plugin].

Using the reference in NetBeans is quite simple, type an IDL type in the editor and press '''ALT ＋ F1'''. A further useful feature is the code completion feature that you get also automatically when you install the plugin.

{{PDL1}}

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

User:OOoLerner

2009-02-11T23:49:22Z

OOoLerner: New page: This is just a placeholder text. Real content to come.

This is just a placeholder text. Real content to come.

Documentation/DevGuide/FirstSteps/First Contact

2009-02-11T23:44:10Z

OOoLerner: /* Getting Started */

{{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 Eclipse IDE, use the following steps:

# From the '''File''' menu, select '''New''', then select '''Java Project'''. On the first wizard panel insert '''FirstUnoContact''' as project name. Press '''Next'''. On the next wizard panel check that the default output folder is set to '''FirstUnoContact/bin'''. Select the '''Libraries''' tab. On this tab add the following external JARs: '''/opt/openoffice.org/ure/share/java/juh.jar''', '''/opt/openoffice.org/ure/share/java/jurt.jar''', '''/opt/openoffice.org/ure/share/java/ridl.jar''' and '''/opt/openoffice.org/base3.0/program/classes/unoil.jar'''. Press '''Finish''' to create the project.
# Right click on the project node '''FirstUnoContact''', select '''New''', then select '''File''' to create the file '''build.xml'''.
# Enter the ant build script shown below. 
# From the '''Run''' menu, select '''External Tools''', then select '''Open External Tools Dialog'''. On the dialog select '''FirstUnoContract build.xml'''. On the JRE tab, select the option '''Run in the same JRE as the workspace'''. Click '''Apply''' and '''Close'''. This option is necessary for the ant property '''eclipse.running''' to be set when the ant build script is run.
# Right click on the project node '''FirstUnoContact''', select '''New''', then select '''Class''' to generate the '''FirstUnoContact.java''' skeleton.
# Complete the generated source code as shown below .
# Build an run the project by running the build script shown below .

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">
package de.ooo.devguide.example1;

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 easily possible to integrate the necessary steps in other IDEs as well or run an ant script directly.

An example ant build script could be as follows: 

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






<property name="OFFICE_ROOT" value="/opt/openoffice.org" />
<property name="OFFICE_HOME" value="${OFFICE_ROOT}/basis3.0" />
<property name="OO_SDK_HOME" value="${OFFICE_HOME}/sdk" />
<property name="OO_URE_HOME" value="${OFFICE_ROOT}/ure" />

<target name="init">
<property name="OUT_DIR" value="${basedir}/build/example1/" />

<property name="BIN_DIR" value="${basedir}/bin/" />
</target>

<path id="office.class.path">
<filelist dir="${OFFICE_HOME}/program/classes" files="unoil.jar" />
<filelist dir="${OO_URE_HOME}/share/java" files="jurt.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" />
</patternset>
</fileset>


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

<target name="jar" depends="init,compile">
<mkdir dir="${OUT_DIR}" />
<jar basedir="${BIN_DIR}" compress="true" jarfile="${OUT_DIR}/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="de.ooo.devguide.example1.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="all">
<java jar="${OUT_DIR}/FirstUnoContact.jar" failonerror="true" fork="true">
</java>
</target>

<target name="cleanbin" description="Clean all binaries." unless="eclipse.running">
<delete>
<fileset dir="${BIN_DIR}">
<include name="**/*.class" />
</fileset>
</delete>
</target>

<target name="cleanall" description="Clean all build products." depends="init,cleanbin">
<delete file="${OUT_DIR}/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]]