Difference between revisions of "Documentation/DevGuide/GUI/The Toolkit Service"
m (1 revision(s)) |
m |
||
| Line 9: | Line 9: | ||
Before investigating this example, it is reasonable to briefly describe the character of a frame. A frame exports the interface <idl>com.sun.star.frame.XFrame</idl> and serves as a container for arbitrary content - mostly document models. To visualize this content it uses a window (<idl>com.sun.star.awt.XWindow</idl>). It is the central coordination instance that brings together menus, documents, LayoutManager (see <idl>com.sun.star.frame.XLayoutManager</idl>) and progress bars. For more information see [[Documentation/DevGuide/OfficeDev/Using the Component Framework|Using the Component Framework]]. Another important responsibility is the delivery of commands - for example commands fired from tool bar buttons - to the components. See [[Documentation/DevGuide/OfficeDev/Dispatch Framework|Dispatch Framework]] and [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|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. | Before investigating this example, it is reasonable to briefly describe the character of a frame. A frame exports the interface <idl>com.sun.star.frame.XFrame</idl> and serves as a container for arbitrary content - mostly document models. To visualize this content it uses a window (<idl>com.sun.star.awt.XWindow</idl>). It is the central coordination instance that brings together menus, documents, LayoutManager (see <idl>com.sun.star.frame.XLayoutManager</idl>) and progress bars. For more information see [[Documentation/DevGuide/OfficeDev/Using the Component Framework|Using the Component Framework]]. Another important responsibility is the delivery of commands - for example commands fired from tool bar buttons - to the components. See [[Documentation/DevGuide/OfficeDev/Dispatch Framework|Dispatch Framework]] and [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|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. | ||
| − | + | <source lang="java"> | |
public XTopWindow showTopWindow( Rectangle _aRectangle){ | public XTopWindow showTopWindow( Rectangle _aRectangle){ | ||
XTopWindow xTopWindow = null; | XTopWindow xTopWindow = null; | ||
| Line 46: | Line 46: | ||
return xTopWindow; | return xTopWindow; | ||
} | } | ||
| − | + | </source> | |
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 <idl>com.sun.star.awt.WindowClass</idl>. | 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 <idl>com.sun.star.awt.WindowClass</idl>. | ||
| Line 67: | Line 67: | ||
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. | 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. | ||
| − | + | <source lang="java"> | |
public void showDocumentinDialogWindow(XWindowPeer _xParentWindowPeer, Rectangle _aRectangle, String _sUrl){ | public void showDocumentinDialogWindow(XWindowPeer _xParentWindowPeer, Rectangle _aRectangle, String _sUrl){ | ||
try { | try { | ||
| Line 116: | Line 116: | ||
throw new java.lang.RuntimeException("cannot happen..."); | throw new java.lang.RuntimeException("cannot happen..."); | ||
}} | }} | ||
| − | + | </source> | |
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 <code>windowAttribute VclWindowPeerAttribute.CLIPCHILDREN</code> to make sure that the graphical operations on the parent window do not interfere with child windows. | 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 <code>windowAttribute VclWindowPeerAttribute.CLIPCHILDREN</code> to make sure that the graphical operations on the parent window do not interfere with child windows. | ||
| Line 122: | Line 122: | ||
From the following example you can learn how to get the windowpeer from a frame | From the following example you can learn how to get the windowpeer from a frame | ||
| − | + | <source lang="java"> | |
/** gets the WindowPeer of a frame | /** gets the WindowPeer of a frame | ||
* @param _xFrame the UNO Frame | * @param _xFrame the UNO Frame | ||
| Line 132: | Line 132: | ||
return xWindowPeer; | return xWindowPeer; | ||
} | } | ||
| − | + | </source> | |
The <code>ComponentWindow</code> is the window that displays just the view of a document. The <code>Containerwindow</code> is the complete window including its title bar and border. | The <code>ComponentWindow</code> is the window that displays just the view of a document. The <code>Containerwindow</code> 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: | There are several ways to retrieve a frame. The easiest way to retrieve a frame is to query the frame that has the focus: | ||
| − | + | <source lang="java"> | |
public XFrame getCurrentFrame(){ | public XFrame getCurrentFrame(){ | ||
XFrame xRetFrame = null; | XFrame xRetFrame = null; | ||
| Line 148: | Line 148: | ||
return xRetFrame; | return xRetFrame; | ||
} | } | ||
| − | + | </source> | |
This should only be used for debugging purposes. The method <code>getCurrentFrame</code> 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 {{PRODUCTNAME}} extension provides a frame as explained in [[Documentation/DevGuide/WritingUNO/Integrating Components into OpenOffice.org|Integrating Components into OpenOffice.org]]. | This should only be used for debugging purposes. The method <code>getCurrentFrame</code> 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 {{PRODUCTNAME}} extension provides a frame as explained in [[Documentation/DevGuide/WritingUNO/Integrating Components into OpenOffice.org|Integrating Components into OpenOffice.org]]. | ||
Revision as of 13:45, 29 March 2008
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). |
