Frames

OpenOffice.org Developer's Guide

Office Development

< Previous Section

Next Section >

• OpenOffice.org Application Environment

• Desktop Environment
• Framework API

• Frame-Controller-Model Paradigm in OpenOffice.org
• Frames
• Controllers
• Windows
• Dispatch Framework

• Using the Desktop
• Using the Component Framework

• Getting Frames, Controllers and Models from Each Other
• Frames
• Controllers
• Models
• Window Interfaces

• Creating Frames Manually
• Handling Documents

• Closing Documents
• Storing Documents

• Using the Dispatch Framework

• Command URL
• Processing Chain
• Dispatch Process
• Dispatch Results
• Dispatch Interception

• Java Window Integration

• Common Application Features

• Internationalization

• Overview and Using the API
• Implementing a New Locale

• Linguistics

• Using Spellchecker
• Using Hyphenator
• Using Thesaurus
• Events
• Implementing a Spell Checker
• Implementing a Hyphenator
• Implementing a Thesaurus

• Integrating Import and Export Filters

• Filtering Process
• Filters
• Type Detection and its Configuration
• Properties of a Type
• Properties of a Filter
• Filter Options
• Properties of a FrameLoader
• Document API Filter Development

• XML Based Filter Development

• Writing the Filtering Component
• The Importer
• The Exporter
• XML Filter Detection

• Number Formats

• Managing Number Formats
• Applying Number Formats

• Document Events
• Path Organization

• Path Settings
• Path Variables

• Predefined Variables
• Custom Path Variables
• Resolving Path Variables

• OpenOffice.org Single Sign-On API
• RDF metadata

< Previous Page

Next Page >

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:

  // methods for container window
  void initialize ( [in] com::sun::star::awt::XWindow xWindow);
  com::sun::star::awt::XWindow getContainerWindow ();
 
  // methods for component window and controller
  boolean setComponent ( [in] com::sun::star::awt::XWindow xComponentWindow, 
                         [in] com::sun::star::frame::XController xController );
  com::sun::star::awt::XWindow getComponentWindow ();
  com::sun::star::frame::XControllergetController ();

The first two methods deal with the container window of a frame, the latter three are about linking the component and the component window with the frame. The method initialize() expects a top window that is created by the AWT toolkit that becomes the container window of the frame and is retrieved by getContainerWindow().

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:

  [oneway] void setCreator ( [in] com::sun::star::frame::XFramesSupplier xCreator );
  com::sun::star::frame::XFramesSupplier getCreator ();
  string getName ();
  [oneway] void setName ( [in] string aName );
  com::sun::star::frame::XFrame findFrame ( [in] string aTargetFrameName, [in] long nSearchFlags );
  boolean isTop ();

The XFrame method setCreator() informs a frame about its parent frame and must be called by a frames container (com.sun.star.frame.XFrames) when a frame is added to it by a call to append(). A frames container is provided by frames supporting the interface com.sun.star.frame.XFramesSupplier. XFramesSupplier is currently supported by the desktop frame and by the default frame implementation used by Apache OpenOffice documents. It is described below.

The frame has a custom name that is read through getName() and written through setName(). Frames in the desktop hierarchy created by GUI interaction usually do not have names. The getName() returns an empty string for them, whereas frames that are created for special purposes, such as the beamer frame or the online help, have names. Developers can set a name and use it to address a frame in findFrame() calls or when loading a component into the frame. Custom frame names must not start with an underscore. Leading underscores are reserved for special frame names. See below.

Every frame in the frame hierarchy is accessed through any other frame in this hierarchy by calling the findFrame() method. This method searches for a frame with a given name in five steps: self, children, siblings, parent, and create if not found. The findFrame() checks the called frame, then calls findFrame() at its children, then its siblings and at its parent frame. The fifth step in the search strategy is reached if the search makes it to the desktop without finding a frame with the given name. In this case, a new frame is created and assigned the name that was searched for. If the top frame is outside the desktop hierarchy, a new frame is not created.

The name used with findFrame() can be an arbitrary string without a leading underscore or one of the following reserved frame names. These names are for internal use for loading documents. Some of the reserved names are logical in a findFrame() call, also. A complete list of reserved frame names can be found in section Target Frame.

_top

Returns the top frame of the called frame, first frame where isTop() returns true when traveling up the hierarchy.

_parent

Returns the next frame above in the frame hierarchy.

_self

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 Apache OpenOffice 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 Apache OpenOffice 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 CREATE SearchFlag may differ.

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:

  void contextChanged ();
 
  [oneway] void activate ();
  [oneway] void deactivate ();
  boolean isActive ();
 
  [oneway] void addFrameActionListener ( [in] com::sun::star::frame::XFrameActionListener xListener );
  [oneway] void removeFrameActionListener ( [in] com::sun::star::frame::XFrameActionListener xListener );

The method activate() makes the given frame the active frame in its parent container. If the parent is the desktop frame, this makes the associated component the current component. However, this is not reflected in the user interface by making the corresponding window the top window. If the container of the active frame is to be the top window, use setFocus() at the com.sun.star.awt.XWindow interface of the container window.

The interface com.sun.star.frame.XFrameActionListener used with addFrameActionListener() must implement the following method:

Method of com.sun.star.frame.XFrameActionListener

frameAction()

Takes a struct com.sun.star.frame.FrameActionEvent. The struct contains two members: the source com.sun.star.frame.XFrame Frame and an enum com.sun.star.frame.FrameActionEvent Action value with one of the following values: 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. FRAME_ACTIVATED: a component has been activated. Activations are broadcast from the top component which was not active, down to the innermost component. FRAME_DEACTIVATING: broadcast immediately before the component is deactivated. Deactivations are broadcast from the innermost component which does not stay active up to the outermost component which does not stay active. 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. FRAME_UI_ACTIVATED: broadcast by an active frame when it is getting UI control (tool control). FRAME_UI_DEACTIVATING: broadcast by an active frame when it is losing UI control (tool control).

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 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 Apache OpenOffice 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 OpenNewView property with loadComponentFromURL() at the com.sun.star.frame.XComponentLoader interface of the desktop. There is also another possibility: dispatch a ".uno:NewWindow" command to a frame that contains that model.

XFramesSupplier

The Frame interface com.sun.star.frame.XFramesSupplier offers methods to access sub-frames of a frame. The frame implementation of Apache OpenOffice 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:

  void append ( [in] com::sun::star::frame::XFrame xFrame )
  sequence < com::sun::star::frame::XFrame > queryFrames ( [in] long nSearchFlags )
  void remove ( [in] com::sun::star::frame::XFrame xFrame );

This XFrames collection is used when frames are appended to a frame to become sub-frames. The append() method implementation must extend the existing frame hierarchy by an internal call to setCreator() at the parent frame in the frame hierarchy. The parent frame is always the frame whose XFramesSupplier interface is used to append a new frame.

Through getActiveFrame() access the active sub-frame in a frame with subframes. If there are no sub-frames or a sub-frame is currently non-active, the active frame is null. The setActiveFrame() is called by a sub-frame to inform the frame about the activation of the sub-frame. In setActiveFrame(), the method setActiveFrame() at the creator is called, then the registered frame action listeners are notified by an appropriate call to frameAction() with Action set to FRAME_UI_ACTIVATED.

XDispatchProvider and XDispatchProviderInterception

Frame services also support com.sun.star.frame.XDispatchProvider and com.sun.star.frame.XDispatchProviderInterception. The section Using the Dispatch Framework explains how these interfaces are used.

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 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.

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