Difference between revisions of "Documentation/DevGuide/OfficeDev/Frames"
(Initial author Sun Microsystems, Inc.) |
|||
| (8 intermediate revisions by 6 users not shown) | |||
| Line 6: | Line 6: | ||
|NextPage=Documentation/DevGuide/OfficeDev/Controllers | |NextPage=Documentation/DevGuide/OfficeDev/Controllers | ||
}} | }} | ||
| − | {{DISPLAYTITLE:Frames}} | + | {{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}} |
| + | {{DISPLAYTITLE:Frames}} | ||
=== Linking Components and Windows === | === Linking Components and Windows === | ||
<!--<idltopic>com.sun.star.frame.Frame;com.sun.star.frame.XFrame;com.sun.star.frame.XFrames;com.sun.star.awt.XWindow;com.sun.star.awt.XTopWindow</idltopic>--> | <!--<idltopic>com.sun.star.frame.Frame;com.sun.star.frame.XFrame;com.sun.star.frame.XFrames;com.sun.star.awt.XWindow;com.sun.star.awt.XTopWindow</idltopic>--> | ||
| Line 15: | Line 16: | ||
[[Image:FCMFrame.png|none|thumb|400px|Frame containing a component]] | [[Image:FCMFrame.png|none|thumb|400px|Frame containing a component]] | ||
| − | When a frame is constructed, the frame must be initialized with a container window using | + | When a frame is constructed, the frame must be initialized with a container window using <idlm>com.sun.star.frame.XFrame:initialize</idlm>(). This method expects the <idl>com.sun.star.awt.XWindow</idl> interface of a surrounding window instance, which becomes the container window of the frame. The window instance passed to <code>initialize()</code> must also support <idl>com.sun.star.awt.XTopWindow</idl> to become a container window. The container window must broadcast window events, such as <code>windowActivated()</code>, and appear in front of other windows or be sent to the background. The fact that container windows support <idl>com.sun.star.awt.XTopWindow</idl> does not mean the container window is an independent window of the underlying window system with a title bar and a system menu. An <code>XTopWindow</code> acts as a window if necessary, but it can also be docked or depend on a surrounding application window. |
| − | After initializing the frame, a component is set into the frame by a frame loader implementation that loads a component into the frame. It calls | + | 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 <idlm>com.sun.star.frame.XFrame:setComponent</idlm>() that takes another <idl>com.sun.star.awt.XWindow</idl> instance and the <idl>com.sun.star.frame.XController</idl> interface of a controller.Usually the controller is holding a model, therefore the component gets a component window of its own, separate from the container window. |
| − | A frame with a component is associated with ''two'' windows: the ''container'' window which is an <code>XTopWindow</code> and the ''component'' window, which is the rectangular area that displays the component and receives GUI events for the component while it is active. When a frame is initialized with an instance of a window in a call to <code>initialize()</code>, this window becomes its container window. When a component is set into a frame using <code>setComponent()</code>, another <idl>com.sun.star.awt.XWindow</idl> instance is passed | + | A frame with a component is associated with ''two'' windows: the ''container'' window which is an <code>XTopWindow</code> and the ''component'' window, which is the rectangular area that displays the component and receives GUI events for the component while it is active. When a frame is initialized with an instance of a window in a call to <code>initialize()</code>, this window becomes its container window. When a component is set into a frame using <code>setComponent()</code>, another <idl>com.sun.star.awt.XWindow</idl> instance is passed and becomes the component window. |
When a frame is added to the desktop frame hierarchy, the desktop becomes the parent frame of our frame. For this purpose, the <idl>com.sun.star.frame.XFramesSupplier</idl> interface of the desktop is passed to the method <code>setCreator()</code> at the <code>XFrame</code> interface. This happens internally when the method <code>append()</code> is called at the <idl>com.sun.star.frame.XFrames</idl> interface supplied by the desktop. | When a frame is added to the desktop frame hierarchy, the desktop becomes the parent frame of our frame. For this purpose, the <idl>com.sun.star.frame.XFramesSupplier</idl> interface of the desktop is passed to the method <code>setCreator()</code> at the <code>XFrame</code> interface. This happens internally when the method <code>append()</code> is called at the <idl>com.sun.star.frame.XFrames</idl> interface supplied by the desktop. | ||
| − | {{ | + | {{Note|A component window can have sub-windows, and that is the case with all documents in {{AOo}}. For instance, a text document has sub-windows for the toolbars and the editable text. Form controls are sub-windows, as well, however, these sub-windows depend on the component window and do not appear in the Frame-Controller-Model paradigm, as discussed above.}} |
The second diagram shows a frame with a component and a sub-frame with another component. Each frame has a container window and component window. | 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. | ||
| Line 29: | Line 30: | ||
[[Image:FCMSubframe.png|none|thumb|400px|Frame containing a component and a sub-frame]] | [[Image:FCMSubframe.png|none|thumb|400px|Frame containing a component and a sub-frame]] | ||
| − | In the {{ | + | In the {{AOo}} 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. | 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. | ||
| Line 39: | Line 40: | ||
=== Communication through Dispatch Framework === | === Communication through Dispatch Framework === | ||
| − | Besides the main role of frames as expressed in the <idl>com.sun.star.frame.XFrame</idl> interface, frames play another role by providing a communication context for the component they contain, that is, every communication from a controller to the desktop environment | + | Besides the main role of frames as expressed in the <idl>com.sun.star.frame.XFrame</idl> interface, frames play another role by providing a communication context for the component they contain, that is, every communication from a controller to the desktop environment and the user interface, and conversely, is done through the frame. This aspect of a frame is published through the <idl>com.sun.star.frame.XDispatchProvider</idl> interface, which uses special command requests to trigger actions. |
The section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]] discusses the usage of the dispatch API. | The section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]] discusses the usage of the dispatch API. | ||
| Line 45: | Line 46: | ||
=== Components in Frames === | === Components in Frames === | ||
| − | The desktop environment section discussed the three kinds of viewable components that can be inserted into a frame. If the component has a controller ''and'' a model like a document, or if it has only a controller, such as the bibliography and database browser, it implements the <idl>com.sun.star.frame.Controller</idl> service represented by the interface <idl>com.sun.star.frame.XController</idl>. In the call to | + | The desktop environment section discussed the three kinds of viewable components that can be inserted into a frame. If the component has a controller ''and'' a model like a document, or if it has only a controller, such as the bibliography and database browser, it implements the <idl>com.sun.star.frame.Controller</idl> service represented by the interface <idl>com.sun.star.frame.XController</idl>. In the call to <idlm>com.sun.star.frame.XFrame:setComponent</idlm>(), the controller is passed with the component window instance. If the component has no controller, it directly implements <idl>com.sun.star.lang.XComponent</idl> and <idl>com.sun.star.awt.XWindow</idl>. In this case, the component is passed as <code>XWindow</code> parameter, and the <code>XController</code> parameter must be a <code>XController</code> reference set to null. |
If the viewable component is a ''trivial component'' (implementing <code>XWindow</code> only), the frame holds a reference to the component window, controls the lifetime of the component and propagates certain events from the container window to the component window. If the viewable component is an ''office component'' (having a controller), the frame adds to these basic functions a set of features for integration of the component into the environment by supporting additional command URLs for the component at its <idl>com.sun.star.frame.XDispatchProvider</idl> interface. | If the viewable component is a ''trivial component'' (implementing <code>XWindow</code> only), the frame holds a reference to the component window, controls the lifetime of the component and propagates certain events from the container window to the component window. If the viewable component is an ''office component'' (having a controller), the frame adds to these basic functions a set of features for integration of the component into the environment by supporting additional command URLs for the component at its <idl>com.sun.star.frame.XDispatchProvider</idl> interface. | ||
{{PDL1}} | {{PDL1}} | ||
| − | [[Category: Office Development]] | + | |
| + | [[Category:Documentation/Developer's Guide/Office Development]] | ||
Latest revision as of 17:32, 2 January 2021
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 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 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 Apache OpenOffice. For instance, a text document has sub-windows for the toolbars and the editable text. Form controls are sub-windows, as well, however, these sub-windows depend on the component window and do not appear in the Frame-Controller-Model paradigm, as discussed above. |
The second diagram shows a frame with a component and a sub-frame with another component. Each frame has a container window and component window.
In the Apache OpenOffice 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 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 a 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). |
