Handling Documents Openoffice 3.1
Handling Documents Openoffice 3.1
Handling Documents Openoffice 3.1
This chapter describes the application environment of the OpenOffice.org application. It assumes that you
have read the chapter First Steps, and that you are able to connect to the office and load documents.
In most cases, users use the functionality of OpenOffice.org by opening and modifying documents. The
interfaces and services common to all document types and how documents are embedded in the
surrounding application environment are discussed.
It is also possible to extend the functionality of OpenOffice.org by replacing the services mentioned here by
intercepting the communication between objects or by creating your own document type and integrating it
into the desktop environment. All these things are discussed in this chapter.
The OpenOffice.org application environment is made up of the desktop environment and the framework API.
and the dispatch framework. The component framework follows a special Frame-Controller-Model paradigm
to manage components viewable in OpenOffice.org. The dispatch framework handles command requests
sent by the GUI.
Desktop Environment
The com.sun.star.frame.Desktop service is the central management instance for the OpenOffice.org
application framework. All OpenOffice.org 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 com.sun.star.frame.XDesktop were kept for compatibility reasons.
The desktop object and frame objects use auxiliary services, such as the
com.sun.star.document.TypeDetection service and other, opaque implementations that interact with the
UNO-based office, but are not accessible through the OpenOffice.org 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.
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
com.sun.star.lang.XComponent interface. Components with controllers are also called office components,
whereas simple window components are called trivial components.
Frames in the OpenOffice.org API are the connecting link between windows, components and the desktop
environment. The relationship between frames and components is discussed in the next section, Framework
API.
Like all other services, the com.sun.star.frame.Desktop service can be exchanged by another
implementation that extends the functionality of OpenOffice.org. By exchanging the desktop service it is
possible to use different kinds of windows or to make OpenOffice.org use MDI instead of SDI. This is not an
easy thing to do, but it is possible without changing any code elsewhere in OpenOffice.org.
Framework API
The framework API does not define an all-in-one framework with strongly coupled interfaces, but defines
specialized frameworks that are grouped together by implementing the relevant interfaces at OpenOffice.org
components. Each framework concentrates on a particular aspect, so that each component decides the
frameworks it wants to participate in.
Currently, there are two of these frameworks: the component framework that implements the framecontroller-model paradigm and the dispatch framework that handles command requests from and to the
application environment. The controller and frame implementations form the bridge between the two
frameworks, because controllers and frames implement interfaces from the component framework and
dispatch framework.
The framework API is an abstract specification. Its current implementation uses the Abstract Window Toolkit
(AWT) specified in com.sun.star.awt, which is an abstract specification as well. The current implementation
3
of the AWT is the Visual Component Library (VCL), a cross-platform toolkit for windows and controls written
in C++ created before the specification of com.sun.star.awt and adapted to support com.sun.star.awt.
module awt
Description
Java AWT-like user interface toolkit interface specifications for UNO.
Nested Modules
tree
Services
AccessibleButton
AccessibleCheckBox
AccessibleComboBox
AccessibleDropDownComboBox
AccessibleDropDownListBox
AccessibleEdit
AccessibleFixedText
AccessibleIconChoiceControl
AccessibleIconChoiceControlEntry
AccessibleList
Accessible lists are used by combo boxes as container for the list items.
AccessibleListBox
AccessibleListBoxList
Accessible list box lists are used by list boxes as container for the list items. In
addtion of the simple container functionality of the AccessibleList service the
::com::sun::star::accessibility::XAccessibleSelection interface is supported.
AccessibleListItem
AccessibleMenu
AccessibleMenuBar
AccessibleMenuItem
AccessibleMenuSeparator
AccessiblePopupMenu
AccessibleRadioButton
AccessibleScrollBar
AccessibleStatusBar
AccessibleStatusBarItem
AccessibleTabBar
AccessibleTabBarPage
AccessibleTabBarPageList
AccessibleTabControl
AccessibleTabPage
AccessibleTextField
Text fields are like edit fields as described by the AccessibleEdit service but
without the ability to edit the text.
AccessibleToolBox
AccessibleToolBoxItem
AccessibleTreeListBox
AccessibleTreeListBoxEntry
AccessibleWindow
AsyncCallback
ContainerWindowProvider
DialogProvider
DialogProvider2
MenuBar
PopupMenu
RoadmapItem
TabController
TabControllerModel
Toolkit
UnoControl
UnoControlButton
UnoControlButtonModel
UnoControlCheckBox
UnoControlCheckBoxModel
UnoControlComboBox
UnoControlComboBoxModel
UnoControlContainer
UnoControlContainerModel
UnoControlCurrencyField
UnoControlCurrencyFieldModel
UnoControlDateField
UnoControlDateFieldModel
UnoControlDialog
UnoControlDialogElement
UnoControlDialogModel
UnoControlEdit
UnoControlEditModel
UnoControlFileControl
UnoControlFileControlModel
UnoControlFixedHyperlink
UnoControlFixedHyperlinkModel
UnoControlFixedLine
UnoControlFixedLineModel
UnoControlFixedText
UnoControlFixedTextModel
UnoControlFormattedField
UnoControlFormattedFieldModel
UnoControlGroupBox
UnoControlGroupBoxModel
UnoControlImageControl
UnoControlImageControlModel
UnoControlListBox
UnoControlListBoxModel
UnoControlModel
UnoControlNumericField
UnoControlNumericFieldModel
UnoControlPatternField
UnoControlPatternFieldModel
UnoControlProgressBar
UnoControlProgressBarModel
UnoControlRadioButton
UnoControlRadioButtonModel
UnoControlRoadmap
UnoControlRoadmapModel
UnoControlScrollBar
UnoControlScrollBarModel
UnoControlSimpleAnimation
UnoControlSpinButtonModel
UnoControlThrobber
UnoControlThrobberModel
UnoControlTimeField
UnoControlTimeFieldModel
Interfaces
XActionListener
XActivateListener
XAdjustmentListener
XBitmap
XButton
makes it possible to set the label of a button and to register for action events.
XCallback
XCheckBox
gives access to the state of a check box and makes it possible to register for
events.
XComboBox
gives access to the items of a combo box and makes it possible to register item
and action event listeners.
XContainerWindowEventHandler
XContainerWindowProvider
XControl
identifies a control.
XControlContainer
XControlModel
XCurrencyField
XDataTransferProviderAccess
This interface extends the XToolkit interface with clipboard and drag-and-drop
support.
9
XDateField
XDevice
provides information about a graphical output device and offers a factory for the
graphics which provides write operations on the device.
XDialog
makes it possible to show and hide a dialog and gives access to the title of the
dialog.
XDialog2
XDialogEventHandler
XDialogProvider
XDialogProvider2
XDisplayBitmap
specifies an object as a bitmap for which data is formatted for a specific output
device.
XDisplayConnection
This interface should be implemented by toolkits that want to give access to their
internal message handling loop.
XDockableWindow
XDockableWindowListener
XEnhancedMouseClickHandler
XEventHandler
This interface can be implemented by clients that need access to the toolkits
window message loop.
XExtendedToolkit
[ DEPRECATED ]
The XExtendedToolkit is an extension of the XToolkit interface. It basically
provides access to three event broadcasters which are used for instance in the
context of accessibility. It is, however, not restricted to accessibility.
XFileDialog
[ DEPRECATED ]
gives access to a file dialog.
XFixedHyperlink
XFixedText
XFocusListener
10
XFont
XFont2
extends the XFont interface and provides additional information for a font.
XGraphics
XImageButton
makes it possible to register for action events of an image button and sets the
action command.
XImageConsumer
XImageProducer
XInfoPrinter
XItemEventBroadcaster
XItemListener
makes it possible to receive events from a component when the state of an item
changes.
XKeyHandler
This key handler is similar to XKeyListener but allows the consumption of key
events. If a key event is consumed by one handler both the following handlers,
with respect to the list of key handlers of the broadcaster, and a following
handling by the broadcaster will not take place.
XKeyListener
XLayoutConstrains
XLayoutContainer
XLayoutFlow
XLayoutRoot
XLayoutUnit
XListBox
gives access to the items of a list box and makes it possible to register item and
action event listeners.
XMenu
XMenuBar
11
XMenuBarExtended
XMenuExtended
XMenuExtended2
XMenuListener
XMessageBox
[ DEPRECATED ]
gives access to a message box.
XMessageBoxFactory
XMetricField
XMouseClickHandler
XMouseListener
XMouseMotionHandler
XMouseMotionListener
XNumericField
XPaintListener
XPatternField
XPointer
XPopupMenu
XPopupMenuExtended
XPrinter
XPrinterPropertySet
XPrinterServer
12
XProgressBar
XProgressMonitor
[ DEPRECATED ]
gives access to the text of a progress monitor.
XRadioButton
gives access to the state of a radio button and makes it possible to register item
event listeners.
XRegion
XRequestCallback
XReschedule
[ DEPRECATED ]
The XReschedule interface can be used to give control to the main thread to allow
events processing.
XScrollBar
gives access to the value and settings of a scroll bar and makes it possible to
register adjustment event listeners.
XSimpleAnimation
XSimpleTabController
specifies the basic operations for a tab controller, but does not require XControl
as type of tabs.
XSpinField
gives access to the value of a spin field and makes it possible to register for spin
events.
XSpinListener
XSpinValue
gives access to the value and settings of a control which is associated with a
spinnable value.
XSystemChildFactory
XSystemDependentMenuPeer
XSystemDependentWindowPeer
XTabController
XTabControllerModel
XTabListener
13
XTextArea
XTextComponent
gives access to the text of a component and makes it possible to register event
listeners.
XTextEditField
XTextLayoutConstrains
XTextListener
XThrobber
XTimeField
XToggleButton
XToolkit
XTopWindow
XTopWindowListener
XUnitConversion
XUnoControlContainer
XUserInputInterception
Interface to add handlers for key and mouse events. A handler is not a passive
listener, it can even consume the event.
XVclContainer
[ DEPRECATED ]
represents a VCL container window.
XVclContainerListener
[ DEPRECATED ]
makes it possible to receive container events.
XVclContainerPeer
[ DEPRECATED ]
gives access to the VCL container window implementation.
XVclWindowPeer
[ DEPRECATED ]
gives access to the VCL window implementation.
14
XView
XWindow
XWindow2
XWindowListener
XWindowListener2
XWindowPeer
Structs
ActionEvent
AdjustmentEvent
DeviceInfo
DockingData
DockingEvent
EndDockingEvent
EndPopupModeEvent
EnhancedMouseEvent
FocusEvent
FontDescriptor
Gradient
InputEvent
ItemEvent
15
KeyEvent
KeyStroke
MenuEvent
MenuLogo
MouseEvent
PaintEvent
Point
Rectangle
Selection
SimpleFontMetric
Size
SpinEvent
SystemDependentXWindow
[ DEPRECATED ]
specifies a system dependent XWindow.
TextEvent
VclContainerEvent
WindowDescriptor
describes a window.
WindowEvent
Exceptions
MaxChildrenException
PrinterException
16
Enums
AdjustmentType
FontSlant
GradientStyle
MenuItemType
PushButtonType
RasterOperation
These values are used to specify the binary pixel-operation applied when pixels
are written to the device.
WindowClass
Constant Groups
CharSet
[ DEPRECATED ]
These values are used to specify the characters which are available in a font and
their codes.
Command
DeviceCapability
FieldUnit
FocusChangeReason
A combination of these values can be used to specify the reason for a focus
change.
FontEmphasisMark
FontFamily
FontPitch
These values are used to specify whether the width of a character is fixed or
variable.
FontRelief
17
FontStrikeout
FontType
These values are used to specify the technology of the font representation.
FontUnderline
FontWeight
FontWidth
These values are used to specify the width of the characters of a font.
ImageAlign
ImagePosition
ImageScaleMode
defines modes how an image displayed in a given area should be scaled to fit this
area
ImageStatus
InvalidateStyle
Key
KeyFunction
KeyGroup
[ DEPRECATED ]
These values are used to specify functional groups of keys.
KeyModifier
These values are used to specify which modifier keys are pressed.
LineEndFormat
These values are used to specify which line end format should be used in strings
MenuItemStyle
MessageBoxButtons
MessageBoxCommand
[ DEPRECATED ]
specifies a message box command.
MouseButton
These values are used to specify which keys on the mouse are pressed.
PopupMenuDirection
These values are used to specify the direction in which a popup menu will grow.
18
PosSize
ScrollBarOrientation
Style
SystemPointer
TextAlign
VclWindowPeerAttribute
[ DEPRECATED ]
specifies attributes for the VCL window implementation.
VisualEffect
WindowAttribute
The well-known Model-View-Controller (MVC) paradigm separates three application areas: document data
(model), presentation (view) and interaction (controller). OpenOffice.org has a similar abstraction, called the
Frame-Controller-Model (FCM) paradigm. The FCM paradigm shares certain aspects with MVC, but it has
different purposes; therefore, it is best to approach FCM independently from MVC. The model and controller
in MVC and FCM are quite different things.
The FCM paradigm in OpenOffice.org separates three application areas: document object (model), screen
interaction with the model (controller) and controller-window linkage (frame).
The model holds the document data and has methods to change these data without using a controller
object. Text, drawings, and spreadsheet cells are accessed directly at the model.
19
The controller has knowledge about the current view status of the document and manipulates the
screen presentation of the document, but not the document data. It observes changes made to the
model, and can be duplicated to have multiple controllers for the same model.
The frame contains the controller for a model and knows the windows that are used with it, but does not
have window functionality.
The purpose of FCM is to have three exchangeable parts that are used with an exchangeable window
system:
It is possible to write a new controller that presents an existing model in a different manner without changing
the model or the frame. A controller depends on the model it presents; therefore, a new controller for a new
model can be written.
Developers can introduce new models for new document types without taking care of the frame and
underlying window management system. However, since there is no default controller, it is necessary to write
a suitable controller also.
By keeping all window-related functionality separate from the frame, it is possible to use one single frame
implementation for every possible window in the entire OpenOffice.org application. Thus, the presentation of
all visible components is customized by exchanging the frame implementation. At runtime you can access a
frame and replace the controller, together with the model it controls, by a different controller instance.
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.
20
When a frame is constructed, the frame must be initialized with a container window using
com.sun.star.frame.XFrame:initialize(). This method expects the com.sun.star.awt.XWindow interface of a
surrounding window instance, which becomes the container window of the frame. The window instance
passed to initialize() must also support com.sun.star.awt.XTopWindow to become a container window.
The container window must broadcast window events, such as windowActivated(), and appear in front
of other windows or be sent to the background. The fact that container windows support
com.sun.star.awt.XTopWindow does not mean the container window is an independent window of the
underlying window system with a title bar and a system menu. An XTopWindow 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 com.sun.star.frame.XFrame:setComponent() that takes another
com.sun.star.awt.XWindow instance and the com.sun.star.frame.XController 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 XTopWindow
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 initialize(), this window becomes its container window. When a component is set into a frame using
setComponent(), another com.sun.star.awt.XWindow 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 com.sun.star.frame.XFramesSupplier interface of the desktop is passed to the method
setCreator() at the XFrame interface. This happens internally when the method append() is called at
the com.sun.star.frame.XFrames interface supplied by the desktop.
A component window can have sub-windows, and that is the case with all documents in OpenOffice.org. For instance, a text
document has sub-windows for the toolbars and the editable text. Form controls are sub-windows, as well, however, these subwindows 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.
21
22
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 com.sun.star.frame.Controller service
represented by the interface com.sun.star.frame.XController. In the call to
com.sun.star.frame.XFrame:setComponent(), the controller is passed with the component window instance.
If the component has no controller, it directly implements com.sun.star.lang.XComponent and
com.sun.star.awt.XWindow. In this case, the component is passed as XWindow parameter, and the
XController parameter must be an XController reference set to null.
If the viewable component is a trivial component (implementing XWindow 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
com.sun.star.frame.XDispatchProvider interface.
Controllers
Controllers in OpenOffice.org are between a frame and document model. This is their basic role as
expressed in com.sun.star.frame.XController, which has methods getModel() and getFrame(). The
method getFrame() provides the frame that the controller is attached to. The method getModel() returns
a document model, but it may return an empty reference if the component does not have a model.
Usually the controller objects support additional interfaces specific to the document type they control, such
as com.sun.star.sheet.XSpreadsheetView for Calc document controllers or
com.sun.star.text.XTextViewCursorSupplier for Writer document controllers.
23
24
com::sun::star::frame::XFrame getCurrentFrame ()
com::sun::star::container::XEnumerationAccess getComponents ()
com::sun::star::lang::XComponent getCurrentComponent ()
boolean terminate ()
void addTerminateListener ( [in] com::sun::star::frame::XTerminateListener
xListener)
void removeTerminateListener ( [in] com::sun::star::frame::XTerminateListener
xListener)
The methods getCurrentFrame() and getCurrentComponent() distribute the active frame and
document model, whereas getComponents() returns a com.sun.star.container.XEnumerationAccess to all
loaded documents. For documents loaded in the desktop environment the methods getComponents() and
getCurrentComponent() always return the com.sun.star.lang.XComponent interface of the document
model.
If a specific document component is required, but you are not sure whether this component is the current component, use
getComponents() to get an enumeration of all document components, check each for the existence of the
com.sun.star.frame.XModel interface and use getURL() at XModel to identify your document. Since not all components
have to support XModel, test for XModel before calling getURL().
The office process is usually terminated when the user selects File - Exit or after the last application window
has been closed. Clients can terminate the office through a call to terminate() and add a terminate
listener to veto the shutdown process.
As long as the Windows quickstarter is active, the soffice executable is not terminated.
26
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;
public class TerminateListener implements XTerminateListener {
public void notifyTermination (com.sun.star.lang.EventObject eventObject)
{
System.out.println("about to terminate...");
}
public void queryTermination (com.sun.star.lang.EventObject eventObject)
throws TerminationVetoException {
// test if we can terminate now
if (TerminationTest.isAtWork() == true) {
System.out.println("Terminate while we are at work? No way!");
throw new TerminationVetoException() ; // this will veto the
termination,
// a call to terminate()
returns false
}
}
public void disposing (com.sun.star.lang.EventObject eventObject) {
}
}
The following class TerminationTest tests the TerminateListener above.
import
import
import
import
import
import
com.sun.star.bridge.XUnoUrlResolver;
com.sun.star.uno.UnoRuntime;
com.sun.star.uno.XComponentContext;
com.sun.star.lang.XMultiComponentFactory;
com.sun.star.beans.XPropertySet;
com.sun.star.beans.PropertyValue;
import com.sun.star.frame.XDesktop;
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;
public class TerminationTest extends java.lang.Object {
private static boolean atWork = false;
public static void main(String[] args) {
XComponentContext xRemoteContext = null;
XMultiComponentFactory xRemoteServiceManager = null;
27
e.printStackTrace();
}
finally {
System.exit(0);
}
}
public static boolean isAtWork() {
return atWork;
}
}
The office freezes when terminate() is called if there are unsaved changes. As a workaround set all
documents into an unmodified state through their com.sun.star.util.XModifiable interface or store them using
com.sun.star.frame.XStorable.
The Desktop offers a facility to load components through its interface
com.sun.star.frame.XComponentLoader. It has one method:
almost all of its methods are dummy implementations. The default implementation of the desktop object in
OpenOffice.org is not able to contain a component and refuses to be attached to it, because the desktop is
still a frame that is the root for the common hierarchy of all frames in OpenOffice.org. The desktop has to be
a frame because its com.sun.star.frame.XFramesSupplier interface must be passed to
com.sun.star.frame.XFrame:setCreator() at the child frames, therefore the desktop becomes the parent
frame. However, the following functionality of com.sun.star.frame.Frame is still in place:
The desktop interface com.sun.star.frame.XFramesSupplier offers methods to access frames. This interface
inherits from com.sun.star.frame.XFrame, and introduces the following methods:
com::sun::star::frame::XFrames getFrames ()
com::sun::star::frame::XFrame getActiveFrame ()
void setActiveFrame ( [in] com::sun::star::frame::XFrame xFrame)
The method getFrames() returns a com.sun.star.frame.XFrames container, that is a
com.sun.star.container.XIndexAccess, with additional methods to add and remove frames:
30
void dispose ()
void addEventListener ( [in] com::sun::star::lang::XEventListener xListener)
void removeEventListener ( [in] com::sun::star::lang::XEventListener
aListener)
The process to resolve the circular dependencies of the component framework is a complex. For instance,
the objects involved in the process may be in a condition where they may not be disposed of. Refer to the
section Closing Documents for additional details.
Theoretically every UNO object could exist in a frame, as long as it is willing to let the frame control its
existence when it ends.
A trivial component (XWindow only) is enough for simple viewing purposes, where no activation of a
component and related actions like cursor positioning or user interactions are necessary.
If the component participates in more complex interactions, it must implement the controller service.
Many features of the desktop environment are only available if the URL of a component is known. For
example:
31
a controller object that presents the model or shows a view to the model that implements the
com.sun.star.frame.Controller service, but publishes additional document-specific interfaces. For almost
all OpenOffice.org document types there are document specific controller object specifications,such as
com.sun.star.sheet.SpreadsheetView, and com.sun.star.drawing.DrawingDocumentDrawView. For
controllers, refer to the section Controllers.
Usually developers require the controller and frame of an already loaded document model. The
com.sun.star.frame.XModel interface of OpenOffice.org document models gets the controller that provides
access to the frame through its com.sun.star.frame.XController interface. The following illustration shows the
methods that get the controller and frame for a document model and conversely. From the frame , obtain the
corresponding component and container window.
Frame-Controller-Model Organization
If the loaded component is a trivial component and implements com.sun.star.awt.XWindow only, the window
and the window peer is reached by querying these interfaces from the com.sun.star.lang.XComponent
returned by loadComponentFromURL().
32
Frames
Frame Service
XFrame
Frame Setup
The main role of a frame is to link components into a surrounding window system. This role is expressed by
the following methods of the frame's main interface com.sun.star.frame.XFrame:
Frame Hierarchies
When frames link components into a surrounding window system, they build a frame hierarchy. This aspect
is covered by the hierarchy-related XFrame methods:
33
34
Returns the frame itself, same as an empty target frame name. This means you are searching for a
frame you already have, but it is legal to do so.
_blank
Creates a new top-level frame whose parent is the desktop frame.
Calls with "_top" or "_parent" return the frame itself if the called frame is a top frame or has no parent.
This is compatible to the targeting strategies of web browsers.
We have seen that findFrame() is called recursively. To control the recursion, the search flags parameter
specified in the constants group com.sun.star.frame.FrameSearchFlag is used. For all of the five steps
mentioned above, a suitable flag exists (SELF, CHILDREN, SIBLINGS, PARENT, CREATE). Every search step
can be prohibited by deleting the appropriate FrameSearchFlag. The search flag parameter can also be
used to avoid ambiguities caused by multiple occurrences of a frame name in a hierarchy by excluding parts
of the frame tree from the search. If findFrame() is called for a reserved frame name, the search flags are
ignored.
An additional flag can be used to extend a bottom-up search to all OpenOffice.org application
windows, no matter where the search starts. Based on the five flags for the five steps, the default
frame search stops searching when it reaches a top frame and does not continue with other
OpenOffice.org windows. Setting the TASKS flag overrides this.
There are separate frame hierarchies that do not interact with each other. If a frame is created, but not
inserted into any hierarchy, it becomes the top frame of its own hierarchy. This frame and its contents can
not be accessed from other hierarchies by traversing the frame hierarchies through API calls. Also, this
frame and its content cannot reach frames and their contents in other hierarchies. It is the code that creates
a frame and decides if the new frame becomes part of an existing hierarchy, thus enabling it to find other
frames, and making it and its viewable component visible to the other frames. Examples for frames that are
not inserted into an existing hierarchy are preview frames in dialogs, such as the document preview in the
File - New - Templates and Documents dialog.
This is the only way the current frame and desktop implementation handle this. If one exchanges
either or both of them by another implementation, the treatment of the " _blank" target and the
Frame Actions
Several actions take place at a frame. The context of viewable components can change, a frame may be
activated or the relationship between frame and component may be altered. For instance, when the current
selection in a document has been changed, the controller informs the frame about it by calling
contextChanged(). The frame then tells its frame action listeners that the context has changed. The
frame action listeners are also informed about changes in the relationship between the frame and
component, and about frame activation. The corresponding XFrame methods are:
COMPONENT_ATTACHED: a component has been attached to a frame. This is almost the same as the instantiation
of the component within that frame. The component is attached to the frame immediately before this event is broadcast.
COMPONENT_DETACHING: a component is detaching from a frame. This is the same as the destruction of the
component which was in that frame. The moment the event is broadcast the component is still attached to the frame,
but in the next moment it will not be..
COMPONENT_REATTACHED: a component has been attached to a new model. In this case, the component
remains the same, but operates on a new model component.
frameAction()
FRAME_ACTIVATED: a component has been activated. Activations are broadcast from the top component which
was not active, down to the innermost component.
CONTEXT_CHANGED: a component has changed its internal context, for example, the selection. If the activation
status within a frame changes, this is a context change, also.
At this time, the XFrame methods used to build a frame-controller-model relationship can only be fully utilized by frame
loader implementations or customized trivial components. Outside a frame loader you can create a frame, but the current
implementations cannot create a standalone controller that could be used with setComponent(). Therefore, you can not
remove components from one frame and add them to another or create additional controllers for a loaded model using the
36
component framework. This is due to restrictions of the VCL and the C++ implementation of the current document
components.
Currently, the only way for clients to construct a frame and insert a OpenOffice.org document into it, is to use the
com.sun.star.frame.XComponentLoader interface of the com.sun.star.frame.Desktop or the interfaces
com.sun.star.frame.XSynchronousFrameLoader, the preferred frame loader interface, and the asynchronous
com.sun.star.frame.XFrameLoader of the com.sun.star.frame.FrameLoader service that is available at the global service
factory.
The recommended method to get additional controllers for loaded models is to use the
XFramesSupplier
The Frame interface com.sun.star.frame.XFramesSupplier offers methods to access sub-frames of a frame.
The frame implementation of OpenOffice.org supports this interface. This interface inherits from
com.sun.star.frame.XFrame, and introduces the following methods:
com::sun::star::frame::XFrames getFrames ()
com::sun::star::frame::XFrame getActiveFrame ()
void setActiveFrame ( [in] com::sun::star::frame::XFrame xFrame)
The method getFrames() returns a com.sun.star.frame.XFrames container, that is a
com.sun.star.container.XIndexAccess with additional methods to add and remove frames:
37
XStatusIndicatorFactory
The frame implementation supplies a status indicator through its interface
com.sun.star.task.XStatusIndicatorFactory. A status indicator can be used by a frame loader to show the
loading process for a document. The factory has only one method that returns an object supporting
com.sun.star.task.XStatusIndicator:
com::sun::star::task::XStatusIndicator createStatusIndicator ()
The status indicator is displayed by a call to com.sun.star.task.XStatusIndicator:start(). Pass a text and a
numeric range, and use setValue() to let the status bar grow until the maximum range is reached. The
method end() removes the status indicator.
Controllers
Controller Service
XController
A com.sun.star.frame.XController inherits from com.sun.star.lang.XComponent and introduces the following
methods:
38
com::sun::star::frame::XFrame getFrame ()
void attachFrame (com::sun::star::frame::XFrame xFrame)
com::sun::star::frame::XModel getModel ()
boolean attachModel (com::sun::star::frame::XModel xModel)
boolean suspend (boolean bSuspend)
any getViewData ()
void restoreViewData (any Data)
The com.sun.star.frame.XController links model and frame through the methods get/attachModel() and
get/attachFrame(). These methods and the corresponding methods in the com.sun.star.frame.XModel
and com.sun.star.frame.XFrame interfaces act together. calling attachModel() at the controller must be
accompanied by a corresponding call of connectController() at the model, and attachFrame() at the
controller must have its counterpart setComponent() at the frame.
The controller is asked for permission to dispose of the entire associated component by using suspend().
The suspend() method shows dialogs, for example, to save changes. To avoid the dialog, close the
corresponding frame without using suspend() before. The section Closing Documents provides additional
information.
Developers retrieve and restore data used to setup the view at the controller by calling
get/restoreViewData(). These methods are usually called on loading and saving the document, but
they also allow developers to manipulate the state of a view from the outside. The exact content of this data
depends on the concrete controller/model pair.
XDispatchProvider
Through com.sun.star.frame.XDispatchProvider, the controller participates in the dispatch framework. It is
described in section Using the Dispatch Framework.
XSelectionSupplier
The optional Controller interface com.sun.star.view.XSelectionSupplier accesses the selected object and
informs listeners when the selection changes:
39
XContextMenuInterception
The optional Controller interface com.sun.star.ui.XContextMenuInterception intercepts requests for
context menus in the document's window. See chapter Intercepting Context Menus.
General Description
Calc Spreadsheet
Document Controller
com.sun.star.sheet.SpreadsheetView
com.sun.star.drawing.DrawingDocumentDrawView
DataBaseAccess
com.sun.star.sdb.DataSourceBrowser
Bibliography
Writer (PagePreview)
Writer/Webdocument
40
com.sun.star.presentation.PresentationView
(SourceView)
Calc (PagePreview)
Chart Chart
Document Controller
Math
Models
There is not an independent specification for a model service. The interface com.sun.star.frame.XModel is
currently supported by Writer, Calc, Draw and Impress document components. In our context, we call objects
supporting com.sun.star.frame.XModel, model objects. All OpenOffice.org document components have the
service com.sun.star.document.OfficeDocument in common. An OfficeDocument implements the following
interfaces:
XModel
The interface com.sun.star.frame.XModel inherits from com.sun.star.lang.XComponent and introduces the
following methods, which handle the model's resource description, manage its controllers and retrieves the
current selection.
string getURL ()
sequence < com::sun::star::beans::PropertyValue > getArgs ()
boolean attachResource ( [in] string aURL,
[in] sequence < com::sun::star::beans::PropertyValue
aArgs > )
com::sun::star::frame::XController getCurrentController ()
void setCurrentController (com::sun::star::frame::XController xController)
void connectController (com::sun::star::frame::XController xController)
void disconnectController (com::sun::star::frame::XController xController)
void lockControllers ()
void unlockControllers ()
boolean hasControllersLocked ()
41
com::sun::star::uno::XInterface getCurrentSelection ()
The method getURL() provides the URL where a document was loaded from or last stored using
storeAsURL(). As long as a new document has not been saved, the URL is an empty string. The method
getArgs() returns a sequence of property values that report the resource description according to
com.sun.star.document.MediaDescriptor, specified on loading or saving with storeAsURL. The method
attachResource() is used by the frame loader implementations to inform the model about its URL and
MediaDescriptor.
The current or last active controller for a model is retrieved through getCurrentController(). The
corresponding method setCurrentController() sets a different current controller at models where
additional controllers are available. However, additional controllers can not be created at this time for
OpenOffice.org components using the component API. The method connectController() is used by
frame loader implementations and provides the model with a new controller that has been created for it,
without making it the current controller. The disconnectController() tells the model that a controller
may no longer be used. Finally, the model holds back screen updates using lockControllers() and
unlockControllers(). For each call to lockControllers(), there must be a call to
unlockControllers() to remove the lock. The method hasControllersLocked() tells if the
controllers are locked.
The currently selected object is retrieved by a call to getCurrentSelection(). This method is an
alternative to getSelection() at the com.sun.star.view.XSelectionSupplier interface supported by
controller services.
XModifiable
The interface com.sun.star.util.XModifiable traces the modified status of a document:
XStorable
The interface com.sun.star.frame.XStorable stores a document under an arbitrary URL or its current location.
Details about how to use this interface are discussed in the chapter Handling Documents.
XPrintable
The interface com.sun.star.view.XPrintable is used to set and get the printer and its settings, and dispatch
print jobs. These methods and special printing features for the various document types are described in the
chapters Printing Text Documents, Printing Spreadsheet Documents, Printing Drawing Documents and
Printing Presentation Documents.
42
XEventBroadcaster
For versions later than 641, the optional interface com.sun.star.document.XEventBroadcaster at office
documents enables developers to add listeners for events related to office documents in general, or for
events specific for the individual document type.See Document Events).
XEventsSupplier
The optional interface com.sun.star.document.XEventsSupplier binds the execution of dispatch URLs to
document events, thus providing a configurable event listener as a simplification for the more general event
broadcaster or listener mechanism of the com.sun.star.document.XEventBroadcaster interface. This is done
programmatically versus manually in Tools - Configure - Events.
XDocumentInfoSupplier
The optional interface com.sun.star.document.XDocumentInfoSupplier provides access to document
information as described in section Document Info. Document information is presented in the File Properties dialog in the GUI.
XViewDataSupplier
The optional com.sun.star.document.XViewDataSupplier interface sets and restores view data.
com::sun::star::container::XIndexAccess getViewData ()
43
Service
Chapter
Calc
com.sun.star.sheet.SpreadsheetDocument
Spreadsheet Documents
Draw
com.sun.star.drawing.DrawingDocument
Impress
Math
com.sun.star.formula.FormulaProperties
Text Documents
Chart
Charts
com.sun.star.chart.ChartDocument
Refer to the related chapters for additional information about the interfaces of the documents of
OpenOffice.org.
Window Interfaces
The window interfaces of the component window and container window control the OpenOffice.org
application windows. This chapter provides a short overview.
44
XWindow
The interface com.sun.star.awt.XWindow is supported by the component and controller windows. This
interface comprises methods to resize a window, control its visibility, enable and disable it, and make it the
focus for input device events. Listeners are informed about window events.
[oneway] void setPosSize ( long X, long Y, long Width, long Height, short
Flags );
com::sun::star::awt::Rectangle getPosSize ();
[oneway] void setVisible ( boolean Visible );
[oneway] void setEnable ( boolean Enable );
[oneway] void setFocus ();
[oneway] void addWindowListener ( com::sun::star::awt::XWindowListener
xListener );
[oneway] void removeWindowListener ( com::sun::star::awt::XWindowListener
xListener );
[oneway] void addFocusListener ( com::sun::star::awt::XFocusListener xListener
);
[oneway] void removeFocusListener ( com::sun::star::awt::XFocusListener
xListener );
[oneway] void addKeyListener ( com::sun::star::awt::XKeyListener xListener );
[oneway] void removeKeyListener ( com::sun::star::awt::XKeyListener xListener
);
[oneway] void addMouseListener ( com::sun::star::awt::XMouseListener xListener
);
[oneway] void removeMouseListener ( com::sun::star::awt::XMouseListener
xListener );
[oneway] void addMouseMotionListener (
com::sun::star::awt::XMouseMotionListener xListener );
[oneway] void removeMouseMotionListener (
com::sun::star::awt::XMouseMotionListener xListener );
[oneway] void addPaintListener ( com::sun::star::awt::XPaintListener xListener
);
[oneway] void removePaintListener ( com::sun::star::awt::XPaintListener
xListener );
The com.sun.star.awt.XWindowListener gets the following notifications. The com.sun.star.awt.WindowEvent
has members describing the size and position of the window.
[oneway]
[oneway]
[oneway]
[oneway]
void
void
void
void
45
XTopWindow
The interface com.sun.star.awt.XTopWindow is available at container windows. It informs listeners about top
window events, and it can put itself in front of other windows or withdraw into the background. It also has a
method to control the current menu bar:
The top window listener receives the following messages. All methods take a com.sun.star.awt.WindowEvent
with members describing the size and position of the window.
[oneway]
[oneway]
[oneway]
[oneway]
[oneway]
[oneway]
[oneway]
void
void
void
void
void
void
void
XWindowPeer
Each XWindow has a com.sun.star.awt.XWindowPeer. The com.sun.star.awt.XWindowPeer interface
accesses the window toolkit implementation used to create it and provides the pointer of the pointing device,
and controls the background color. It is also used to invalidate a window or portions of it to trigger a redraw
cycle.
com::sun::star::awt::XToolkit getToolkit ()
[oneway] void setPointer ( [in] com::sun::star::awt::XPointer Pointer )
[oneway] void setBackground ( [in] long Color )
[oneway] void invalidate ( [in] short Flags )
[oneway] void invalidateRect ( [in] com::sun::star::awt::Rectangle Rect,
[in] short Flags )
46
Frame Creation
Every time a frame is needed in OpenOffice.org, the com.sun.star.frame.Frame service is created.
OpenOffice.org has an implementation for this service, available at the global service manager.
This service can be replaced by a different implementation, for example, your own implementation in Java,
by registering it at the service manager. In special cases, it is possible to use a custom frame implementation
instead of the com.sun.star.frame.Frame service by instantiating a specific implementation using the
implementation name with the factory methods of the service manager. Both methods can alter the default
window and document handling in OpenOffice.org, thus changing or extending its functionality.
The second condition is that if a frame and its component are supposed to get windowActivated()
messages, the window object implements the additional interface com.sun.star.awt.XTopWindow. This is
necessary for editing components, because the windowActivated event shows a cursor or a selection in
the document. As long as this condition is met, further code is not necessary for the interaction between the
frame and window, because the frame gets all the necessary events from the window by registering the
appropriate listeners in the call to initialize().
When you use the com.sun.star.awt.Toolkit to create windows, supply a com.sun.star.awt.WindowDescriptor
struct to describe what kind of window is required. Set the Type member of this struct to
com.sun.star.awt.WindowClass:TOP and the WindowServiceName member to "window" if you want to
have an application window, or to "dockingwindow" if a window is need to be inserted in other windows
created by the toolkit.
The following example creates a new window and a frame, plugs them together, and adds them to the
desktop, thus creating a new, empty OpenOffice.org application window.
=
=
=
=
=
com.sun.star.awt.WindowClass.TOP ;
"window" ;
-1;
null;
new com.sun.star.awt.Rectangle(0,0,0,0);
aDescriptor.WindowAttributes =
com.sun.star.awt.WindowAttribute.BORDER
com.sun.star.awt.WindowAttribute.MOVEABLE
48
|
|
com.sun.star.awt.WindowAttribute.SIZEABLE |
com.sun.star.awt.WindowAttribute.CLOSEABLE ;
com.sun.star.awt.XWindowPeer xPeer = xToolkit.createWindow(aDescriptor) ;
com.sun.star.awt.XWindow xWindow =
(com.sun.star.awt.XWindow)UnoRuntime.queryInterface ( com.sun.star.awt.XWindow
.class, xPeer);
// Create a new empty target frame.
// Attention: Before {{PRODUCTNAME}} build 643 we must use
// com.sun.star.frame.Task instead of com.sun.star.frame.Frame,
// because the desktop environment accepts only this special frame type
// as direct children. It will be deprecated from build 643
xFrame = (com.sun.star.frame.XFrame)UnoRuntime.queryInterface(
com.sun.star.frame.XFrame.class,
xSMGR.createInstance ("com.sun.star.frame.Task "));
// Set the container window on it. xFrame.initialize(xWindow) ;
// Insert the new frame in desktop hierarchy.
// Use XFrames interface to do so. It provides access to the
// child frame container of the parent node.
// Note: append(xFrame) calls xFrame.setCreator(Desktop) automatically.
com.sun.star.frame.XFramesSupplier xTreeRoot =
(com.sun.star.frame.XFramesSupplier)UnoRuntime.queryInterface(
com.sun.star.frame.XFramesSupplier.class,
xSMGR.createInstance("com.sun.star.frame.Desktop") );
com.sun.star.frame.XFrames xChildContainer = xTreeRoot.getFrames ();
xChildContainer.append(xFrame) ;
// Make some other initializations.
49
Handling Documents
Loading Documents
The framework API defines a simple but powerful interface to load viewable components, the
com.sun.star.frame.XComponentLoader. This interface is implemented by the globally accessible
com.sun.star.frame.Desktop service and also by the com.sun.star.frame.Frame service.
50
MediaDescriptor
A call to loadComponentFromURL() receives a sequence of com.sun.star.beans.PropertyValue structs as
a parameter, which implements the com.sun.star.document.MediaDescriptor service, consisting of property
definitions. In general it describes a resource and how it shall be handled in the particular context where the
MediaDescriptor is used. In the context of loading a file it describes the "from where" and the "how". In the
content of storing a document using the interface com.sun.star.frame.XStorable it describes the "where to"
and the "how". The table below shows the properties defined in the media descriptor.
Some properties are used for loading and saving while others apply to one or the other. If a media descriptor
is used, only a few of the members are specified. The others assume default values. Strings default to empty
strings in general and interface references default to empty references. For all other properties, the default
values are specified in the description column of the table.
Some properties are tagged deprecated. There are old implementations that still use these properties. They
are supported, but are discouraged to use them. Use the new property that can be found in the description
column of the deprecated property.
To develop a UNO component that uses the media descriptor, note that all the properties are under control
of the framework API. Never create your own property names for the media descriptor, or name clashes may
be induced if the framework defines a property that uses the same name. Instead, use the ComponentData
property to transport document specific information. ComponentData is specified to be an any, therefore it
can be a sequence of property values by itself. If you do use it. make an appropriate specification available
to users of your component.
Properties of com.sun.star.document.MediaDescriptor
boolean. Setting AsTemplate to true creates a new untitled document out of the loaded document, even
if it has no template extension.
AsTemplate
Loading a template, that is, a document with a template extension, creates a new untitled document by
default, but setting the AsTemplate property to false loads a template for editing.
Author
string. Only for storing versions in components supporting versioning: author of version.
CharacterSet
string. Defines the character set for document formats that contain single byte characters, if necessary.
Which character set names are valid depends on the filter implementation, but with the current filters you
can employ the character sets used for the conversion of byte to unicode strings.
Comment
string. Only for storing versions in components supporting versioning: comment (description) for stored
version.
ComponentData
any. This is a parameter that is used for any properties specific for a special office component type.
51
FileName - deprecated
FilterData
any. This is a parameter that is used for any properties specific for a special filter type.
FilterName
string. Name of a filter that should be used for loading or storing the component. Names must match the
names of the typedetection configuration. Invalid names are ignored. If a name is specified on
loading, it will be verified by a filter detection, but in case of doubt it will be preferred.
FilterFlags - deprecated
FilterOptions
string. Some filters need additional parameters. Use only together with property FilterName. Details must be
documented by the filter. This is an old format for some filters. If a string is not enough, filters can use the
property FilterData.
Hidden
boolean. Defines if the loaded component is made visible. If this property is not specified, the component is
made visible by default. Prior to OpenOffice.org 2.3 a document could be loaded either "hidden" or "visible",
but is wasn't possible to change the visibility of its frame afterwards (by calling setVisible() at the
container window) without risking a crash later on. But starting with version 2.3 doing this is safe. Note that a
"hidden" frame (or the document it contains) must be closed by the code that created it or switched it to the
hidden state.
because an InputStream is only usable once for reading. Even if it implements the
com.sun.star.io.XSeekable interface, do not interfere with the model's reading process. Consider all the
objects involved in the loading process as temporary.
JumpMark
string. Jump to a marked position after loading. The office document loaders expect simple strings used like
targets in HTML documents.Do not use a leading # character. The meaning of a jump mark depends upon
the filter, but in Writer, bookmarks can be used, whereas in Calc cells, cell ranges and named areas are
supported.
string. Type of the medium to load that must match to one of the types defined in the
MediaType (string)
OpenFlags - deprecated
52
typedetection
string. For compatibility reasons: string that summarizes some flags for loading. The string contains capital
letters for the flags:
"ReadOnly" - "R"
"Preview" - "B"
"AsTemplate" - "T"
"Hidden" - "H"
Use the corresponding boolean parameters instead.
OpenNewView
boolean. Affects the behavior of the component loader when a resource is already loaded. If true, the loader
tries to open a new view for a document already loaded. For components supporting multiple views, a
second window is opened as if the user clicked Window - New Window. Other components are loaded one
more time. Without this property, the default behavior of the loader applies, for example, the loader of the
desktop activates a document if the user tries to load it a second time.
Overwrite
boolean. For storing only: overwrite existing files with the same name, default is true, so an
com.sun.star.io.IOException occurs if the target file already exists. If the default is changed and the file
exists, the UCB throws an exception. If the file is loaded through API, this exception is transported to the
caller or handled by an interaction handler.
Password
string. A password for loading or storing a component, if necessary. If no password is specified, loading of a
password protected document fails, storing is done without encryption.
PostData
reference <XinputStream>. HTTP post data to send to a location described by the media descriptor to get a
result that is loaded as a component, usually in webforms. Default is: no PostData.
PostString - deprecated
string. Same as PostData, but the data is transferred as a string (just for compatibility).
Preview
boolean. Setting this to true tells the loaded component that it is loaded as a preview, so that it can optimize
loading and viewing for this special purpose. Default is false.
ReadOnly
boolean. Tells if a document is to be loaded in a (logical) readonly or in read/write mode. If opening in the
desired mode is impossible, an error occurs. By default, the loaded content decides what to do. If its UCB
content supports a "readonly" property, the logical open mode depends on that property, otherwise it is
read/write.
This property only affects the UI. Opening a document in read only mode does not prevent the component
from being modified by API calls, but all modifying functionality in the UI is disabled or removed.
Referer
(the wrong spelling is
string. A URL describing the environment of the request; for example,. a referrer may be the URL of a
document, if a hyperlink inside this document is clicked to load another document. The referrer may be
evaluated by the addressed UCB content or the loaded document.
Without a referrer, the processing of URLs that require security checks is denied, for instance macro: URLs.
createStatusIndicator() at the frame you load a component into. Usually you do not need
this parameter if you do not want to use any other indicator than the one in the status bar of the document
window. It is not allowed to keep a reference to this object, not even in the loaded or stored component's
copy of the MediaDescriptor provided by its getArgs() method.
TemplateName
string. The logical name of a template to load. Together with the TemplateRegionName property this
is used instead of the URL of the template. The logical names are the template names you see in the
53
templates dialog.
TemplateRegionName
string. See TemplateName. The template region names are the folder names you see in the templates
dialog.
Unpacked
boolean. For storing: Setting this to true means that a zip file is not used to save the document. Use a folder
instead for UCB contents that support folders, such as file, WebDAV, and ftp. Default is false.
URL
Version
short. For components supporting versioning: the number of the version to be loaded or saved. Default is
zero and means that no version is created or loaded, and the main document is processed.
ViewData
any. Data to set a special view state after loading. The type depends on the component and is retrieved
from a controller object by its com.sun.star.document.XViewDataSupplier interface. Default is: no ViewData.
ViewId
short. For components supporting different views: a number to define the view that should be constructed
after loading. Default is: zero, and this should be treated by the component as the default view.
MacroExecutionMode
short. How should the macro be executed - the value should be one from
com.sun.star.document.MacroExecMode constants group
UpdateDocMode
short. Can the document be updated depending on links. The value should be one from
com.sun.star.document.UpdateDocMode constant group
The media descriptor used for loading and storing components is passed as an in/out parameter to some
methods of objects that participate in the loading or storing process, e.g. the
com.sun.star.document.TypeDetection service or a com.sun.star.document.ExtendedTypeDetection service,
but also to the filter objcects involved. This enable these objects to add more information to the
MediaDescriptor. As an example, if the MediaDescriptor at the beginning just contains a URL. If an object
uses this URL to open a stream, it should add this stream to the MediaDescriptor (Stream, InputStream or
OutputStream). This prevents that other objects have to create the stream a second time (unfortunate if a
remote file is loaded) and it must be reused by later users of the MediaDescriptor.
So if a method gets a MediaDescriptor parameter for loading content it is supposed to do the following:
if you find a stream, don't expect that its position is at the beginning of the file, seek to the position where
you want to start
only if none of these properties is available, try to create a stream by yourself from other properties, e.g.
the URL property
if the resulting stream is seekable, the MediaDescriptor is an in-parameter and the stream isn't a return
value, close it when you are done with it
54
if the stream is not seekable, it is a "one way read" stream and must not be added to the MediaDescriptor.
If it gets a MediaDescriptor parameter for storing content the workflow is:
only if none of these properties is available, try to create a stream by yourself from other properties, e.g.
the URL property
if the resulting stream isn't seekable, a temporary stream must be created for the storing process and after
successful storing all content must be copied to the target stream.
Methods that get the MediaDescriptor as in-parameter only of course can't modify it.
It is not allowed to hold a member of this descriptor by reference longer than it is used. This is especially important for the
stream properties, except if the ownership of the stream is unquestionable. If it isn't, the stream can't be closed and only
releases its file by refcounting down to zero. So if you are in doubt whether your code is the owner of a stream that you have
passed to a MediaDescriptor, don't keep any reference to it outside of that descriptor.
URL Parameter
The URL is part of the media descriptor and also an explicit parameter for loadComponentFromURL().
This enables script code to load a document without creating a media descriptor at the cost of code
redundancy. The URL parameter of loadComponentFromURL() overrides a possible URL property passed
in the media descriptor. Aside from valid URLs that describe an existing file, the following URLs are used to
open viewable components in OpenOffice.org:
Component
URL
Writer
private:factory/swriter
Calc
private:factory/scalc
Draw
private:factory/sdraw
Impress
private:factory/simpress
.component:DB/QueryDesign
.component:DB/TableDesign
Database
.component:DB/RelationDesign
.component:DB/DataSourceBrowser
.component:DB/FormGridView
Bibliography .component:Bibliography/View1
55
Target Frame
The URL and media descriptor loadComponentFromURL() have two additional arguments, the target
frame name and search flags. The method loadComponentFromURL() looks for a frame in the frame
hierarchy and loads the component into the frame it finds. It uses the same algorithm as findFrame() at
the com.sun.star.frame.XFrame interface, described in section Frame Hierarchies.
The target frame name is a reserved name starting with an underscore or arbitrary name. The reserved
names denote frequently used frames in the frame hierarchy or special functions, whereas an arbitrary name
is searched recursively. If a reserved name is used, the search flags are ignored and set to 0. The following
reserved names are supported:
_self
Returns the frame itself. The same as with an empty target frame name. This means to search for a
frame you already have, but it is legal.
_top
Returns the top frame of the called frame .,The first frame where isTop() returns true when
traveling up the hierarchy. If the starting frame does not have a parent frame, the call is treated as a
search for "_self". This behavior is compatible to the frame targeting in a web browser.
_parent
Returns the next frame above in the frame hierarchy. If the starting frame does not have a parent
frame, the call is treated as a search for "_self". This behavior is compatible to the frame targeting
in a web browser.
_blank
Creates a new top-level frame as a child frame of the desktop. If the called frame is not part of the
desktop hierarchy, this call fails. Using the "_blank" target loads open documents again that result
in a read-only document, depending on the UCB content provider for the component. If loading is
done as a result of a user action, this becomes confusing to the users, therefore the "_default"
target is recommended in calls from a user interface, instead of "_blank". Refer to the next section
for a discussion about the _default target.
_default
Similar to "_blank", but the implementation defines further behavior that has to be documented by
the implementer. The com.sun.star.frame.XComponentLoader implemented at the desktop object
shows the following default behavior.
56
First, it checks if the component to load is already loaded in another top-level frame. If this is the
case, the frame is activated and brought to the foreground. When the OpenNewView property is set
to true in the media descriptor, the loader creates a second controller to show another view for the
loaded document. For components supporting this, a second window is opened as if the user clicked
Window - New Window. The other components are loaded one more time, as if the "_blank"
target had been used. Currently, almost all office components implementing
com.sun.star.frame.XModel have multiple controllers, except for HTML and writer documents in the
online view. The database and bibliography components have no model, therefore they cannot open
a second view at all and OpenNewView leads to an exception with them.
Next, the loader checks if the active frame contains an unmodified, empty document of the same
document type as the component that is being loaded. If so, the component is loaded into that frame,
replacing the empty document, otherwise a new top-level frame is created similar to a call with
"_blank".
Names starting with an underscore must not be used as real names for a frame.
If the given frame name is an arbitrary string, the loader searches for this frame in the frame hierarchy. The
search is done in the following order: self, children, siblings, parent, create if not found. Each of these search
steps can be skipped by deleting it from the com.sun.star.frame.FrameSearchFlag bit vector:
Constants in com.sun.star.frame.FrameSearchFlag group
SELF
SIBLINGS
PARENT
CREATE
TASKS
do not stop searching when a top frame is reached, but continue with other
top frames
ALL
GLOBAL
A typical case for a named frame is a situation where a frame is needed to be reused for subsequent loading
of components, for example, a frame attached to a preview window or a docked frame, such as the frame in
OpenOffice.org that opens the address book when the F4 key is pressed.
The frame names "_self", "_top" and "_parent" define a frame target relative to a starting frame. They
can only be used if the component loader interface finds the frame and the setComponent() can be used
with the frame. The desktop frame is the root, therefore it does not have a top and parent frame. The
57
component loader of the desktop cannot use these names, because the desktop refuses to have a
component set into it. However, if a frame implemented com.sun.star.frame.XComponentLoader, these
names could be used.
OpenOffice.org 1.0.x didn't have a frame implementation that supports
XComponentLoader.
The reserved frame names are also used as a targeting mechanism in the dispatch framework with regard to
as far as the relative frame names being resolved. For additional information, see chapter Using the
Dispatch Framework.
The example below creates a frame, and uses the target frame and search flag parameters of
loadComponentFromURL() to load a document into it.
//
//
//
//
//
//
//
//
58
loadComponentFromURL() call returns it. The database and bibliography components however, return a
controller, because they do not have a model.
Closing Documents
The loadComponentFromURL() returns a com.sun.star.lang.XComponent interface has previously been
discussed. The return value is a reference to a com.sun.star.lang.XComponent interface, the corresponding
object is a disposable component, and the caller must take care of lifetime problems. An XComponent
supports the following methods:
void dispose ()
void addEventListener ( [in] com::sun::star::lang::XEventListener xListener)
void removeEventListener ( [in] com::sun::star::lang::XEventListener
aListener)
In principle, there is a simple rule. The documentation of a com.sun.star.lang.XComponent specifies the
objects that can own a component. Normally, a client using an XComponent is the owner of the
XComponent and has the responsibility to dispose of it or it is not the owner. If it is not the owner, it may add
itself as a com.sun.star.lang.XEventListener at the XComponent and not call dispose() on it. This type of
XEventListener supports one method in which a component reacts upon the fact that another component
is about to be disposed of:
If the component is used briefly as a stack variable, you do not care about the component after loading, or
you are sure there will be no interference, it is justifiable to load the component without taking further
59
measures. If the user is going to close the component, let the reference go out of scope, or release the
reference when no longer required.
If a reference is used, but it is not necessary to react when it becomes invalid and the object supports
com.sun.star.uno.XWeak, you can hold a weak reference instead of a hard reference. Weak references
are automatically converted to null if the object they reference is going to be disposed. Because the
generic frame implementation, and also the controllers and models of all standard document types
implement XWeak, it is recommended to use it when possible.
If a hard reference is held or you want to know that the component has been closed and the new situation
has to be accommodated, add a com.sun.star.lang.XEventListener at the com.sun.star.lang.XComponent
interface. In this case, release the reference on a disposing() notification.
Sometimes it is necessary to exercise more control over the closing process, therefore a new, optional
interface com.sun.star.util.XCloseable has been introduced which is supported in versions beyond 641. If the
object you are referencing is a com.sun.star.util.XCloseable, register it as a com.sun.star.util.XCloseListener
and throw a com.sun.star.util.CloseVetoException when prompted to close. Since XCloseable is specified
as an optional interface for frames and models, do not assume that this interface is supported. It is possible
that the code runs with a OpenOffice.org version where frames and models do not implement XCloseable.
Therefore ,be prepared for the case when you receive null when you try to query XCloseable. The
XCloseable interface is described in more detail below.
The following three diagrams show the decisions to be made when closing a frame or a document model.
The important points are: if you expect modifications, you must either handle them using
com.sun.star.util.XModifiable and com.sun.star.frame.XStorable, or let the user do the necessary interaction
by calling suspend() on the controller. In any case, check if the frame or model is an XCloseable and
prefer com.sun.star.util.XCloseable:close() over a call to dispose(). The first two diagrams illustrate the
separate closing process for frames and models, the third diagram covers the actual termination of frames
and models.
60
Closing a Frame
Closing a Model
61
Terminate Frame/Model
XCloseable
The dispose mechanism has shortcomings in complex situations, such as the frame-controller-model
interaction. The dispose call cannot be rejected, but as shown above, sometimes it is necessary to prevent
destruction of objects due to shared ownership or a state of the documents that forbids destruction.
A closing mechanism is required that enables all involved objects to negotiate if deletion is possible and to
veto, if necessary. By offering the interface com.sun.star.util.XCloseable, a component tells it must be
destroyed by calling close(). Calling dispose() on an XCloseable might lead to deadlocks or crash the
entire application.
In OpenOffice.org, model or frame objects are possible candidates for implementing the interface
XCloseable, therefore query for that interface before destroying the object. Call dispose() directly if the
model or frame does not support the interface, thus declaring that it handles all the problems.
An object implementing XCloseable registers close listeners. When a close request is received, all
listeners are asked for permission. If a listener wants to deprecate, it throws an exception derived from
com.sun.star.util.CloseVetoException containing the reason why the component can not be closed. This
exception is passed to the close requester. The XCloseable itself can veto the destruction by throwing an
exception. If there is no veto, the XCloseable calls dispose() on itself and returns.
The XCloseable handles problems that occur if a component rejects destruction. A script programmer
usually can not cope with a component not used anymore and refuses to be destroyed. Ensure that the
component is destroyed to avoid a memory leak. The close() method offers a method to pass the
responsibility to close the object to any possible close listener that vetoes closing or to the XCloseable if
the initial caller is not able to stay in memory to try again later. This responsibility is referred to as delivered
ownership. The mechanism sets some constraints on the possible reasons for an objection against a close
request.
A close listener that is asked for permission can object for any reason if the close call does not force it to
assume ownership of the closeable object.The close requester is aware of a possible failure. If the close call
forces the ownership, the close listener must be careful. An objection is only allowed if the reason is
temporary. As soon as the reason no longer exists, the owner automatically calls close on the object that
should be closed, now being in the same situation as the initial close requester.
62
A permanent reason for objection is not allowed. For example,. the document is modified is not a valid
reason to object, because it is unlikely that the document becomes unmodified by itself. Consequently, it
could never be closed. Therefore, if an API programmer wants to avoid data loss, he must use the
com.sun.star.util.XModifiable and com.sun.star.frame.XStorable interfaces of the document. The fact that a
model refuses to be closed if it is modified is not dependable.
The interface com.sun.star.util.XCloseable inherits from com.sun.star.util.XCloseBroadcaster and has the
following methods:
No API exists for trivial components. As a consequence, components are not allowed to do anything that prevents them from
being destroyed. For example, since the office crashes when a container window or component window has an open modal
dialog, every component that wants to open a modal dialog must implement the com.sun.star.frame.XController interface.
If a model object supports XCloseable, calling dispose() on it is forbidden, try to close() the
XCloseable and catch a possible CloseVetoException. Components that cannot cope with a destroyed
model add a close listener at the model. This enables them to object when the model receives a close()
request. They also add as a close listener if they are not already added as an (dispose) event listener. This
can be done by every controller object that uses that model. It is also possible to let the model iterate
through its controllers and call their suspend() methods explicitly as a part of its implementation of the
close method. It is only necessary to know that a method close() must be called to close the model with its
controllers. The method the model chooses is an implementation detail.
The example below closes a loaded document component. It does not save modified documents or prompts
the user to save.
else
{
com.sun.star.lang.XComponent xDisposeable =
(com.sun.star.lang.XComponent)UnoRuntime.queryInterface(
com.sun.star.lang.XComponent.class,xModel);
xDisposeable.dispose();
}
catch(com.sun.star.beans.PropertyVetoException exModifyVeto)
{
}
}
}
}
Storing Documents
After loading an office component successfully, the returned interface cis used to manipulate the component.
Document specific interfaces, such as the interfaces com.sun.star.text.XTextDocument,
com.sun.star.sheet.XSpreadsheetDocument or com.sun.star.drawing.XDrawPagesSupplier are retrieved
using queryInterface().
If the office component supports the com.sun.star.frame.XStorable interface applying to every component
implementing the service com.sun.star.document.OfficeDocument, it can be stored:
void store ( )
void storeAsURL ( [in]
[in]
lArguments )
void storeToURL ( [in]
[in]
lArguments )
boolean hasLocation ()
string getLocation ()
boolean isReadonly ()
string sURL,
sequence< com::sun::star::beans::PropertyValue >
string sURL,
sequence< com::sun::star::beans::PropertyValue >
The XStorable offers the methods store(), storeAsURL() and storeToURL() for storing. The latter
two methods are called with a media descriptor.
The method store() overwrites an existing file. Calling this method on a document that was created from
scratch using a private:factory/... URL leads to an exception.
65
The other two methods storeAsURL() and storeToURL() leave the original file untouched and differ
after the storing procedure. The storeToURL() method saves the current document to the desired location
without touching the internal state of the document. The method storeAsURL sets the Modified attribute
of the document, accessible through its com.sun.star.util.XModifiable interface, to false and updates the
internal media descriptor of the document with the parameters passed in the call. This changes the
document URL.
The following example exports a Writer document, Writer/Web document or Calc sheet to HTML.
// Conditions: sURL
= "file:///home/target.htm"
//
xDocument = m_xLoadedDocument
// Export can be achieved by saving the document and using
// a special filter which can write the desired format.
// Normally this filter should be searched inside the filter
// configuration (using service com.sun.star.document.FilterFactory)
// but here we use well known filter names directly.
String sFilter = null;
// Detect document type by asking XServiceInfo
com.sun.star.lang.XServiceInfo xInfo =
(com.sun.star.lang.XServiceInfo)UnoRuntime.queryInterface (
com.sun.star.lang.XServiceInfo.class, xDocument);
// Determine suitable HTML filter name for export.
if(xInfo!=null)
{
if(xInfo.supportsService ("com.sun.star.text.TextDocument") == true)
sFilter = new String("HTML (StarWriter)");
else
if(xInfo.supportsService ("com.sun.star.text.WebDocument") == true)
sFilter = new String("HTML");
else
if(xInfo.supportsService ("com.sun.star.sheet.SpreadsheetDocument") == true)
sFilter = new String("HTML (StarCalc)");
}
if(sFilter!=null)
{
// Build necessary argument list for store properties.
// Use flag "Overwrite" to prevent exceptions, if file already exists.
com.sun.star.beans.PropertyValue[] lProperties =
new com.sun.star.beans.PropertyValue[2];
lProperties[0]
= new com.sun.star.beans.PropertyValue();
lProperties[0].Name = "FilterName";
lProperties[0].Value = sFilter;
lProperties[1]
= new com.sun.star.beans.PropertyValue();
lProperties[1].Name = "Overwrite";
lProperties[1].Value = new Boolean(true);
com.sun.star.frame.XStorable xStore =
(com.sun.star.frame.XStorable)UnoRuntime.queryInterface (
com.sun.star.frame.XStorable.class, xDocument);
xStore.storeAsURL (sURL, lProperties);
66
}
If a model is loaded or stored successfully, all parts of the media descriptor not explicitly excluded according
to the media descriptor table in section MediaDescriptor must be provided by the methods getURL() and
getArgs() in the com.sun.star.frame.XModel interface. The separation of the URL and the other
arguments is used, because the URL is the often the most wanted part for itsperformance optimized access.
The XModel offers a method attachResource() that changes the media descriptor of the document, but this method
should only be used in special cases, for example, by the implementer of a new document model and controller. The method
attachResource() does not force reloading of the document. Validation checks are done when a document is loaded
through MediaDescriptor. For example, if the resource is write protected, add
Readonly to the
MediaDescriptor and the filter name must match the data. A possible use for attachResource() could be
creating a document from a template, where after loading successfully, the document's resource is changed to an "unnamed"
state by deleting the URL.
Printing Documents
Printing revolves around the interface com.sun.star.view.XPrintable. Its methods and special printing
features for the various document types are described in the document chapters Printing Text Documents,
Printing Spreadsheet Documents, Printing Drawing Documents and Printing Presentation Documents.
67
mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl);
// retrieve the Desktop object, we need its XComponentLoader
Object desktop = mxRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", mxRemoteContext);
XComponentLoader xComponentLoader =
(XComponentLoader)UnoRuntime.queryInterface(
XComponentLoader.class, desktop);
// define load properties according to
com.sun.star.document.MediaDescriptor
// the boolean property AsTemplate tells the office to create a new
document
// from the given file
PropertyValue[] loadProps = new PropertyValue[1];
loadProps[0] = new PropertyValue();
loadProps[0].Name = "AsTemplate";
loadProps[0].Value = new Boolean(true);
// load
return xComponentLoader.loadComponentFromURL(loadUrl, "_blank", 0,
loadProps);
}
Now that we are able to load a text document as template, we will open an existing template file that
contains five text fields and a bookmark. We want to demonstrate how to insert text at predefined positions in
a document.
Text fields and bookmarks are supplied by the appropriate XTextFieldsSupplier and
XBookmarksSupplier interfaces. Their fully qualified names are com.sun.star.text.XTextFieldsSupplier
and com.sun.star.text.XBookmarksSupplier.
The XTextFieldsSupplier provides collections of text fields in our text. We use document variable fields
for our purpose, which are com.sun.star.text.textfield.User services. All User fields have a field master that
holds the actual content of the variable. Therefore, the TextFields collection, as well as the
FieldMasters are required for our example. We get the field masters for the five fields by name and set
their Content property. Finally, we refresh the text fields so that they reflect the changes made to the field
masters.
The XBookmarksSupplier returns all bookmarks in our document. The collection of bookmarks is a
com.sun.star.container.XNameAccess, so that the bookmarks are retrieved by name. Every object in a text
supports the interface XTextContent that has a method getAnchor(). The anchor is the text range an
object takes up, so getAnchor() retrieves is an XTextRange. From the chapter First Steps, a
com.sun.star.text.XTextRange allows setting the string of a text range. Our bookmark is a text content and
therefore must support XTextContent. Inserting text at a bookmark position is straightforward: get the
anchor of the bookmark and set its string.
70
XRefreshable.class, xEnumeratedFields);
xRefreshable.refresh();
// accessing the Bookmarks collection of the document
XNameAccess xNamedBookmarks = xBookmarksSupplier.getBookmarks();
// find the bookmark named "Subscription"
Object bookmark = xNamedBookmarks.getByName("Subscription");
// we need its XTextRange which is available from getAnchor(),
// so query for XTextContent
XTextContent xBookmarkContent = (XTextContent)UnoRuntime.queryInterface(
XTextContent.class, bookmark);
// get the anchor of the bookmark (its XTextRange)
XTextRange xBookmarkRange = xBookmarkContent.getAnchor();
// set string at the bookmark position
xBookmarkRange.setString("subscription for the Manatee Journal");
72
view cursor for its Text service, then we have the Text service create a model cursor based on the current
cursor position. The model cursor knows where the paragraph ends, so we go there and insert a string.
/** Sample for document changes, starting at the current view cursor position
The sample changes the paragraph style and the character style at the
current
view cursor selection
Open the sample file ViewCursorExampleFile, select some text and run the
example
The current paragraph will be set to Quotations paragraph style
The selected text will be set to Quotation character style
*/
private void viewCursorExample() throws java.lang.Exception {
// get the remote service manager
mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl);
// get the Desktop service
Object desktop = mxRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", mxRemoteContext);
// query its XDesktop interface, we need the current component
XDesktop xDesktop = (XDesktop)UnoRuntime.queryInterface(
XDesktop.class, desktop);
// retrieve the current component and access the controller
XComponent xCurrentComponent = xDesktop.getCurrentComponent();
// get the XModel interface from the component
XModel xModel = (XModel)UnoRuntime.queryInterface(XModel.class,
xCurrentComponent);
// the model knows its controller
XController xController = xModel.getCurrentController();
// the controller gives us the TextViewCursor
// query the viewcursor supplier interface
XTextViewCursorSupplier xViewCursorSupplier =
(XTextViewCursorSupplier)UnoRuntime.queryInterface(
XTextViewCursorSupplier.class, xController);
// get the cursor
XTextViewCursor xViewCursor = xViewCursorSupplier.getViewCursor();
// query its XPropertySet interface, we want to set character and paragraph
properties
XPropertySet xCursorPropertySet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xViewCursor);
// set the appropriate properties for character and paragraph style
xCursorPropertySet.setPropertyValue("CharStyleName", "Quotation");
xCursorPropertySet.setPropertyValue("ParaStyleName", "Quotations");
73
// print the current page number - we need the XPageCursor interface for
this
XPageCursor xPageCursor = (XPageCursor)UnoRuntime.queryInterface(
XPageCursor.class, xViewCursor);
System.out.println("The current page number is " + xPageCursor.getPage());
// the model cursor is much more powerful, so
// we create a model cursor at the current view cursor position with the
following steps:
// we get the Text service from the TextViewCursor, the cursor is an
XTextRange and has
// therefore a method getText()
XText xDocumentText = xViewCursor.getText();
// the text creates a model cursor from the viewcursor
XTextCursor xModelCursor =
xDocumentText.createTextCursorByRange(xViewCursor.getStart());
// now we could query XWordCursor, XSentenceCursor and XParagraphCursor
// or XDocumentInsertable, XSortable or XContentEnumerationAccess
// and work with the properties of com.sun.star.text.TextCursor
// in this case we just go to the end of the paragraph and add some text.
XParagraphCursor xParagraphCursor =
(XParagraphCursor)UnoRuntime.queryInterface(
XParagraphCursor.class, xModelCursor);
// goto the end of the paragraph
xParagraphCursor.gotoEndOfParagraph(false);
xParagraphCursor.setString(" ***** Fin de semana! ******");
}
boolean hasLocation()
string getLocation()
boolean isReadonly()
void store()
void storeAsURL( [in] string aURL, sequence<
com::sun::star::beans::PropertyValue > aArgs)
void storeToURL( [in] string aURL, sequence<
com::sun::star::beans::PropertyValue > aArgs)
74
The method names are evident. The method storeAsUrl() is the exact representation of File - Save
As,that is, it changes the current document location. In contrast, storeToUrl() stores a copy to a new
location, but leaves the current document URL untouched.
Exporting
For exporting purposes, a filter name can be passed to storeAsURL() and storeToURL() that triggers an
export to other file formats. The property needed for this purpose is the string argument FilterName that
takes filter names defined in the configuration file:
<OfficePath>\share\config\registry\instance\org\openoffice\Office\TypeDetection.
xml
In TypeDetection.xml, look for <Filter/> elements, their cfg:name attribute contains the needed strings
for FilterName. The proper filter name for StarWriter 5.x is "StarWriter 5.0", and the export format "MS
Word 97" is also popular. This is the element in TypeDetection.xml that describes the MS Word 97 filter:
75
Name
PaperOrientation
PaperFormat
com.sun.star.view.PaperFormat. Specifies a predefined paper size or if the paper size is a user-defined size.
PaperSize
IsBusy
CanSetPaperOrientation
CanSetPaperFormat
76
CanSetPaperSize
Properties of com.sun.star.view.PrintOptions
CopyCount
FileName
Collate
Pages
boolean - Advises the printer to collate the pages of the copies. If true, a whole document is printed prior to the next
copy, otherwise the page copies are completed together.
string - Specifies the pages to print in the same format as in the print dialog of the GUI (e.g. "1, 3, 4-7, 9-")
boolean - Advises that the print job should be performed synchronously, i.e. wait until printing is complete before
Wait
returning from printing. Otherwise return is immediate and following actions (e.g. closing the corresponding model) may fail
until printing is complete. Default is false.
The following method uses PrinterDescriptor and PrintOptions to print to a special printer, and
preselect the pages to print.
PageRows
short - Number of rows in which document pages should appear on the output page.
PageColumns
short - Number of columns in which document pages should appear on the output page.
LeftMargin
RightMargin
TopMargin
BottomMargin
HoriMargin
VertMargin
IsLandscape
The method printPages() prints the document according to the previous settings. The argument for the
printPages() method may contain the PrintOptions as described in the section above (containing the
properties CopyCount, FileName, Collate and Pages).
78
Editing Text
As previously discussed in the introductory chapter First Steps, the interface com.sun.star.text.XText
incorporates three interfaces: XText, XSimpleText and XTextRange. When working with an XText, you
work with the string it contains, or you insert and remove contents other than strings, such as tables, text
fields, and graphics.
Strings
The XText is handled as a whole. There are two possibilities if the text is handled as one string. The
complete string can be set at once, or strings can be added at the beginning or end of the existing text.
These are the appropriate methods used for that purpose:
79
}
Beginning and end of a text can be determined calling getStart() and getEnd():
com::sun::star::text::XTextRange getStart()
com::sun::star::text::XTextRange getEnd()
The following example adds text using the start and end range of a text:
com::sun::star::text::XTextCursor createTextCursor()
com::sun::star::text::XTextCursor createTextCursorByRange (
com::sun::star::text::XTextRange aTextPosition)
The text cursor travels through the text as a "collapsed" text range with identical start and end as a point in
text, or it can expand while it moves to contain a target string. This is controlled with the methods of the
XTextCursor interface:
void collapseToStart()
void collapseToEnd()
boolean isCollapsed()
In writer, a text cursor has three interfaces that inherit from XTextCursor: com.sun.star.text.XWordCursor,
com.sun.star.text.XSentenceCursor and com.sun.star.text.XParagraphCursor. These interfaces introduce
the following additional movements and status checks:
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
Since XTextCursor inherits from XTextRange, a cursor is an XTextRange and incorporates the methods
of an XTextRange:
com::sun::star::text::XText getText()
com::sun::star::text::XTextRange getStart()
com::sun::star::text::XTextRange getEnd()
string getString()
void setString( [in] string aString)
The cursor can be told where it is required and the string content can be set later. This does have a
drawback. After setting the string, the inserted string is always selected. That means further text can not be
added without moving the cursor again. Therefore the most flexible method to insert strings by means of a
cursor is the method insertString() in XText. It takes an XTextRange as the target range that is
replaced during insertion, a string to insert, and a boolean parameter that determines if the inserted text
should be absorbed by the cursor after it has been inserted. The XTextRange could be any XTextRange.
The XTextCursor is an XTextRange, so it is used here:
81
e.printStackTrace(System.out);
}
}
AnchorTypes A sequence of com.sun.star.text.TextContentAnchorType that contains all allowed anchor types for the object.
TextWrap
Determines the way the surrounding text flows around the object, according to com.sun.star.text.WrapTextMode.
The method dispose() of the XComponent interface deletes the object from the document. Since a text
content is an XComponent, com.sun.star.lang.XEventListener can be added or removed with the methods
addEventListener() and removeEventListener(). These methods are called back when the object
is disposed. Other events are not supported.
The method getAnchor() at the XTextContent interface returns a text range which reflects the text
position where the object is located. This method may return a void object, for example, for text frames that
are bound to a page. The method getAnchor() is used in situations where an XTextRange is required.
For instance, placeholder fields (com.sun.star.text.textfield.JumpEdit) can be filled out using their
getAnchor() method. Also, you can get a bookmark, retrieve its XTextRange from getAnchor() and
use it to insert a string at the bookmark position.
The method attach() is an intended method to attach text contents to the document, but it is currently not
implemented.
All text contents - including paragraphs - can be created by the service manager of the document. They are
created using the factory methods createInstance() or createInstanceWithArguments() at the
com.sun.star.lang.XMultiServiceFactory interface of the document.
All text contents - except for paragraphs - can be inserted into text using the com.sun.star.text.XText method
insertTextContent(). They can be removed by calling removeTextContent(). Starting with the
83
section Tables, there are code samples showing the usage of the document service manager with
insertTextContent().
Control Characters
We have used Java escape sequences for paragraph breaks, but this may not be feasible in every language.
Moreover, OpenOffice.org supports a number of control characters that can be used. There are two
possibilities: use the method
0x000D).
LINE_BREAK
HARD_HYPHEN
A character that appears like a dash, but prevents hyphenation at its position ( UNICODE
SOFT_HYPHEN
HARD_SPACE
A character that appears like a space, but prevents hyphenation at this point ( UNICODE
0x000A).
0x2011).
0x00AD).
0x00A0).
84
Bookmark
IsCollapsed
IsStart
boolean - Determines whether the portion is a start portion if two portions are needed to include an object, that is,
DocumentIndexMark.
Description
"Text"
"TextField"
A com.sun.star.text.TextField content.
"TextContent"
"Footnote"
A footnote or an endnote.
"ControlCharacter"
A control character.
"ReferenceMark"
A reference mark.
"DocumentIndexMark"
"Bookmark"
A bookmark.
"Redline"
"Ruby"
The text portion enumeration of a paragraph does not supply contents which do belong to the paragraph, but
do not fuse together with the text flow. These could be text frames, graphic objects, embedded objects or
drawing shapes anchored at the paragraph, characters or as character. The TextPortionType
"TextContent" indicate if there is a content anchored at a character or as a character. If you have a
TextContent portion type, you know that there are shape objects anchored at a character or as a
character.
85
This last group of data contained in a text, Paragraphs and TextPortions in writer support the interface
com.sun.star.container.XContentEnumerationAccess. This interface tells which text contents other than the
text flow contents exist, and supplies them as an com.sun.star.container.XEnumeration:
The enumeration access to text through paragraphs and text portions is used if every single paragraph in a
text needs to be touched. The application area for this enumeration are export filters, that uses this
enumeration to go over the whole document, writing out the paragraphs to the target file. The following code
snippet centers all paragraphs in a text.
Sorting Text
It is possible to sort text or the content of text tables.
Sorting of text is done by the text cursor that supports com.sun.star.util.XSortable. It contains two methods:
87
Auto Text
The auto text function can be used to organize reusable text passages. They allow storing text, including the
formatting and all other contents in a text block collection to apply them later. Three services deal with auto
text in OpenOffice.org:
88
89
The current implementation forces the user to close the AutoTextEntry instance when they are changed,
so that the changes can take effect. However, the new AutoText is not written to disk until the destructor of
the AutoTextEntry instance inside the writer is called. When this example has finished executing, the file
on disk correctly contains the complete text "This string was inserted using the API!\n\nSome
text for a new autotext block", but there is no way in Java to call the destructor. It is not clear
when the garbage collector deletes the object and writes the modifications to disk.
Formatting
A multitude of character, paragraph and other properties are available for text in OpenOffice.org. However,
the objects implemented in the writer do not provide properties that support
com.sun.star.beans.XPropertyChangeListener or com.sun.star.beans.XVetoableChangeListener yet.
Character and paragraph properties are available in the following services:
Services supporting Character and
Paragraph Properties
com.sun.star.text.TextCursor
Remark
If collapsed, the CharacterProperties refer to the position on the right hand side of
the cursor.
com.sun.star.text.Paragraph
com.sun.star.text.TextPortion
com.sun.star.text.TextTableCursor
com.sun.star.text.Shape
com.sun.star.table.CellRange
In text tables.
com.sun.star.text.TextDocument
The model offers a selected number of character properties which apply to the entire
document. These are: CharFontName, CharFontStyleName,
CharFontFamily, CharFontCharSet, CharFontPitch and their Asian
counterparts CharFontStyleNameAsian, CharFontFamilyAsian,
CharFontCharSetAsian, CharFontPitchAsian.
string - This property specifies the name of the font in western text.
CharFontStyleName
CharFontFamily
short - This property contains font family that is specified in com.sun.star.awt.FontFamily. Possible
values are: DONTKNOW, DECORATIVE, MODERN, ROMAN, SCRIPT, SWISS, and SYSTEM.
short - This property contains the text encoding of the font that is specified in com.sun.star.awt.CharSet.
CharFontCharSet
90
Possible values are: DONTKNOW, ANSI MAC, IBMPC_437, IBMPC_850, IBMPC_860, IBMPC_861,
IBMPC_863, IBMPC_865, and SYSTEM SYMBOL.
short - This property contains the font pitch that is specified in com.sun.star.awt.FontPitch. The word font
CharFontPitch
CharColor
pitch refers to characters per inch, but the possible values are DONTKNOW, FIXED and VARIABLE.
VARIABLE points to the difference between proportional and unproportional fonts.
long - This property contains the value of the text color in ARGB notation. ARGB has four bytes denoting
alpha, red, green and blue. In hex notation, this can be used conveniently: 0xAARRGGBB. The AA
(Alpha) can be 00 or left out.
CharEscapement
CharHeight
[optional] short - Property which contains the relative value of the character height in
subscription or superscription.
CharUnderline
CharWeight
CharPosture
CharAutoKerning
com.sun.star.awt.FontUnderline. A lot of underline types are available. Some possible values are SINGLE,
DOUBLE, and DOTTED.
float - This property contains the value of the font weight, cf. [com.sun.star.awt.FontWeight. A lot of
weights are possible. The common ones are BOLD and NORMAL.
long - This property contains the posture of the font as defined in com.sun.star.awt.FontSlant. The most
common values are ITALIC and NONE.
[optional] boolean - Property to determine whether the kerning tables from the current font are
used.
CharBackColor
[optional] long - Property which contains the text background color in ARGB:
0xAARRGGBB.
CharBackTransparent
CharCaseMap
formatting and displaying. Possible CaseMaps are NONE, UPPERCASE, LOWERCASE, TITLE, and
SMALLCAPS as defined in the constants group com.sun.star.style.CaseMap. (optional)
CharCrossedOut
[optional] boolean - This property is true if the characters are crossed out.
CharFlash
[optional] boolean - If this optional property is true , then the characters are flashing
[optional] short - Determines the type of the strikethrough of the character as defined in
CharStrikeout
CharWordMode
com.sun.star.awt.FontStrikeout. Values are NONE, SINGLE, DOUBLE, DONTKNOW, BOLD, and SLASH
X.
[optional] boolean - If this property is true , the underline and strike-through properties are not
applied to white spaces.
CharKerning
[optional] short - Property which contains the value of the kerning of the characters.
CharLocale
struct com.sun.star.lang.Locale. Contains the locale (language and country) of the characters.
CharKeepTogether
CharNoLineBreak
CharShadowed
CharFontType
[optional] boolean - Property which marks a range of characters to prevent it from being broken
into two lines.
[optional] boolean - Property which marks a range of characters to ignore a line break in this
area.
[optional] boolean - True if the characters are formatted and displayed with a shadow effect.
(optional)
[optional] short - Property which specifies the fundamental technology of the font as specified in
com.sun.star.awt.FontType. Possible values are DONTKNOW, RASTER, DEVICE, and SCALABLE.
CharStyleName
CharContoured
[optional] boolean - True if the characters are formatted and displayed with a contour effect.
CharCombineIsOn
CharCombinePrefix
CharCombineSuffix
[optional] string - Contains the prefix string (usually parenthesis) before text that is formatted in
two lines.
[optional] string - Contains the suffix string (usually parenthesis) after text that is formatted in
two lines.
CharEmphasis
CharRelief
RubyText
RubyAdjust
RubyCharStyleName
RubyIsAbove
CharRotation
CharRotationIsFitToLine
[optional] string - Contains the name of the character style that is applied to RubyText
(optional).
[optional] boolean - Determines whether the ruby text is printed above/left or below/right of the
text (optional) .
CharScaleWidth
HyperLinkURL
HyperLinkTarget
[optional] string - contains the name of the target for a hyperlink if the target is set.
HyperLinkName
[optional] string - contains the name of the hyperlink if the name is set.
VisitedCharStyleName
[optional] string - Contains the character style name for visited hyperlinks.
UnvisitedCharStyleName
[optional] string - Contains the character style name for unvisited hyperlinks.
CharEscapementHeight
[optional] byte - This is the additional height used for subscript or superscript characters in units
of percent. For subscript characters the value is negative and for superscript characters positive.
CharNoHyphenation
CharUnderlineColor
CharUnderlineHasColor
CharStyleNames
[optional] sequence<string> - specifies the names of the all styles applied to the font.
CharHidden
TextUserDefinedAttributes
[optional] XNameContainer - This property stores xml attributes. They will be saved to and restored
from automatic styles inside xml files.
CharWeightAsian
CharFontNameAsian
CharFontStyleNameAsian
CharFontFamilyAsian
short - This property contains the font family that is specified in com.sun.star.awt.FontFamily.
CharFontCharSetAsian
short - This property contains the text encoding of the font that is specified in com.sun.star.awt.CharSet.
CharFontPitchAsian
short - This property contains the font pitch that is specified in com.sun.star.awt.FontPitch.
CharPostureAsian
long - This property contains the value of the posture of the font as defined in com.sun.star.awt.FontSlant.
CharLocaleAsian
92
ParaLineSpacing
ParaBackColor
ParaBackTransparent
[optional] boolean - This value is true if the paragraph background color is set to transparent.
ParaBackGraphicURL
[optional] string - Contains the value of a link for the background graphic of a paragraph.
ParaBackGraphicFilter
ParaBackGraphicLocation
[optional] string - Contains the name of the graphic filter for the background graphic of a
paragraph.
[optional] long - Contains the value for the position of a background graphic according to
com.sun.star.style.GraphicLocation.
ParaLastLineAdjust
ParaExpandSingleWord
ParaLeftMargin
ParaRightMargin
ParaTopMargin
ParaBottomMargin
ParaLineNumberCount
ParaLineNumberStartValue
[optional] boolean - Contains the start value for the line numbering.
ParaIsHyphenation
PageDescName
PageNumberOffset
[optional] string - If this property is set, it creates a page break before the paragraph it
belongs to and assigns the value as the name of the new page style sheet to use.
[optional] short - If a page break property is set at a paragraph, this property contains the new
value for the page number.
PageStyleName
ParaRegisterModeActive
ParaTabStops
ParaStyleName
DropCapFormat
DropCapWholeWord
ParaKeepTogether
ParaSplit
[optional] boolean - Specifies if the property DropCapFormat is applied to the whole first
word.
[optional] boolean - Setting this property to true prevents page or column breaks between this
and the following paragraph.
[optional] boolean - Setting this property to false prevents the paragraph from getting split into
two pages or columns.
NumberingLevel
NumberingRules
NumberingStartValue
ParaIsNumberingRestart
NumberingStyleName
[optional] short - Specifies the start value for numbering if a new numbering starts at this
paragraph.
[optional] boolean - Determines if the numbering rules restart, counting at the current
paragraph.
[optional] string - Specifies the name of the style for the numbering.
93
ParaOrphans
ParaWidows
ParaShadowFormat
ParaIsHangingPunctuation
ParaIsCharacterDistance
ParaIsForbiddenRules
[optional] byte - Specifies the minimum number of lines of the paragraph that have to be at
bottom of a page if the paragraph is spread over more than one page.
[optional] byte - Specifies the minimum number of lines of the paragraph that have to be at top
of a page if the paragraph is spread over more than one page.
[optional] struct com.sun.star.table.ShadowFormat. Determines the type, color, and size of the
shadow.
[optional] boolean - Determines if the the rules for forbidden characters at the start or end of
text lines are considered.
[optional] boolean - Determines if the the rules for forbidden characters at the start or end of
text lines are considered.
/** This snippet shows the necessary steps to set a property at the
current position of a given text cursor mxDocCursor
*/
// query the XPropertySet interface
XPropertySet xCursorProps = (XPropertySet)
UnoRuntime.queryInterface(XPropertySet.class, mxDocCursor);
// call setPropertyValue, passing in a Float object
xCursorProps.setPropertyValue("CharWeight", new Float (
com.sun.star.awt.FontWeight.BOLD));
The same procedure is used for all properties. The more complex properties are described here.
If a change of the page style is required the paragraph property PageDescName has to be set using an
existing page style name. This forces a page break at the cursor position and the new inserted page uses
the requested page style. The property PageNumberOffset has to be set to start with a new page count. If
inserting an additional paragraph should be avoided, the cursor must be placed at the beginning of the first
paragraph before inserting it.
If a page break (or a column break) without a change in the used style is required, the property BreakType
is set using the values of com.sun.star.style.BreakType:
Page
break
94
Description
Page or column break as described in com.sun.star.style.BreakType. Possible values are NONE, COLUMN_BEFORE,
BreakType COLUMN_AFTER, COLUMN_BOTH, PAGE_BEFORE, PAGE_AFTER, and PAGE_BOTH. Setting the property forces a
page or column break at the current text cursor position, paragraph or text table.
The property ParaLineNumberCount is used to include a paragraph in the line numbering. The setting of
the line numbering options is done using the property set provided by the
com.sun.star.text.XLineNumberingProperties interface implemented at the text document model.
To create a hyperlink these properties are set at the current cursor position or the current
[IDL:com.sun.star.text.Paragraph] service.
[BUG641+]Hyperlink properties are not specified for paragraphs in the API reference.
Hyperlink Properties
Description
HyperLinkURL
HyperLinkTarget
string - Contains the name of the target frame and can be left blank.
HyperLinkName
UnvisitedCharStyleName string - The names of the character styles used to emphasize visited or not visited links. If
left blank, the default character styles Internet Link/Visited Internet Link are applied automatically.
VisitedCharStyleName
HyperLinkEvents
Events attached to the hyperlink. The names of the events are OnClick, OnMouseOver, and
OnMouseOut. Each returned event is a sequence of com.sun.star.beans.PropertyValue, with
three elements named EventType, MacroName and Library. All elements contain string values.
The EventType contains the value "StarBasic" for [PRODUCTNAME] Basic macros . The macro
name contains the path to the macro, for example, Standard.Module1.Main. The library contains
the name of the library.
Some properties are connected with each other. There may be side effects or dependencies between the
following properties:
Interdependencies between Properties
95
Navigating
Cursors
The text model cursor allows for free navigation over the model by character, words, sentences, or
paragraphs. There can be several model cursors at the same time. Model cursor creation, movement and
usage is discussed in the section Word Processing . The text model cursors are
com.sun.star.text.TextCursor services that are based on the interface com.sun.star.text.XTextCursor, which
is based on com.sun.star.text.XTextRange.
The text view cursor enables the user to travel over the document in the view by character, line, screen page
and document page. There is only one text view cursor. Certain information about the current layout, such as
the number of lines and page number must be retrieved at the view cursor. The chapter Text Document
Controller below discusses the view cursor in detail. The text view cursor is a
com.sun.star.text.TextViewCursor service that includes com.sun.star.text.TextLayoutCursor.
Methods
XTextTablesSupplier
com.sun.star.container.XNameAccess getTextTables()
XTextFramesSupplier
com.sun.star.container.XNameAccess getTextFrames()
XTextGraphicObjectsSupplier
com.sun.star.container.XNameAccess getGraphicObjects()
XTextEmbeddedObjectsSupplier
com.sun.star.container.XNameAccess getEmbeddedObjects()
com.sun.star.container.XEnumerationAccess getTextFields()
XTextFieldsSupplier
com.sun.star.container.XNameAccess getTextFieldMasters()
XBookmarksSupplier
com.sun.star.container.XNameAccess getBookmarks()
XReferenceMarksSupplier
com.sun.star.container.XNameAccess getReferenceMarks()
XFootnotesSupplier
com.sun.star.container.XIndexAccess getFootnotes()
com.sun.star.beans.XPropertySet getFootnoteSettings()
96
com.sun.star.container.XIndexAccess getEndnotes()
XEndnotesSupplier
com.sun.star.beans.XPropertySet getEndnoteSettings()
XTextSectionsSupplier
com.sun.star.container.XNameAccess getTextSections()
XDocumentIndexesSupplier
com.sun.star.container.XIndexAccess getDocumentIndexes()
XRedlinesSupplier
com.sun.star.container.XEnumerationAccess getRedlines()
You can work with text content directly, set properties and use its interfaces, or find out where it is and do an
action at the text content location in the text. To find out where a text content is located call the
getAnchor() method at the interface com.sun.star.text.XTextContent, which every text content must
support.
In addition, text contents located at the current text cursor position or the content where the cursor is
currently located are provided in the PropertySet of the cursor. The corresponding cursor properties are:
DocumentIndexMark
TextField
ReferenceMark
Footnote
Endnote
DocumentIndex
TextTable
TextFrame
Cell
TextSection
com::sun::star::util::XSearchDescriptor createSearchDescriptor()
com::sun::star::util::XReplaceDescriptor createReplaceDescriptor()
com::sun::star::uno::XInterface findFirst( [in]
com::sun::star::util::XSearchDescriptor xDesc)
com::sun::star::uno::XInterface findNext( [in] com::sun::star::uno::XInterface
xStartAt,
[in]
com::sun::star::util::XSearchDescriptor xDesc)
com::sun::star::container::XIndexAccess findAll( [in]
com::sun::star::util::XSearchDescriptor xDesc)
97
98
XPropertyReplace
The interface com.sun.star.util.XPropertyReplace is required to describe your search. It is a powerful
interface and inherits from XReplaceDescriptor, XSearchDescriptor and XPropertySet.
The target of your search is described by a string containing a search text or a style name using
setSearchString(). Correspondingly, provide the text string or style name that should replace the found
occurrence of the search target to the XReplaceDescriptor using setReplaceString(). Refine the
search mode through the properties included in the service com.sun.star.util.SearchDescriptor:
99
Properties of com.sun.star.util.SearchDescriptor
SearchBackwards
SearchCaseSensitive
SearchRegularExpression
SearchSimilarity
SearchSimilarityAdd
SearchSimilarityExchange
short - Determines the number of characters the word in the document may be longer than the search
string for it to remain valid.
short - Determines how many characters in the search term can be exchanged.
boolean - If true, the values of added, exchanged, and removed characters are combined The search
SearchSimilarityRelax
SearchSimilarityRemove
SearchStyles
SearchWords
term is then found if the word in the document can be generated through any combination of these three
conditions.
short - Determines how many characters the word in the document may be shorter than the search
string for it to remain valid. The characters may be removed from the word at any position.
boolean - Determines if the search and replace string should be interpreted as paragraph style names.
Note that the Display Name of the style has to be used.
In XPropertyReplace, the methods to get and set search attributes, and replace attributes allow the
attributes to search for to be defined and the attributes to insert instead of the existing attributes. All of these
methods expect a sequence of com.sun.star.beans.PropertyValue structs.
Any properties contained in the services com.sun.star.style.CharacterProperties,
com.sun.star.style.CharacterPropertiesAsian and com.sun.star.style.ParagraphProperties can be used for an
attribute search. If setValueSearch(false) is used, OpenOffice.org checks if an attribute exists,
whereas setValueSearch(true) finds specific attribute values. If only searching to see if an attribute
exists at all, it is sufficient to pass a PropertyValue struct with the Name field set to the name of the
required attribute.
The following code snippet replaces all occurrences of the text "random numbers" by the bold text "replaced
numbers" in a given document mxDoc.
xRepDesc.setReplaceString("replaced numbers");
// create an array of one property value for a CharWeight property
PropertyValue[] aReplaceArgs = new PropertyValue[1];
// create PropertyValue struct
aReplaceArgs[0] = new PropertyValue();
// CharWeight should be bold
aReplaceArgs[0].Name = "CharWeight";
aReplaceArgs[0].Value = new Float(com.sun.star.awt.FontWeight.BOLD);
// set our sequence with one property value as ReplaceAttribute
XPropertyReplace xPropRepl = (XPropertyReplace) UnoRuntime.queryInterface(
XPropertyReplace.class, xRepDesc);
xPropRepl.setReplaceAttributes(aReplaceArgs);
// replace
long nResult = xReplaceable.replaceAll(xRepDesc);
Tables
Table Architecture
OpenOffice.org text tables consist of rows, rows consist of one or more cells, and cells can contain text or
rows. There is no logical concept of columns. From the API's perspective, a table acts as if it had columns,
as long as there are no split or merged cells.
Cells in a row are counted alphabetically starting from A, where rows are counted numerically, starting from
1. This results in a cell-row addressing pattern, where the cell letter is denoted first (A-Zff.), followed by the
row number (1ff.):
A1 B1 C1 D1
A2 B2 C2 D2
A3 B3 C3 D3
A4 B4 C4 D4
When a cell is split vertically, the new cell gets the letter of the former right-hand-side neighbor cell and the
former neighbor cell gets the next letter in the alphabet. Consider the example table below: B2 was split
vertically, a new cell C2 is inserted and the former C2 became D2, D2 became E2, and so forth.
101
When cells are merged vertically, the resulting cell counts as one cell and gets one letter. The neighbor cell
to the right gets the subsequent letter. B4 in the table below shows this. The former B4 and C4 have been
merged, so the former D4 could become C4. The cell name D4 is no longer required.
As shown, there is no way to address a column C anymore, for the cells C1 to C4 no longer form a column:
A1 B1
C1 D1
C3 D3
A4 B4 merged with C4
C4
When cells are split horizontally, OpenOffice.org simply inserts as many rows into the cell as required.
In our example table, we continued by splitting C2 first horizontally and then vertically so that there is a range
of four cells.
The writer treats the content of C2 as two rows and starts counting cells within rows. To address the new
cells, it extends the original cell name C2 by new addresses following the cell-row pattern. The upper row
gets row number 1 and the first cell in the row gets cell number 1, resulting in the cell address C2.1.1, where
the latter 1 indicates the row and the former 1 indicates the first cell in the row. The right neighbor of C2.1.1
is C2.2.1. The subaddress 2.1 means the second cell in the first row.
A1 B1
C1 D1
C2.1.1 C2.2.1
D2 E2
C2.1.2 C2.2.2
A3 B3
C3 D3
A4 B4 merged with C4
C4
The cell-row pattern is used for all further subaddressing as the cells are split and merged. The cell
addresses can change radically depending on the table structure generated by OpenOffice.org. The next
table shows what happens when E2 is merged with D3. The table is reorganized, so that it has three rows
instead of four. The second row contains two cells, A2 and B2 (sic!). The cell A2 has two rows, as shown
from the cell subaddresses: The upper row consists of four cells, namely A2.1.1 through A2.4.1, whereas the
lower row consists of the three cells A2.1.2 through A2.3.2.
The cell range C2.1.1:C2.2.2 that was formerly contained in cell C2 is now in cell A2.3.1 that denotes the
third cell in the first row of A2. Within the address of the cell A2.3.1, OpenOffice.org has started a new
subaddressing level using the cell-row pattern again.
A1
102
B1
C1
D1
A2.3.1.1.1 A2.3.1.2.1
A2.1.1 A2.2.1
A2.4.1
A2.3.1.1.2 A2.3.1.2.2
A2.1.2 A2.2.2
A3
Former E2 merged
with former D3
A2.3.2
B3
Becomes B2!
C3
Cell addresses can become complicated. The cell address can be looked up in the user interface. Set the
GUI text cursor in the desired cell and observe the lower-right corner of the status bar in the text document.
Remember that there are only "columns" in a text table, as long as there are no split or merged cells.
Text tables support the service com.sun.star.text.TextTable, which includes the service
com.sun.star.text.TextContent:
Service com.sun.star.text.TextTable
The service com.sun.star.text.TextTable offers access to table cells in two different ways::
103
Yields named table cells which are organized in rows and columns.
Provides a table cursor to travel through the table cells and alter the cell properties.
These aspects are reflected in the interface com.sun.star.text.XTextTable which inherits from
com.sun.star.text.XTextContent. It can be seen as a rectangular range of cells defined by numeric column
indexes, as described by com.sun.star.table.XCellRange. This aspect makes text tables compatible with
spreadsheet tables. Also, text tables have a name, can be sorted, charts can be based on them, and
predefined formats can be applied to the tables. The latter aspects are covered by the interfaces
com.sun.star.container.XNamed, com.sun.star.util.XSortable, com.sun.star.chart.XChartDataArray and
com.sun.star.table.XAutoFormattable.
The usage of these interfaces and the properties of the TextTable service are discussed below.
The interface XTextTable introduces the following methods to initialize a table, work with table cells, rows
and columns, and create a table cursor:
104
The method getRows() returns a table row container supporting com.sun.star.table.XTableRows that is a
com.sun.star.container.XIndexAccess, and introduces the following methods to insert an arbitrary number of
table rows below a given row index position and remove rows from a certain position:
hasElements()
getByIndex()
getCount()
insertByIndex()
removeByIndex()
Every row returned by getRows() supports the service com.sun.star.text.TextTableRow, that is, it is a
com.sun.star.beans.XPropertySet which features these properties:
Properties of com.sun.star.text.TextTableRow
BackColor
BackTransparent
[1]
BackGraphicFilter
BackGraphicLocation
TableColumnSeparators
Defines the column width and its merging behavior. It contains a sequence of
com.sun.star.text.TableColumnSeparator structs with the fields Position and IsVisible. The value of Position is
relative to the table property com.sun.star.text.TextTable:TableColumnRelativeSum. IsVisible refers to
merged cells where the separator becomes invisible.
Height
IsAutoHeight
boolean - If the value of this property is true, the height of the table row depends on the content of the
table cells.
The method getColumns() is similar to getRows(), but restrictions apply. It returns a table column
container supporting com.sun.star.table.XTableColumns that is a com.sun.star.container.XIndexAccess and
introduces the following methods to insert an arbitrary number of table columns behind a given column index
position and remove columns from a certain position:
In Simple Table
X
In Complex Table
X
105
hasElements()
getByIndex()
getCount()
insertByIndex()
removeByIndex()
The method createCursorByCellName() creates a text table cursor that can select a cell range in the
table, merge or split cells, and read and write cell properties of the selected cell range. It is a
com.sun.star.text.TextTableCursor service with the interfaces com.sun.star.text.XTextTableCursor and
com.sun.star.beans.XPropertySet.
com.sun.star.text.TextTableCursor
These are the methods contained in XTextTableCursor:
string getRangeName()
boolean
boolean
boolean
boolean
106
107
BackGraphicFilter
string - Contains the name of the file filter for the background graphic.
BackGraphicLocation
BackGraphicURL
BackTransparent
BottomMargin
BreakType
com.sun.star.style.BreakType. Determines the type of break that is applied at the beginning of the table.
ChartColumnAsLabel
ChartRowAsLabel
boolean - Determines if the first column of the table should be treated as axis labels when a chart is to
be created.
boolean - Determines if the first row of the table should be treated as axis labels when a chart is to be
created.
HoriOrient
IsWidthRelative
KeepTogether
LeftMargin
108
boolean - Setting this property to true prevents page or column breaks between this table and the
following paragraph or text table.
PageDescName
PageNumberOffset
string - If this property is set, it creates a page break before the table and assigns the value as the
name of the new page style sheet to use.
short - If a page break property is set at the table, this property contains the new value for the page
number.
RelativeWidth
RepeatHeadline
boolean - Determines if the first row of the table is repeated on every new page.
RightMargin
ShadowFormat
struct com.sun.star.table.ShadowFormat determines the type, color and size of the shadow.
Split
boolean - Setting this property to false prevents the table from getting spread on two pages.
TableBorder
TableColumnRelativeSum
short - Contains the sum of the column width values used in TableColumnSeparators.
sequence < com.sun.star.text.TableColumnSeparator >. Defines the column width and its merging
TableColumnSeparators
TopMargin
Width
Inserting Tables
To create and insert a new text table, a five-step procedure must be followed:
1. Get the service manager of the text document, querying the document's factory interface
com.sun.star.lang.XMultiServiceFactory.
2. Order a new text table from the factory by its service name "com.sun.star.text.TextTable", using
the factory method createInstance().
3. From the object received, query the com.sun.star.text.XTextTable interface that inherits from
com.sun.star.text.XTextContent.
4. If necessary, initialize the table with the number of rows and columns. For this purpose, XTextTable
offers the initialize() method.
5. Insert the table into the text using the insertTextContent() method at its com.sun.star.text.XText
interface. The method insertTextContent() expects an XTextContent to insert. Since
XTextTable inherits from XTextContent, pass the XTextTable interface retrieved previously.
You are now ready to get cells, fill in text, values and formulas and set the table and cell properties as
needed.
In the following code sample, there is a small helper function to put random numbers between -1000 and
1000 into the table to demonstrate formulas:
109
/** This method returns a random double which isn't too high or too low
*/
protected double getRandomDouble()
{
return ((maRandom.nextInt() % 1000) * maRandom.nextDouble());
}
The following helper function inserts a string into a cell known by its name and sets its text color to white:
/** This method sets the text colour of the cell refered to by sCellName to
white and inserts
the string sText in it
*/
public static void insertIntoCell(String sCellName, String sText, XTextTable
xTable) {
// Access the XText interface of the cell referred to by sCellName
XText xCellText = (XText) UnoRuntime.queryInterface(
XText.class, xTable.getCellByName(sCellName));
// create a text cursor from the cells XText interface
XTextCursor xCellCursor = xCellText.createTextCursor();
// Get the property set of the cell's TextCursor
XPropertySet xCellCursorProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xCellCursor);
try {
// Set the colour of the text to white
xCellCursorProps.setPropertyValue("CharColor", new Integer(16777215));
} catch (Exception e) {
e.printStackTrace(System.out);
}
// Set the text in the cell to sText
xCellText.setString(sText);
}
Using the above helper functions, create a text table and insert it into the text document.
/** This method shows how to create and insert a text table, as well as insert
text and formulae
into the cells of the table
*/
protected void TextTableExample ()
{
try
{
// Create a new table from the document's factory
XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
XTextTable.class, mxDocFactory .createInstance(
"com.sun.star.text.TextTable" ) );
110
"A1",
"B1",
"C1",
"D1",
of each
);
);
);
}
catch (Exception e)
{
e.printStackTrace ( System.out );
}
}
The next sample inserts auto text entries into a table, splitting cells during its course.
112
{
// Generate a random, positive number which is lower than
// the number of autotext groups
int nRandom = Math.abs ( maRandom.nextInt() %
aGroupNames.length );
// Get the autotext group at this name
xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (
XAutoTextGroup.class, xContainer.getByName (
aGroupNames[ nRandom ] ) );
// Fill our string array with the names of all the blocks in
this
// group
aBlockNames = xGroup.getElementNames();
// increment our depth counter
++nDepth;
}
while ( nDepth < 200 && aBlockNames.length == 0 );
// If we managed to find a group containg blocks...
if ( aBlockNames.length > 0 )
{
// Pick a random block in this group and get it's
// XAutoTextEntry interface
int nRandom = Math.abs ( maRandom.nextInt()
% aBlockNames.length );
XAutoTextEntry xEntry = ( XAutoTextEntry )
UnoRuntime.queryInterface (
XAutoTextEntry.class, xGroup.getByName (
aBlockNames[ nRandom ] ) );
// insert the modified autotext block at the end of the
document
xEntry.applyTo ( mxDocCursor );
// Get the titles of all text blocks in this AutoText group
String [] aBlockTitles = xGroup.getTitles();
// Get the XNamed interface of the autotext group
XNamed xGroupNamed = ( XNamed ) UnoRuntime.queryInterface (
XNamed.class, xGroup );
// Output the short cut and title of the random block
//and the name of the group it's from
System.out.println ( "Inserted the Autotext '" +
aBlockTitles[nRandom]
+ "', shortcut '" + aBlockNames[nRandom] + "' from group '"
+ xGroupNamed.getName() );
}
}
// Go to the end of the document
mxDocCursor.gotoEnd( false );
115
import
import
import
import
com.sun.star.text.XTextTablesSupplier;
com.sun.star.container.XNameAccess;
com.sun.star.container.XIndexAccess;
com.sun.star.beans.XPropertySet;
...
// first query the XTextTablesSupplier interface from our document
XTextTablesSupplier xTablesSupplier = (XTextTablesSupplier)
UnoRuntime.queryInterface(
XTextTablesSupplier.class, mxDoc );
// get the tables collection
XNameAccess xNamedTables = xTablesSupplier.getTextTables();
// now query the XIndexAccess from the tables collection
116
117
Text Fields
Text fields are text contents that add a second level of information to text ranges. Usually their appearance
fuses together with the surrounding text, but actually the presented text comes from elsewhere. Field
commands can insert the current date, page number, total page numbers, a cross-reference to another area
of text, the content of certain database fields, and many variables, such as fields with changing values, into
the document. There are some fields that contain their own data, where others get the data from an attached
field master.
Description
com.sun.star.text.textfield.Annotation
com.sun.star.text.textfield.Author
com.sun.star.text.textfield.Bibliography
Identifier=ABC99
118
BibliographicType=1
The names of the fields are defined in com.sun.star.text.BibliographyDataField. A
bibliographic entry depends on com.sun.star.text.fieldmaster.Bibliography
com.sun.star.text.textfield.Chapter
com.sun.star.text.textfield.CharacterCount
com.sun.star.text.textfield.CombinedCharacters
Combines up to six characters as one text object that is formatted in two lines.
com.sun.star.text.textfield.ConditionalText
com.sun.star.text.textfield.Database
The form letter field showing the content from a database. Depends on
com.sun.star.text.fieldmaster.Database.
com.sun.star.text.textfield.DatabaseName
com.sun.star.text.textfield.DatabaseNextSet
com.sun.star.text.textfield.DatabaseNumberOfSet
com.sun.star.text.textfield.DatabaseSetNumber
com.sun.star.text.textfield.DateTime
com.sun.star.text.textfield.DDE
com.sun.star.text.textfield.docinfo.ChangeAuthor
Shows the name of the author of the last change of the document.
com.sun.star.text.textfield.docinfo.ChangeDateTime Shows the date and time of the last change of the document.
com.sun.star.text.textfield.docinfo.CreateAuthor
com.sun.star.text.textfield.docinfo.CreateDateTime
com.sun.star.text.textfield.docinfo.Custom
com.sun.star.text.textfield.docinfo.Description
com.sun.star.text.textfield.docinfo.EditTime
com.sun.star.text.textfield.docinfo.Info0
Shows the content of the first user defined info field of the document info. This
service has been removed in OOo 3.0; use
com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info1
Shows the content of the second user defined info field of the document info. This
service has been removed in OOo 3.0; use
com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info2
Shows the content of the third user defined info field of the document info. This
service has been removed in OOo 3.0; use
com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info3
Shows the content of the fourth user defined info field of the document info. This
service has been removed in OOo 3.0; use
com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Keywords
com.sun.star.text.textfield.docinfo.PrintAuthor
com.sun.star.text.textfield.docinfo.PrintDateTime
com.sun.star.text.textfield.docinfo.Revision
com.sun.star.text.textfield.docinfo.Subject
com.sun.star.text.textfield.docinfo.Title
com.sun.star.text.textfield.EmbeddedObjectCount
com.sun.star.text.textfield.ExtendedUser
com.sun.star.text.textfield.FileName
com.sun.star.text.textfield.GetExpression
Variables - Show Variable. Shows the value set by the previous occurrence of
SetExpression.
com.sun.star.text.textfield.GetReference
com.sun.star.text.textfield.GraphicObjectCount
com.sun.star.text.textfield.HiddenParagraph
com.sun.star.text.textfield.HiddenText
com.sun.star.text.textfield.Input
The field activates a dialog to input a value that changes a related User field or
SetExpression<code> field.
com.sun.star.text.textfield.InputUser
The field activates a dialog to input a string that is displayed by the field. This field
is not connected to variables.
com.sun.star.text.textfield.JumpEdit
A placeholder field with an attached interaction to insert text, a text table, text
frame, graphic object or an OLE object.
com.sun.star.text.textfield.Macro
com.sun.star.text.textfield.PageCount
com.sun.star.text.textfield.PageNumber
com.sun.star.text.textfield.ParagraphCount
com.sun.star.text.textfield.ReferencePageGet
Displays the page number with respect to the reference point, that is determined
by the text field ReferencePageSet.
com.sun.star.text.textfield.ReferencePageSet
Inserts a starting point for additional page numbers that can be switched on or off.
com.sun.star.text.textfield.Script
com.sun.star.text.textfield.SetExpression
Variables - Set Variable. A variable field. The value is valid until the next
occurrence of <code>SetExpression field. The actual value depends on
com.sun.star.text.fieldmaster.SetExpression.
com.sun.star.text.textfield.TableCount
com.sun.star.text.textfield.TableFormula
com.sun.star.text.textfield.TemplateName
Shows the name of the template the current document is created from.
com.sun.star.text.textfield.User
com.sun.star.text.textfield.WordCount
Date and time fields are set to the current date and time.
The ExtendedUser fields that show parts of the user data set for OpenOffice.org, such as the Name, City,
Phone No. and the Author fields that are set to the current values.
The FileName fields are updated with the current name of the file.
The DocInfo.XXX fields are updated with the current document info of the document.
All other fields ignore calls to update().
Some of these fields need a field master that provides the data that appears in the field. This applies to the
field types Database, SetExpression, DDE, User and Bibliography. The interface
com.sun.star.text.XDependentTextField handles these pairs of FieldMasters and TextFields. The method
120
attachTextFieldMaster() must be called prior to inserting the field into the document. The method
getTextFieldMaster() does not work unless the dependent field is inserted into the document.
To create a valid text field master, the instance has to be created using the
com.sun.star.lang.XMultiServiceFactory interface of the model with the appropriate service name:
Text Field Master Service Names
Description
com.sun.star.text.fieldmaster.User
Contains the global variable that is created and displayed by the fieldtype
com.sun.star.text.textfield.User.
com.sun.star.text.fieldmaster.DDE
com.sun.star.text.fieldmaster.SetExpression
com.sun.star.text.fieldmaster.Database
com.sun.star.text.fieldmaster.Bibliography
The property Name has to be set after the field instance is created, except for the Database field master
type where the properties DatabaseName, DatabaseTableName, DataColumnName and
DatabaseCommandType are set instead of the Name property.
To access existing text fields and field masters, use the interface com.sun.star.text.XTextFieldsSupplier that
is implemented at the text document model.
Its method getTextFields() returns a com.sun.star.text.TextFields container which is a
com.sun.star.container.XEnumerationAccess and can be refreshed through the refresh() method in its
interface com.sun.star.util.XRefreshable.
Its method getTextFieldMasters() returns a com.sun.star.text.TextFieldMasters container holding the
text field masters of the document. This container provides a com.sun.star.container.XNameAccess
interface. All field masters, except for Database are named by the service name followed by the name of
the field master. The Database field masters create their names by appending the DatabaseName,
DataTableName and DataColumnName to the service name.
Consider the following examples for this naming convention:
"com.sun.star.text.fieldmaster.SetExpression.Illustration"
"com.sun.star.text.fieldmaster.User.Company"
"com.sun.star.text.fieldmaster.Database.Bibliography.biblio.Identifier"
Each text field master has a property InstanceName that contains its name in the format of the related
container.
Some SetExpression text field masters are always available if they are not deleted. These are the
masters with the names Text, Illustration, Table and Drawing. They are predefined as number range field
masters used for captions of text frames, graphics, text tables and drawings. Note that these predefined
names are internal names that are usually not used at the user interface.
The following methods show how to create and insert text fields.
121
/** This method inserts both a date field and a user field containing the
number '42'
*/
protected void TextFieldExample() {
try {
// Use the text document's factory to create a DateTime text field,
// and access it's
// XTextField interface
XTextField xDateField = (XTextField) UnoRuntime.queryInterface(
XTextField.class, mxDocFactory.createInstance(
"com.sun.star.text.textfield.DateTime"));
// Insert it at the end of the document
mxDocText.insertTextContent ( mxDocText.getEnd(), xDateField, false );
// Use the text document's factory to create a user text field,
// and access it's XDependentTextField interface
XDependentTextField xUserField = (XDependentTextField)
UnoRuntime.queryInterface (
XDependentTextField.class, mxDocFactory.createInstance(
"com.sun.star.text.textfield.User"));
// Create a fieldmaster for our newly created User Text field, and
access it's
// XPropertySet interface
XPropertySet xMasterPropSet = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, mxDocFactory.createInstance(
"com.sun.star.text.fieldmaster.User"));
// Set the name and value of the FieldMaster
xMasterPropSet.setPropertyValue ("Name", "UserEmperor");
xMasterPropSet.setPropertyValue ("Value", new Integer(42));
// Attach the field master to the user field
xUserField.attachTextFieldMaster (xMasterPropSet);
// Move the cursor to the end of the document
mxDocCursor.gotoEnd(false);
// insert a paragraph break using the XSimpleText interface
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
// Insert the user field at the end of the document
mxDocText.insertTextContent(mxDocText.getEnd(), xUserField, false);
} catch (Exception e) {
e.printStackTrace (System.out);
}
}
122
Description
CharacterStyles
Character styles are used to format single characters or entire words and phrases. Character styles can be nested.
ParagraphStyles
Paragraph styles are used to format entire paragraphs. Apart from the normal format settings for paragraphs, the
paragraph style also defines the font to be used, and the paragraph style for the following paragraph.
FrameStyles
Frame styles are used to format graphic and text frames. These Styles are used to quickly format graphics and
frames automatically.
PageStyles
Page styles are used to structure the page. If a "Next Style" is specified, the OpenOffice.org automatically applies the
specified page style when an automatic page break occurs.
NumberingStyles Numbering styles are used to format paragraphs in numbered or bulleted text.
string getName()
void setName( [in] string aName)
boolean isUserDefined()
boolean isInUse()
string getParentStyle()
void setParentStyle( [in] string aParentStyle)
The office comes with a set of default styles. These styles use programmatic names on the API level. The
method setName() in XStyle always throws an exception if called at such styles. The same applies to
123
changing the property Category. At the user interface localized names are used. The user interface names
are provided through the property UserInterfaceName.
Note that page and numbering styles are not hierarchical and cannot have parent styles. The method
getParentStyle() always returns an empty string, and the method setParentStyle() throws a
com.sun.star.uno.RuntimeException when called at a default style.
The method isUserDefined() determines whether a style is defined by a user or is a built-in style. A builtin style cannot be deleted. Additionally the built-in styles have two different names: a true object name and
an alias that is displayed at the user interface. This is not usually visible in an English OpenOffice.org
version, except for the default styles that are named "Standard" as programmatic name and "Default" in the
user interface.
The Style service defines the following properties which are shared by all styles:
Properties of com.sun.star.style.Style
IsPhysical
FollowStyle
[optional] boolean - Contains the name of the style that is applied to the next paragraph.
DisplayName
IsAutoUpdate
ParaStyleConditions
[optional, readonly] string - Contains the name of the style as is displayed in the user
interface.
[optional] string - Determines if a style is automatically updated when the properties of an object that
the style is applied to are changed.
[optional, property] sequence< NamedValue > - Defines the context and styles for conditional
paragraphs. This property is only available if the style is a conditional paragraph style.
To determine the user interface name, each style has a string property DisplayName that contains the
name that is used at the user interface. It is not allowed to use a DisplayName of a style as a name of a
user-defined style of the same style family.
The built-in styles are not created actually as long as they are not used in the document. The property
IsPhysical checks for this. It is necessary, for file export purposes, to detect styles which do not need to
be exported.
Conditional paragraph styles are handled by the property ParaStyleConditions. The sequence consists of
pairs where the name part (the first part) of the pair defines the context where the style (the second part, a
string that denotes a style name or an empty string) should be applied to. Assigning an empty string to the
style name will disable the conditional style for that context.
The StyleFamilies collection can load styles. For this purpose, the interface
com.sun.star.style.XStyleLoader is available at the StyleFamilies collection. It consists of two methods:
124
Description
LoadTextStyles
Determines if character and paragraph styles are to be imported. It is not possible to select
character styles and paragraph styles separately.
LoadFrameStyles
LoadPageStyles
LoadNumberingStyles
OverwriteStyles
boolean - Determines if internal styles are overwritten if the source document contains styles
having the same name.
Character Styles
Character styles support all properties defined in the services com.sun.star.style.CharacterProperties and
com.sun.star.style.CharacterPropertiesAsian.
They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model
using the service name "com.sun.star.style.CharacterStyle".
The default style that is shown in the user interface and accessible through the API is not a style, but a tool
to remove applied character styles. Therefore, its properties cannot be changed.
Set the property CharStyleName at an object including the service com.sun.star.style.CharacterProperties
to set its character style.
Paragraph Styles
Paragraph styles support all properties defined in the services com.sun.star.style.ParagraphProperties and
com.sun.star.style.ParagraphPropertiesAsian.
They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model
using the service name "com.sun.star.style.ParagraphStyle".
Additionally, there is a service com.sun.star.style.ConditionalParagraphStyle which creates conditional
paragraph styles. Conditional styles are paragraph styles that have different effects, depending on the
context. There is currently no support of the condition properties at the API.
125
Frame Styles
Frame styles support all properties defined in the services com.sun.star.text.BaseFrameProperties.
The frame styles are applied to text frames, graphic objects and embedded objects.
They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model
using the service name "com.sun.star.style.FrameStyle".
Set the property FrameStyleName at com.sun.star.text.BaseFrame objects to set their frame style.
Page Styles
Page styles are controlled via properties. The page related properties are defined in the services
com.sun.star.style.PageStyle
They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model
using the service name "com.sun.star.style.PageStyle".
As mentioned above, page styles are not hierarchical. The section Page Layout discusses page styles.
The PageStyle is set at the current text cursor position by setting the property PageDescName to an
existing page style name.This will insert a new page that uses the new page style. If no new page should be
inserted, the cursor has to be at the beginning of the first paragraph.
Numbering Styles
Numbering styles support all properties defined in the services com.sun.star.text.NumberingStyle.
They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model
using the service name "com.sun.star.style.NumberingStyle".
The structure of the numbering rules is described in section Line Numbering and Outline Numbering.
The name of the numbering style is set in the property NumberingStyleName of paragraphs (set through
the PropertySet of a TextCursor) or a paragraph style to apply the numbering to the paragraphs.
The following example demonstrates the use of paragraph styles:
/** This method demonstrates how to create, insert and apply styles
*/
protected void StylesExample() {
try {
// Go to the end of the document
mxDocCursor.gotoEnd(false);
// Insert two paragraph breaks
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
mxDocText.insertControlCharacter(
126
xParaCursor.gotoNextParagraph(true);
// And reset it's style to 'Standard' (the programmatic name for the
default style)
xCursorProps.setPropertyValue("ParaStyleName", "Standard");
} catch (Exception e) {
e.printStackTrace (System.out);
}
}
Settings
General Document Information
Text documents offer general information about the document through their
com.sun.star.document.XDocumentInfoSupplier interface. The DocumentInfo is a common OpenOffice.org
feature and is discussed in Office Development.
The XDocumentInfoSupplier has one single method:
com::sun::star::document::XDocumentInfo getDocumentInfo()
which returns a com.sun.star.document.DocumentInfo service, offering the statistical information about the
document that is available through File - Properties in the GUI.
Document Properties
The model implements a com.sun.star.beans.XPropertySet that provides properties concerning character
formatting and general settings.
The properties for character attributes are CharFontName, CharFontStyleName, CharFontFamily,
CharFontCharSet, CharFontPitch and their Asian counterparts CharFontStyleNameAsian,
CharFontFamilyAsian, CharFontCharSetAsian, CharFontPitchAsian.
The following properties handle general settings:
Properties of com.sun.star.text.TextDocument
CharLocale
CharacterCount
128
ParagraphCount
WordCount
WordSeparator
string - Contains all that characters that are treated as separators between words to determine word
count.
RedlineDisplayType
RecordChanges
ShowChanges
RedlineProtectionKey
ForbiddenCharacters
com.sun.star.i18n.ForbiddenCharacters. Contains characters that are not allowed to be at the first or last
character of a text line.
TwoDigitYear
short - Determines the start of the range, for example, when entering a two-digit year.
IndexAutoMarkFileURL
string - The URL to the file that contains the search words and settings of the automatic marking of index
marks for alphabetical indexes.
AutomaticControlFocus
boolean - If true, the first form object is selected when the document is loaded.
ApplyFormDesignMode
HideFieldTips
boolean - If true, the automatic tips displayed for some types of text fields are suppressed.
129
com::sun::star::container::XIndexReplace getChapterNumberingRules()
at the com.sun.star.text.XChapterNumberingSupplier interface that is implemented at the document model.
These objects provide an interface com.sun.star.container.XIndexReplace. Each element of the container
represents a numbering level. The writer document provides ten numbering levels. The highest level is zero.
Each level of the container consists of a sequence of com.sun.star.beans.PropertyValue.
The two related objects differ in some of properties they provide.
Both of them provide the following properties:
Common Properties for Paragraph and Outline Numbering in com.sun.star.text.NumberingLevel
Adjust
ParentNumbering
short - Determines if higher numbering levels are included in the numbering, for example, 2.3.1.2.
Prefix
string - Contains strings that surround the numbering symbol, for example, brackets.
Suffix
CharStyleName
string - Name of the character style that is applied to the number symbol.
StartWith
short - Determines the value the numbering starts with. The default is one.
FirstLineOffset
long - Influences the left indent and left margin of the numbering.
LeftMargin
SymbolTextDistance
[optional] long - Distance between the numbering symbol and the text of the paragraph.
NumberingType
130
Description
BulletChar
BulletFontName
GraphicURL
string - Determines the type, size and orientation of a graphic when the
numbering type is set to NumberingType::BITMAP.
GraphicBitmap
Undocumented
GraphicSize
Undocumented
VertOrient
HeadingStyleName
Description
string - Contains the name of the paragraph style that marks a paragraph
as a chapter heading.
Note that the NumberingRules service is returned by value like most properties in the OpenOffice.org API, therefore you must
get the rules from the XPropertySet, change them and put the NumberingRules object back into the property.
/** This method demonstrates how to set numbering types and numbering levels
using the
com.sun.star.text.NumberingRules service
*/
protected void NumberingExample() {
try {
// Go to the end of the document
mxDocCursor.gotoEnd(false);
// Get the RelativeTextContentInsert interface of the document
XRelativeTextContentInsert xRelative = (XRelativeTextContentInsert)
UnoRuntime.queryInterface(XRelativeTextContentInsert.class,
mxDocText);
131
break;
case 2 : aProps[j].Value = new
Short(NumberingType.ARABIC);
break;
}
// Put the updated PropertyValue sequence back into the
// NumberingRules service
xReplace.replaceByIndex (i, aProps);
break;
}
}
}
// Get the XParagraphCursor interface of our text cursro
XParagraphCursor xParaCursor = (XParagraphCursor)
UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor);
// Go to the end of the document, then select the preceding paragraphs
mxDocCursor.gotoEnd(false);
xParaCursor.gotoPreviousParagraph false);
xParaCursor.gotoPreviousParagraph true);
xParaCursor.gotoPreviousParagraph true);
// Get the XPropertySet of the cursor's currently selected text
XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, mxDocCursor);
// Set the updated Numbering rules to the cursor's property set
xCursorProps.setPropertyValue ("NumberingRules", xNum);
mxDocCursor.gotoEnd(false);
// Set the first paragraph that was inserted to a numbering level of 2
(thus it will
// have Arabic style numbering)
xParas[0].setPropertyValue ("NumberingLevel", new Short ((short) 2));
// Set the second paragraph that was inserted to a numbering level of 1
(thus it will
// have 'Chars Upper Letter' style numbering)
xParas[1].setPropertyValue ("NumberingLevel", new Short((short) 1));
// Set the third paragraph that was inserted to a numbering level of 0
(thus it will
// have 'Chars Upper Letter' style numbering)
xParas[2].setPropertyValue("NumberingLevel", new Short((short) 0));
} catch (Exception e) {
e.printStackTrace (System.out);
}
}
133
Line Numbering
The text document model supports the interface com.sun.star.text.XLineNumberingProperties. The provided
object has the properties described in the service com.sun.star.text.LineNumberingProperties. It is used in
conjunction with the paragraph properties ParaLineNumberCount and ParaLineNumberStartValue.
Number Formats
The text document model provides access to the number formatter through aggregation, that is, it provides
the interface com.sun.star.util.XNumberFormatsSupplier seamlessly.
The number formatter is used to format numerical values. For details, refer to Number Formats.
In text, text fields with numeric content and table cells provide a property NumberFormat that contains a
long value that refers to a number format.
Text Sections
A text section is a range of complete paragraphs that can have its own format settings and source location,
separate from the surrounding text. Text sections can be nested in a hierarchical structure.
For example, a section is formatted to have text columns that different column settings in a text on a
paragraph by paragraph basis. The content of a section can be linked through file links or over a DDE
connection.
The text sections support the service com.sun.star.text.TextSection. To access the sections, the text
document model implements the interface com.sun.star.text.XTextSectionsSupplier that provides an
interface com.sun.star.container.XNameAccess . The returned objects support the interface
com.sun.star.container.XIndexAccess, as well.
Master documents implement the structure of sub documents using linked text sections.
An example demonstrating the creation, insertion and linking of text sections:
/** This method demonstrates how to create linked and unlinked sections
*/
protected void TextSectionExample() {
try {
// Go to the end of the document
mxDocCursor.gotoEnd(false);
// Insert two paragraph breaks
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, true);
134
// Create a new TextSection from the document factory and access it's
XNamed interface
XNamed xChildNamed = (XNamed) UnoRuntime.queryInterface(
XNamed.class,
mxDocFactory.createInstance("com.sun.star.text.TextSection"));
// Set the new sections name to 'Child_Section'
xChildNamed.setName("Child_Section");
// Access the Child_Section's XTextContent interface and insert it into
the document
XTextContent xChildSection = (XTextContent) UnoRuntime.queryInterface(
XTextContent.class, xChildNamed);
mxDocText.insertTextContent (mxDocCursor, xChildSection, false);
// Access the XParagraphCursor interface of our text cursor
XParagraphCursor xParaCursor = (XParagraphCursor)
UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor);
// Go back one paragraph (into Child_Section)
xParaCursor.gotoPreviousParagraph(false);
// Insert a string into the Child_Section
mxDocText.insertString(mxDocCursor, "This is a test", false);
// Go to the end of the document
mxDocCursor.gotoEnd(false);
// Go back two paragraphs
xParaCursor.gotoPreviousParagraph (false);
xParaCursor.gotoPreviousParagraph (false);
// Go to the end of the document, selecting the two paragraphs
mxDocCursor.gotoEnd(true);
// Create another text section and access it's XNamed interface
XNamed xParentNamed = (XNamed) UnoRuntime.queryInterface(XNamed.class,
mxDocFactory.createInstance("com.sun.star.text.TextSection"));
// Set this text section's name to Parent_Section
xParentNamed.setName ("Parent_Section");
// Access the Parent_Section's XTextContent interface ...
XTextContent xParentSection = (XTextContent) UnoRuntime.queryInterface(
XTextContent.class, xParentNamed);
// ...and insert it into the document
mxDocText.insertTextContent(mxDocCursor, xParentSection, false);
// Go to the end of the document
mxDocCursor.gotoEnd (false);
// Insert a new paragraph
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
135
136
Page Layout
A page layout in OpenOffice.org is always a page style. A page can not be hard formatted. To change the
current page layout, retrieve the current page style from the text cursor property PageStyleName and get
this page style from the StyleFamily PageStyles.
Changes of the page layout happen through the properties described in com.sun.star.style.PageProperties.
Refer to the API reference for details on all the possible properties, including the header and footer texts
which are part of these properties.
As headers or footers are connected to a page style, the text objects are provided as properties of the style.
Depending on the setting of the page layout, there is one header and footer text object per style available or
there are two, a left and right header, and footer text:
com.sun.star.style.PageProperties
containing Headers and Footers
Description
HeaderText
com.sun.star.text.Text
HeaderTextLeft
com.sun.star.text.Text
HeaderTextRight
com.sun.star.text.Text
FooterText
com.sun.star.text.Text
FooterTextLeft
com.sun.star.text.Text
FooterTextRight
com.sun.star.text.Text
The page layout of a page style can be equal on left and right pages, mirrored, or separate for right and left
pages. This is controlled by the property PageStyleLayout that expects values from the enum
com.sun.star.style.PageStyleLayout. As long as left and right pages are equal, HeaderText and
HeaderRightText are identical. The same applies to the footers.
The text objects in headers and footers are only available if headers or footers are switched on, using the
properties HeaderIsOn and FooterIsOn.
Drawing objects cannot be inserted into headers or footers
Columns
Text frames, text sections and page styles can be formatted to have columns. The width of columns is
relative since the absolute width of the object is unknown in the model. The layout formatting is responsible
for calculating the actual widths of the columns.
137
Columns are applied using the property TextColumns. It expects a com.sun.star.text.TextColumns service
that has to be created by the document factory. The interface com.sun.star.text.XTextColumns refines the
characteristics of the text columns before applying the created TextColumns service to the property
TextColumns.
Consider the following example to see how to work with text columns:
/** This method demonstrates the XTextColumns interface and how to insert a
blank paragraph
using the XRelativeTextContentInsert interface
*/
protected void TextColumnsExample() {
try {
// Go to the end of the doucment
mxDocCursor.gotoEnd(false);
// insert a new paragraph
mxDocText.insertControlCharacter(mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false);
// insert the string 'I am a fish.' 100 times
for (int i = 0 ; i < 100 ; ++i) {
mxDocText.insertString(mxDocCursor, "I am a fish.", false);
}
// insert a paragraph break after the text
mxDocText.insertControlCharacter(mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false);
// Get the XParagraphCursor interface of our text cursor
XParagraphCursor xParaCursor = (XParagraphCursor)
UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor);
// Jump back before all the text we just inserted
xParaCursor.gotoPreviousParagraph(false);
xParaCursor.gotoPreviousParagraph(false);
// Insert a string at the beginning of the block of text
mxDocText.insertString(mxDocCursor, "Fish section begins:", false);
// Then select all of the text
xParaCursor.gotoNextParagraph(true);
xParaCursor.gotoNextParagraph(true);
// Create a new text section and get it's XNamed interface
XNamed xSectionNamed = (XNamed) UnoRuntime.queryInterface(
XNamed.class,
mxDocFactory.createInstance("com.sun.star.text.TextSection"));
// Set the name of our new section (appropiately) to 'Fish'
xSectionNamed.setName("Fish");
// Create the TextColumns service and get it's XTextColumns interface
XTextColumns xColumns = (XTextColumns) UnoRuntime.queryInterface(
138
XTextColumns.class,
mxDocFactory.createInstance("com.sun.star.text.TextColumns"));
// We want three columns
xColumns.setColumnCount((short) 3);
// Get the TextColumns, and make the middle one narrow with a larger
margin
// on the left than the right
TextColumn[] aSequence = xColumns.getColumns ();
aSequence[1].Width /= 2;
aSequence[1].LeftMargin = 350;
aSequence[1].RightMargin = 200;
// Set the updated TextColumns back to the XTextColumns
xColumns.setColumns(aSequence);
// Get the property set interface of our 'Fish' section
XPropertySet xSectionProps = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xSectionNamed);
// Set the columns to the Text Section
xSectionProps.setPropertyValue("TextColumns", xColumns);
// Get the XTextContent interface of our 'Fish' section
mxFishSection = (XTextContent) UnoRuntime.queryInterface(
XTextContent.class, xSectionNamed);
// Insert the 'Fish' section over the currently selected text
mxDocText.insertTextContent(mxDocCursor, mxFishSection, true);
// Get the wonderful XRelativeTextContentInsert interface
XRelativeTextContentInsert xRelative = (XRelativeTextContentInsert)
UnoRuntime.queryInterface(XRelativeTextContentInsert.class,
mxDocText);
// Create a new empty paragraph and get it's XTextContent interface
XTextContent xNewPara = (XTextContent)
UnoRuntime.queryInterface(XTextContent.class,
mxDocFactory.createInstance("com.sun.star.text.Paragraph"));
// Insert the empty paragraph after the fish Text Section
xRelative.insertTextContentAfter(xNewPara, mxFishSection);
} catch (Exception e) {
e.printStackTrace(System.out);
}
}
The text columns property consists of com.sun.star.text.TextColumn structs. The Width elements of all
structs in the TextColumns sequence make up a sum, that is provided by the method
getReferenceValue() of the XTextColumns interface. To determine the metric width of an actual
139
column, the reference value and the columns width element have to be calculated using the metric width of
the object (page, text frame, text section) and a rule of three, for example:
Link targets
The interface com.sun.star.document.XLinkTargetSupplier of the document model provides all elements of
the document that can be used as link targets. These targets can be used for load URLs and sets the
selection to a certain position object inside of a document. An example of a URL containing a link target is
"file:///c:/documents/document1|bookmarkname".
This interface is used from the hyperlink dialog to detect the links available inside of a document.
The interface com.sun.star.container.XNameAccess returned by the method getLinks() provides access
to an array of target types. These types are:
Tables
Text frame
Graphics
OLEObjects
Sections
Headings
Bookmarks.
The names of the elements depend on the installed language.
Each returned object supports the interfaces com.sun.star.beans.XPropertySet and interface
com.sun.star.container.XNameAccess. The property set provides the properties LinkDisplayName (string)
and LinkDisplayBitmap (com.sun.star.awt.XBitmap). Each of these objects provides an array of targets
140
of the relating type. Each target returned supports the interface com.sun.star.beans.XPropertySet and the
property LinkDisplayName (string).
The name of the objects is the bookmark to be added to the document URL, for example, "Table1|table". The
LinkDisplayName contains the name of the object, e.g. "Table1
void lockControllers()
void unlockControllers()
boolean hasControllersLocked()
com::sun::star::frame::XController getCurrentController()
void setCurrentController( [in] com::sun::star::frame::XController xController)
The controller returned by getCurrentController() shares the following interfaces with all other
document controllers in OpenOffice.org:
com.sun.star.frame.XController
com.sun.star.frame.XDispatchProvider
com.sun.star.ui.XContextMenuInterceptor
TextView
The writer controller implementation supports the interface com.sun.star.view.XSelectionSupplier that returns
the object that is currently selected in the user interface.
Its method getSelection() returns an any that may contain the following object depending on the
selection:
Selection
Text
Returned Object
com.sun.star.container.XIndexAccess containing one or more com.sun.star.uno.XInterface pointing to a text
range.
141
Selection of table
cells
Text frame
Graphic object
OLE object
com.sun.star.view.XControlAccess
provides access to the controller of form controls.
com.sun.star.text.XTextViewCursorSupplier
Properties of com.sun.star.text.ViewSettings
ShowAnnotations
ShowBreaks
ShowDrawings
ShowFieldCommands
boolean - If true, text fields are shown with their commands, otherwise the content is visible.
ShowFootnoteBackground
ShowGraphics
ShowHiddenParagraphs
ShowHiddenText
ShowHoriRuler
ShowHoriScrollBar
ShowIndexMarkBackground
ShowParaBreaks
ShowProtectedSpaces
boolean - If true, protected spaces (hard spaces) are displayed with gray background.
ShowSoftHyphens
ShowSpaces
ShowTableBoundaries
ShowTables
ShowTabstops
ShowTextBoundaries
ShowTextFieldBackground
ShowVertRuler
ShowVertScrollBar
SmoothScrolling
SolidMarkHandles
ZoomType
short - defines the zoom type for the document as defined in com.sun.star.view.DocumentZoomType
142
short - defines the zoom value to use, the value is given as percentage. Valid only if the property
ZoomType is set to com.sun.star.view.DocumentZoomType:BY_VALUE.
ZoomValue
com.sun.star.view.XViewSettingsSupplier
provides access to the settings of the view as described in the service com.sun.star.text.ViewSettings.
TextViewCursor
The text controller has a visible cursor that is used in the GUI. Get the com.sun.star.text.TextViewCursor by
calling getTextViewCursor() at the com.sun.star.text.XTextViewCursorSupplier interface of the current
text document controller.
It supports the following cursor capabilities that depend on having the necessary information about the
current layout state, therefore it is not supported by the model cursor.
com.sun.star.text.XPageCursor
boolean jumpToFirstPage()
boolean jumpToLastPage()
boolean jumpToPage( [in] long pageNo)
long getPage()
boolean jumpToNextPage()
boolean jumpToPreviousPage()
boolean jumpToEndOfPage()
boolean jumpToStartOfPage()
com.sun.star.view.XScreenCursor
boolean screenDown()
boolean screenUp()
com.sun.star.view.XLineCursor
boolean isAtStartOfLine()
boolean isAtEndOfLine()
void gotoEndOfLine( [in] boolean bExpand)
void gotoStartOfLine( [in] boolean bExpand)
com.sun.star.view.XViewCursor
boolean
boolean
boolean
boolean
144
Sommario
Office Development........................................................................................................................................... 1
OpenOffice.org Application Environment ......................................................................................................... 1
Desktop Environment ........................................................................................................................................ 2
Framework API................................................................................................................................................ 3
Frame-Controller-Model Paradigm in OpenOffice.org.................................................................................... 19
Frames ............................................................................................................................................................. 20
Linking Components and Windows .................................................................................................... 20
Communication through Dispatch Framework ................................................................................. 22
Components in Frames........................................................................................................................ 23
Controllers ....................................................................................................................................................... 23
Using the Desktop ........................................................................................................................................... 25
Using the Component Framework .................................................................................................................. 31
Getting Frames, Controllers and Models from Each Other ............................................................................. 32
Frames ............................................................................................................................................................. 33
XFrame ................................................................................................................................................... 33
XFramesSupplier .................................................................................................................................. 37
XDispatchProvider and XDispatchProviderInterception ................................................................. 38
XStatusIndicatorFactory....................................................................................................................... 38
Controllers ....................................................................................................................................................... 38
XController ............................................................................................................................................. 38
XDispatchProvider ................................................................................................................................ 39
XSelectionSupplier ............................................................................................................................... 39
XContextMenuInterception .................................................................................................................. 40
Document Specific Controller Services ............................................................................................. 40
Models ............................................................................................................................................................. 41
XModel.................................................................................................................................................... 41
XModifiable ............................................................................................................................................ 42
XStorable................................................................................................................................................ 42
XPrintable............................................................................................................................................... 42
XEventBroadcaster ............................................................................................................................... 43
XEventsSupplier.................................................................................................................................... 43
XDocumentInfoSupplier ....................................................................................................................... 43
XViewDataSupplier ............................................................................................................................... 43
Document Specific Features ............................................................................................................... 44
145
147