Creating Frames Manually

From Apache OpenOffice Wiki
Jump to: navigation, search



Frame Creation

Every time a frame is needed in Apache OpenOffice, the com.sun.star.frame.Frame service is created. Apache OpenOffice has an implementation for this service, available at the global service manager.

This service can be replaced by a different implementation, for example, your own implementation in Java, by registering it at the service manager. In special cases, it is possible to use a custom frame implementation instead of the com.sun.star.frame.Frame service by instantiating a specific implementation using the implementation name with the factory methods of the service manager. Both methods can alter the default window and document handling in Apache OpenOffice, thus changing or extending its functionality.

Assigning Windows to Frames

Every frame can be assigned to any Apache OpenOffice window. For instance, the same frame implementation is used to load a component into an application window of the underlying windowing system or into a preview window of a Apache OpenOffice dialog. The com.sun.star.frame.Frame service implementation does not depend on the type of the window, although the entirety of the frame and window will be a different object by the user.

If you have a window in your application and want to load a Apache OpenOffice document, create a frame and window object, and put them together by a call to initialize(). A default frame is created by instantiating an object implementing the com.sun.star.frame.Frame service at the global service manager. For window creation, the current com.sun.star.awt implementation has to be used to create windows in all languages supporting UNO. This toolkit offers a method to create window objects that wrap a platform specific window, such as a Java AWT window or a Windows system window represented by its window handle. A Java example is given below.

Two conditions apply to windows that are to be used with Apache OpenOffice frames.

The first condition is that the window must be created by the current com.sun.star.awt.Toolkit service implementation. Not every object implementing the com.sun.star.awt.XWindow interface is used as an argument in the initialize() method, because it is syntactically correct, but it is restricted to objects created by the current com.sun.star.awt implementation. The insertion of a component into a frame only works if all involved windows are .xbl created by the same toolkit implementation. All internal office components, such as Writer and Calc, are implemented using the Visual Component Library (VCL), so that they do not work if the container window is not implemented by VCL. The current toolkit uses this library internally, so all the windows created by the awt toolkit are passed to a frame. No others work at this time. Using VCL directly is not recommended. The code has to be rewritten, whenever this complication has incurred by the current office implementation and is removed, and the toolkit implementation is exchangeable.

The second condition is that if a frame and its component are supposed to get windowActivated() messages, the window object implements the additional interface com.sun.star.awt.XTopWindow. This is necessary for editing components, because the windowActivated event shows a cursor or a selection in the document. As long as this condition is met, further code is not necessary for the interaction between the frame and window, because the frame gets all the necessary events from the window by registering the appropriate listeners in the call to initialize().

When you use the com.sun.star.awt.Toolkit to create windows, supply a com.sun.star.awt.WindowDescriptor struct to describe what kind of window is required. Set the Type member of this struct to TOP and the WindowServiceName member to "window" if you want to have an application window, or to "dockingwindow" if a window is need to be inserted in other windows created by the toolkit.

Setting Components into Frame Hierarchies

Once a frame has been initialized with a window, it can be added to a frames supplier, such as the desktop using the frames container provided by getFrames(). Its method append() inserts the new frame into the XFrames container and calls setCreator() at the new frame, passing the XFramesSupplier interface of the parent frame.

Documentation note.png The parent frame must be set as the creator of the newly created frame. The current implementation of the frames container calls setCreator() internally when frames are added to it using append().

The following example creates a new window and a frame, plugs them together, and adds them to the desktop, thus creating a new, empty Apache OpenOffice application window.

  // Conditions: xSMGR = m_xServiceManager 
  // Get access to vcl toolkit of remote office to create 
  // the container window of new target frame. 
  com.sun.star.awt.XToolkit xToolkit = 
    (com.sun.star.awt.XToolkit)UnoRuntime.queryInterface( 
        com.sun.star.awt.XToolkit.class, xSMGR.createInstance("com.sun.star.awt.Toolkit") );
 
  // Describe the properties of the container window. 
  // Tip: It is possible to use native window handle of a java window 
  // as parent for this. see chapter "OfficeBean" for further informations 
     com.sun.star.awt.WindowDescriptor aDescriptor = new com.sun.star.awt.WindowDescriptor();
 
  aDescriptor.Type              = com.sun.star.awt.WindowClass.TOP ; 
  aDescriptor.WindowServiceName = "window" ; 
  aDescriptor.ParentIndex       = -1; 
  aDescriptor.Parent            = null; 
  aDescriptor.Bounds            = new com.sun.star.awt.Rectangle(0,0,0,0);
 
  aDescriptor.WindowAttributes  = 
    com.sun.star.awt.WindowAttribute.BORDER    |
    com.sun.star.awt.WindowAttribute.MOVEABLE  | 
    com.sun.star.awt.WindowAttribute.SIZEABLE  | 
    com.sun.star.awt.WindowAttribute.CLOSEABLE ;  
 
  com.sun.star.awt.XWindowPeer xPeer = xToolkit.createWindow(aDescriptor) ; 
 
  com.sun.star.awt.XWindow xWindow = (com.sun.star.awt.XWindow)UnoRuntime.queryInterface ( com.sun.star.awt.XWindow .class, xPeer);  
  // Create a new empty target frame. 
  // Attention: Before {{PRODUCTNAME}} build 643 we must use  
  // com.sun.star.frame.Task instead of com.sun.star.frame.Frame,
  // because the desktop environment accepts only this special frame type 
  // as direct children. It will be deprecated from build 643 
  xFrame = (com.sun.star.frame.XFrame)UnoRuntime.queryInterface( 
     com.sun.star.frame.XFrame.class, 
         xSMGR.createInstance ("com.sun.star.frame.Task "));  
 
  // Set the container window on it. xFrame.initialize(xWindow) ;
  // Insert the new frame in desktop hierarchy. 
  // Use XFrames interface to do so. It provides access to the 
  // child frame container of the parent node. 
  // Note: append(xFrame) calls xFrame.setCreator(Desktop) automatically. 
  com.sun.star.frame.XFramesSupplier xTreeRoot = 
  (com.sun.star.frame.XFramesSupplier)UnoRuntime.queryInterface( 
      com.sun.star.frame.XFramesSupplier.class, 
          xSMGR.createInstance("com.sun.star.frame.Desktop") );
 
  com.sun.star.frame.XFrames xChildContainer = xTreeRoot.getFrames ();
  xChildContainer.append(xFrame) ;
 
  // Make some other initializations. 
  xPeer.setBackground(0xFFFFFFFF); 
  xWindow.setVisible(true); 
  xFrame.setName("newly created 1") ;
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages