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.
When a frame is constructed, the frame must be initialized with a container window using <idlml>com.sun.star.frame.XFrame:initialize</idlml>(). This method expects the 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 <idlml>com.sun.star.frame.XFrame:setComponent</idlml>() 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.
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.
In the OpenOffice.org GUI, sub-frames appear as dependent windows. The sub-frame in the illustration above could be a dockable window, such as the beamer showing the database browser or a floating frame in a document created with Insert > Frame.
Note that a frame with a component and sub-frame is associated with four windows. The frame and the sub-frame have a container window and a component window for the component.
When a sub-frame is added to a surrounding frame, the frame becomes the parent of the sub-frame by a call to
setCreator() at the sub-frame. This happens internally when the method
append() is called at the com.sun.star.frame.XFrames interface supplied by the surrounding frame.
The section Creating Frames Manually shows examples for the usage of the
XFrame interface that creates frames in the desktop environment, constructs dockable and standalone windows, and inserts components into frames.
Communication through Dispatch Framework
Besides the main role of frames as expressed in the com.sun.star.frame.XFrame interface, frames play another role by providing a communication context for the component they contain, that is, every communication from a controller to the desktop environment and the user interface, and conversely, is done through the frame. This aspect of a frame is published through the com.sun.star.frame.XDispatchProvider interface, which uses special command requests to trigger actions.
The section Using the Dispatch Framework discusses the usage of the dispatch API.
Components in Frames
The desktop environment section discussed the three kinds of viewable components that can be inserted into a frame. If the component has a controller and a model like a document, or if it has only a controller, such as the bibliography and database browser, it implements the com.sun.star.frame.Controller service represented by the interface com.sun.star.frame.XController. In the call to <idlml>com.sun.star.frame.XFrame:setComponent</idlml>(), the controller is passed with the component window instance. If the component has no controller, it directly implements 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.
|Content on this page is licensed under the Public Documentation License (PDL).|