The Toolkit Service
The Service com.sun.star.awt.Toolkit is the central instance to create Windows. For this purpose the interface com.sun.star.awt.XToolkit is of major interest. The two methods getDesktopWindow() and getWorkArea() were used when OpenOffice.org offered an intregrated DesktopWindow, and are now deprecated. An instance of the com.sun.star.awt.Toolkit is created at the global MultiServicefactory. One way to get this peer from the frame of the document window can be seen in the following example.
Before investigating this example, it is reasonable to briefly describe the character of a frame. A frame exports the interface com.sun.star.frame.XFrame and serves as a container for arbitrary content - mostly document models. To visualize this content it uses a window (com.sun.star.awt.XWindow). It is the central coordination instance that brings together menus, documents, LayoutManager (see com.sun.star.frame.XLayoutManager) and progress bars. For more information see Using the Component Framework. Another important responsibility is the delivery of commands - for example commands fired from tool bar buttons - to the components. See Dispatch Framework and Using the Dispatch Framework for more information on this. A frame may be embedded in a hierarchy of other frames. The following example demonstrates the creation of a very basic window that is attached to a desktop frame.
public XTopWindow showTopWindow( Rectangle _aRectangle){ XTopWindow xTopWindow = null; try { // The Toolkit is the creator of all windows... Object oToolkit = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext); XToolkit xToolkit = (XToolkit) UnoRuntime.queryInterface(XToolkit.class, oToolkit); // set up a window description and create the window. A parent window is always necessary for this... com.sun.star.awt.WindowDescriptor aWindowDescriptor = new com.sun.star.awt.WindowDescriptor(); // a TopWindow is contains a title bar and is able to inlude menus... aWindowDescriptor.Type = WindowClass.TOP; // specify the position and height of the window on the parent window aWindowDescriptor.Bounds = _aRectangle; // set the window attributes... aWindowDescriptor.WindowAttributes = WindowAttribute.SHOW + WindowAttribute.MOVEABLE + WindowAttribute.SIZEABLE + WindowAttribute.CLOSEABLE; // create the window... XWindowPeer xWindowPeer = xToolkit.createWindow(aWindowDescriptor); XWindow xWindow = (XWindow) UnoRuntime.queryInterface(XWindow.class, xWindowPeer); // create a frame and initialize it with the created window... Object oFrame = m_xMCF.createInstanceWithContext("com.sun.star.frame.Frame", m_xContext); m_xFrame = (XFrame) UnoRuntime.queryInterface(XFrame.class, oFrame); Object oDesktop = m_xMCF.createInstanceWithContext("com.sun.star.frame.Desktop", m_xContext); XFramesSupplier xFramesSupplier = (XFramesSupplier) UnoRuntime.queryInterface(XFramesSupplier.class, oDesktop); m_xFrame.setCreator(xFramesSupplier); // get the XTopWindow interface.. xTopWindow = (XTopWindow) UnoRuntime.queryInterface(XTopWindow.class, xWindow); } catch (com.sun.star.lang.IllegalArgumentException ex) { ex.printStackTrace(); } catch (com.sun.star.uno.Exception ex) { ex.printStackTrace(); } return xTopWindow; }
As can be seen, the window is described by a [IDL:com.sun.star.awt.WindowDescriptor] that manifests all the facets of the window and also the window attributes as defined in [IDL:com.sun.star.awt.WindowAttribute]. It is possible, but not necessary, to define a parent window. The member Type of the windowdescriptor distinguishes between various values of the enumeration com.sun.star.awt.WindowClass.
| Values of com.sun.star.awt.WindowClass | |
|---|---|
| TOP | Specifies if a window is a TopWindow with the ability to include a menubar and a titlebar.
|
| MODALTOP | Specifies if a window is a modal TopWindow that imperatively waits for user input.
|
| CONTAINER | Specifies if a window may include child windows. |
| SIMPLE | A simple window that may also be a container. |
The following example shows how a document is loaded into a window that has been previously inserted into a dialog. The example method expects the peer of the parent dialog to be passed over.
public void showDocumentinDialogWindow(XWindowPeer _xParentWindowPeer, Rectangle _aRectangle, String _sUrl){ try { // The Toolkit is the creator of all windows... Object oToolkit = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext); XToolkit xToolkit = (XToolkit) UnoRuntime.queryInterface(XToolkit.class, oToolkit); // set up a window description and create the window. A parent window is always necessary for this... com.sun.star.awt.WindowDescriptor aWindowDescriptor = new com.sun.star.awt.WindowDescriptor(); // a simple window is enough for this purpose... aWindowDescriptor.Type = WindowClass.SIMPLE; aWindowDescriptor.WindowServiceName = "dockingwindow"; // assign the parent window peer as described in the idl description... aWindowDescriptor.Parent = _xParentWindowPeer; aWindowDescriptor.ParentIndex = 1; aWindowDescriptor.Bounds = _aRectangle; // set the window attributes... // The attribute CLIPCHILDREN causes the parent to not repaint the areas of the children... aWindowDescriptor.WindowAttributes = VclWindowPeerAttribute.CLIPCHILDREN + WindowAttribute.BORDER + WindowAttribute.SHOW; XWindowPeer xWindowPeer = xToolkit.createWindow(aWindowDescriptor); XWindow xWindow = (XWindow) UnoRuntime.queryInterface(XWindow.class, xWindowPeer); XView xView = (XView) UnoRuntime.queryInterface(XView.class, xWindow); // create a frame and initialize it with the created window... Object oFrame = m_xMCF.createInstanceWithContext("com.sun.star.frame.Frame", m_xContext); // The frame should be of global scope because it's within the responsibility to dispose it after usage m_xFrame = (XFrame) UnoRuntime.queryInterface(XFrame.class, oFrame); m_xFrame.initialize(xWindow); // load the document and open it in preview mode XComponentLoader xComponentLoader = (XComponentLoader) UnoRuntime.queryInterface(XComponentLoader.class, m_xFrame); PropertyValue[] aPropertyValues = new PropertyValue[2]; PropertyValue aPropertyValue = new PropertyValue(); aPropertyValue.Name = "Preview"; aPropertyValue.Value = Boolean.TRUE; aPropertyValues[0] = aPropertyValue; aPropertyValue = new PropertyValue(); aPropertyValue.Name = "ReadOnly"; aPropertyValue.Value = Boolean.TRUE; aPropertyValues[1] = aPropertyValue; xComponentLoader.loadComponentFromURL(_sUrl, "_self", 0, aPropertyValues); } catch (com.sun.star.lang.IllegalArgumentException ex) { ex.printStackTrace(); throw new java.lang.RuntimeException("cannot happen..."); } catch (com.sun.star.uno.Exception ex) { ex.printStackTrace(); throw new java.lang.RuntimeException("cannot happen..."); }}
As can be seen, the procedure to create the window and its frame is quite straightforward. The example clarifies the role of the frame as the central instance to bring together the window, layout manager and the document (model). You must set the windowAttribute VclWindowPeerAttribute.CLIPCHILDREN to make sure that the graphical operations on the parent window do not interfere with child windows.
Of course, there are use cases where no parent windowpeer is directly available, so this must be retrieved from a frame beforehand.
From the following example you can learn how to get the windowpeer from a frame
/** gets the WindowPeer of a frame * @param _xFrame the UNO Frame * @return the windowpeer of the frame */ public XWindowPeer getWindowPeer(XFrame _xFrame){ XWindow xWindow = _xFrame.getContainerWindow(); XWindowPeer xWindowPeer = (XWindowPeer) UnoRuntime.queryInterface(XWindowPeer.class, xWindow); return xWindowPeer; }
The ComponentWindow is the window that displays just the view of a document. The Containerwindow is the complete window including its title bar and border.
There are several ways to retrieve a frame. The easiest way to retrieve a frame is to query the frame that has the focus:
public XFrame getCurrentFrame(){ XFrame xRetFrame = null; try { Object oDesktop = m_xMCF.createInstanceWithContext("com.sun.star.frame.Desktop", m_xContext); XDesktop xDesktop = (XDesktop) UnoRuntime.queryInterface(XDesktop.class, oDesktop); xRetFrame = xDesktop.getCurrentFrame(); } catch (com.sun.star.uno.Exception ex) { ex.printStackTrace(); } return xRetFrame; }
This should only be used for debugging purposes. The method getCurrentFrame is based on the implementation of the window handler of the operating system and you cannot be sure that the returned frame is always the desired one on all supported platforms, or that a valid frame is returned at all. Usually each OpenOffice.org extension provides a frame as explained in Integrating Components into OpenOffice.org.
Dockable Windows
The interface XDockableWindow is currently unpublished and only used internally to control layout manager based tool bars. Although the interface is exported by Windows too, its method is not fully supported. It is planed to support dockable windows in a future version of OpenOffice.org.
| Content on this page is licensed under the Public Documentation License (PDL). |
