Creating Menus and Toolbars With the StarOffice API

Print-friendly Version

• Using the UI Configuration Managers
• Creating a Top-Level Menu
• Creating a Toolbar
• Making New Menus and Toolbars Persistent

Before you begin

Download the complete TextDemo.java sample application used in the article Programming With the StarOffice 8 Software Development Kit. If you are not familiar with the StarOffice SDK, first read the article. It describes how to set up a Java environment to use StarOffice APIs. It also describes how to use StarOffice functionality in a Java application.

A sample application is available: createMenuAndToolbar.java

The Menu and Toolbar API provides full access to all elements of the StarOffice software's menu, toolbar, and keyboard-shortcut configuration. This enables you to

• Create, update, and remove menus and submenus
• Administer and build toolbars
• Define new keyboard shortcuts

The Service ModuleUIConfigurationManagerSupplier provides access to the User Interface (UI) Configuration Managers that StarOffice provides. Each configuration manager is related to a certain document type. This Service exports the interface XModuleUIConfigurationManagerSupplier, which provides the method getUIConfigurationManager to retrieve the Configuration Manager.

Each UI Configuration Manager provides the createSettings() method to create a new instance of the user interface settings or getSettings() to retrieve that interface from an existing setting. These settings could be a menu or toolbar. getSettings() is the correct method to create a new menu due to the fact that the new menu is just an extension of a broader menu system. Toolbars are different; they are typically independent from each other. This makes the createSettings() method the appropriate choice to create a toolbar. Either method provides a XIndexAccess interface, which implements the Service UIElementSettings.

A menu is a tree structure of menu elements that starts with a root element. This has a container of menu elements, which could have another container of elements. In other words, a top-level menu has a menu which could have other (sub-) menus. A familiar example is the File > New menu/submenu.

The root structure for the menu is a PropertyValue set of four elements:

MenuProperty[0] = new PropertyValue();
MenuProperty[0].Name = "CommandURL";
MenuProperty[0].Value = ".uno:SunDC";
MenuProperty[1] = new PropertyValue();
MenuProperty[1].Name = "Label";
MenuProperty[1].Value = "Sun Developer Connection";
MenuProperty[2] = new PropertyValue();
MenuProperty[2].Name = "Type";
MenuProperty[2].Value = 0;
MenuProperty[3] = new PropertyValue();
MenuProperty[3].Name = "ItemDescriptorContainer";
MenuProperty[3].Value =
xCfgMgrFactory.createInstanceWithContext( xContext );

This PropertyValue structure defines only the root elements of the menu. This makes it necessary to create an additional container for the menu items. Such a container is created by the method createInstanceWithContext(), which expects as a parameter the component context of StarOffice. (What the component context is and how to retrieve it is described in the Programming with the StarOffice 8 Software Development Kit article.)

The PropertyValue structure for a single menu item looks similar to the one for the root element, but it is simpler. The ItemDescriptorContainer property is necessary only for pointers to a submenu.

itemProperty[0] = new PropertyValue();
itemProperty[0].Name = "CommandURL";
itemProperty[0].Value = "macro:///Standard.Module1.myMacro()";
itemProperty[1] = new PropertyValue();
itemProperty[1].Name = "Label";
itemProperty[1].Value = "myMacro";
itemProperty[2] = new PropertyValue();
itemProperty[2].Name = "Type";
itemProperty[2].Value = 0;

The structures for the root element and for a menu item are now defined. The next step is to apply it to the StarOffice menu structure, using the InsertByIndex() method provided by the XIndexContainer interface. Due to the tree structure of the StarOffice menu system, the root element of the new menu includes an instance of the menu items container. This container exports the interface XindexContainer, which provides the insertByIndex() method to add the menu item properties to the container.

IndexContainer topLevelMenu = (XIndexContainer)
        UnoRuntime.queryInterface(
		XIndexContainer.class,
        topLevelMenuProperty[3].Value );
		
topLevelMenu.insertByIndex( 0, menuItemProperty );

The method UnoRuntime.queryInterface() acquires the XIndexContainer interface from the user interface settings that was retrieved earlier. The InsertByIndex() method has two parameters: the first one specifies the location of the new menu and the second one the PropertyValue set of the menu. (The Programming with the StarOffice 8 Software Development Kit article and the First Contact chapter of the Developer Manual describe the usage and purpose of the frequently used UnoRuntime.queryInterface() method.)

However, the menu has not yet been applied to the StarOffice menu. This is done by the insertByIndex() method, which then has to be exported from the configuration settings of the current StarOffice menu.

XIndexContainer xCfgMgrContainer = (XIndexContainer)

        UnoRuntime.queryInterface( XIndexContainer.class,
xCfgMgrFactory );
xCfgMgrContainer.insertByIndex(
xAllMenuesFactory.getCount(),

        topLevelMenuProperty );

After doing this, the new menu still does not show up: The user interface setting is just a copy of the menu setting. This new menu setting has to replace the settings that are currently used. Do this with the replaceSettings() method, which is provided by the XUIConfigurationManager interface.

The new menu is now available for all text documents.

The internal structure of a toolbar is simpler than a menu, as toolbars cannot have sub-toolbars. The image on a toolbar button must be accessible however, or there can be problems in acquiring the image. To avoid this, you can "recycle" an image from the large number of images that StarOffice provides, as this article does. Any Portable Network Graphic (PNG) image of the right size is acceptable.

The list of existing images (with their URLs) can be determined in Tools > Customize. Choose the Toolbars tab, then select Modify > Change Icon. Hover with your pointer over the icon you like, and its tooltip help will show the internal StarOffice URL.

The Change Icon Dialog Box (click image to enlarge)

To use an image on a toolbar, retrieve the image manager with the getImageManager() method provided by the XUIConfigurationManager interface.

XImageManager xImgMgr = (XImageManager)
      UnoRuntime.queryInterface( XImageManager.class,
      xCfgMgr.getImageManager());
	  
String[ ] imgURL = new String[1];
imgURL[0] = ".uno:CloseDoc";
n
XGraphic[ ] xGraphic = xImgMgr.getImages( ((short) 0), imgURL );

String[ ] imgCmd = new String[1];
imgCmd[0] = "macro:///Standard.Module1.myMacro()";

xImgMgr.insertImages( ((short) 0), imgCmd, xGraphic );

The insertImage() method provided by the XImageManager interface has two parameters. The first one expects a string array of commands, and the second one a sequence of XGraphic elements. The sequence can be created by the getImages() method, which expects a string array of URLs. The command strings have to be in line with the XGraphic elements.

The property UIName of the UIElementSettings Service specifies the name of the toolbar, which is needed to get the toolbar displayed in the StarOffice View menu.

XPropertySet xToolbarProperties = (XPropertySet)
        UnoRuntime.queryInterface( XPropertySet.class,
        xNewToolbarFactory );
        xToolbarProperties.setPropertyValue("UIName", "SunDC Toolbar" );

The PropertyValue structure is the same as for a menu item. To add buttons to the toolbar with the InsertByIndex() method, follow the code that shows how to retrieve the XIndexContainer() interface.

XSingleComponentFactory xCfgMgrFactory = (XSingleComponentFactory)
       UnoRuntime.queryInterface(
                                   XSingleComponentFactory.class,
                                   xNewToolbarFactory );

XIndexContainer xCfgMgrContainer = (XIndexContainer)

     UnoRuntime.queryInterface( XIndexContainer.class,
                                 xNewToolbarFactory );

xCfgMgrContainer.insertByIndex( 0, toolbarItemProperty );

This completes the definition of a new toolbar. The next step makes the toolbar available to the other toolbars. In contrast to the ReplaceSettings() method used for updating existing toolbars and menus, the InsertSettings() method is used to create a new toolbar. Both methods are provided by the XUIConfigurationManager interface.

The new menu and toolbars are not persistent. They disappear when StarOffice is closed. Use the store() method provided by the XUIConfigurationPersistence interface to saves those settings permanently.

This article shows how to create new menus and toolbars using the StarOffice SDK. It also shows you how to integrate these new interfaces in the StarOffice display, and how to make them persistent.

Programming with the StarOffice 8 Software Development Kit
StarOffice Software Development Kit (SDK)
StarOffice/OpenOffice.org Developer Manual
StarOffice/OpenOffice.org Reference help
StarOffice/OpenOffice.org API forum / newsgroup
StarOffice/OpenOffice.org code snippets

Kay Koll is a technical marketing specialist for Desktop Solutions at Sun Microsystems in Hamburg, Germany.