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
When frames link components into a surrounding window system, they build a frame hierarchy. This aspect is covered by the hierarchy-related
[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 ();
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 com.sun.star.frame.XFrames: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 OpenOffice.org 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.
- Returns the top frame of the called frame, first frame where isTop() returns true when traveling up the hierarchy.
- Returns the next frame above in the frame hierarchy.
- 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.
- 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 (
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.
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.
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 );
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 |
|At this time, the |
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
There is also another possibility: dispatch a ".uno:NewWindow" command to a frame that contains that model.
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)
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 );
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.
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
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 com.sun.star.frame.FrameActionEvent:Action set to
XDispatchProvider and XDispatchProviderInterception
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.
|Content on this page is licensed under the Public Documentation License (PDL).|