This tutorial will give you a detailed step-by-step insight into a very flexible way to add dynamic popup menus into the OpenOffice.org 2.0.x menu bar. Dynamic popup menus are implemented via UNO using the popup menu controller service. This tutorial will be split into small chapters which describe different aspects of popup menu controllers.

The reader of this tutorial should know the following

The outcome of this tutorial will be an add-on which exchanges the default recent file list with an enhanced version. Hopefully some people will find it useful. May be it encourages other developers to extend it or create extensions using popup menu controllers.

Popup menu controller architecture

Popup menu controllers are used in OpenOffice.org when the content of a popup menu is dynamic (e.g. changes at runtime). Technically OpenOfforg uses the following architecture to integrate popup menu controllers.

The menubar controls all menu items. At activation time the menubar implementation checks once for all menu items if a popup menu controller has been registered for a command. The menubar uses the CommandURL property and queries the PopupMenuControllerFactory service for an associated popup menu controller. The PopupMenuControllerFactory uses the OpenOffice.org configuration to store the association between command URL and popup menu controller. An OpenOffice.org configuration file can easily be provided by extensions. Therefore popup menu controllers are a good way to extend the default OpenOfifce.org menubar. On success the PopupMenuControllerFactory is asked to create an instance of the popup menu controller. The menubar provides vital information about the current context (e.g. a reference to its popup menu, the associated frame) to the popup menu controller at creation time.

OpenOffice.org 2.0.4 uses the following popup menu controllers within the application modules:

Command	Modules	Service	Purpose
.uno:CharFontName	all	com.sun.star.comp.framework.FontMenuController	Provides a popup menu with all supported fonts.
.uno:FontHeight	all	com.sun.star.comp.framework.FontSizeMenuController	Provides a popup menu with all supported font sizes.
.uno:ObjectMenue	all	com.sun.star.comp.framework.ObjectMenuController	Provides a popup menu with all supported commands of an embedded object.
.uno:InsertPageHeader	all	com.sun.star.comp.framework.HeaderMenuController	Provides a popup menu to insert pages headers.
.uno:InsertPageFooter	all	com.sun.star.comp.framework.FooterMenuController	Provides a popup menu to insert page footers.
.uno:ChangeControlType	all	com.sun.star.comp.framework.ControlMenuController	Provides a popup menu to change the control type of a selected form control.
.uno:AvailableToolbars	all	com.sun.star.comp.framework.ToolBarsMenuController	Provides a popup menu to show/hide toolbars.
.uno:ScriptOrganizer	all	com.sun.star.comp.framework.MacrosMenuController	Provides a popup menu with all available scripting languages.
.uno:RecentFileList	all	com.sun.star.comp.framework.RecentFilesMenuController	Provides a popup menu with recently opened files.
.uno:AddDirect	all	com.sun.star.comp.framework.NewMenuController	Provides a popup menu to create document for all available application modules.
.uno:AutoPilotMenu	all	com.sun.star.comp.framework.NewMenuController	Provides a popup menu with all available wizards.

Configuration

The association between command URL and popup menu controller is controlled by an OpenOffice.org configuration file. The default OpenOffice.org configuration file is located at the following configuration path org.openoffice.Office.UI/Controller.xcu. The Controller.xcu controls the association for popup menu, toolbar and statusbar controllers.

[xml] <!DOCTYPE oor:component-schema SYSTEM "../../../../../component-schema.dtd"> <oor:component-schema xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" oor:name="Controller" oor:package="org.openoffice.Office.UI" xml:lang="en-US">


<info>
 <author>CD</author>
 <desc>Contains implementation of popup menu controllers.</desc>
</info>
<templates>
<group oor:name="ControllerType">
 <info>
  <desc>Describes a controller implementation.</desc>
 </info>
 <prop oor:name="Command" oor:type="xs:string">
  <info>
   <desc>Specifies the command name which the controller is bound to.</desc>
  </info>
 </prop>
 <prop oor:name="Module" oor:type="xs:string">
  <info>
   <desc>Specifies the model that the controller is associated with. An empty string matches every module.</desc>
  </info>
 </prop>
 <prop oor:name="Controller" oor:type="xs:string">
  <info>
   <desc>Specifies the UNO service to use for the specified tuple Command and Module</desc>
  </info>
 </prop>
 <prop oor:name="Value" oor:type="xs:string">
  <info>
   <desc>Specifies a controller specific value which is provided to every controller instance during initialization.</desc>
  </info>
  <value/>
 </prop>
</group>

</templates>
<component>

<group oor:name="Registered">
 <info>
  <desc>Contains all registered controllers for user interface elements.</desc>
 </info>
 <set oor:name="PopupMenu" oor:node-type="ControllerType">
  <info>
   <desc>Contains UNO component implementation names that implement popup menu controller which are bound to a command and module name.</desc>
  </info>
 </set>
 <set oor:name="ToolBar" oor:node-type="ControllerType">
  <info>
   <desc>Contains UNO component implementation names that implement toolbar controller which are bound to a command and module name.</desc>
  </info>
 </set>
 <set oor:name="StatusBar" oor:node-type="ControllerType">
  <info>
   <desc>Contains UNO component implementation names that implement status bar controller which are bound to a command and module name.</desc>
  </info>
 </set>
</group>

</component> </oor:component-schema>

The important part of the schema is the group "ControllerType". The group defines an association between a single command URL and a controller implementation.

Property	Type	Description
Command	String	Contains the command URL for which the controller is registered. The UI element implementation uses the command URL to query for controllers.
Module	String	Specifies the module for which the association is active. This allows to use different controller implementations for different modules. An empty entry means active for all modules.
Controller	String	Specifies the implementation name of the controller. The name will be used by the ControllerFactory to create an instance of the controller.
Value	String	Contains controller specific data which will be provided at creation time. It interpretation of the data depends on the controller implementation.

The following snippet is directly taken from the Controller.xcu of OpenOffice.org 2.0.4. It associates the popup menu controller responsible for the font name list to the command URL ".uno:CharFontName". As the controller is available for all application modules the propery "Module" is empty. The controller doesn't use the "Value" property.

[xml]


 ...
 <node oor:name="Registered">
   <node oor:name="PopupMenu">
     <node oor:name="c1" oor:op="replace">
       <prop oor:name="Command">
         <value>.uno:CharFontName</value>
       </prop>
       <prop oor:name="Module">
         <value/>
       </prop>
       <prop oor:name="Controller">
         <value>com.sun.star.comp.framework.FontMenuController</value>
       </prop>
     </node>
 ...

Now that we know how a popup menu controller is registered in the OpenOffice.org configuration environment we can move to the next important part of this tutorial: the UNO services and interfaces involved.

UNO Services and interfaces

A popup menu controller is described by a UNO service called com.sun.star.frame.PopupMenuController. It defines what interfaces must be supported. The following code part shows the UNO IDL description of the service.

[c++] module com { module sun { module star { module frame {

//=============================================================================

/** provides access to a popup menu controller.


   A popup menu controller is used to make special functions available to 
   users, which depend on runtime or context specific conditions.
   A typical example for a popup menu controller can be a recent file list 
   implementation which provides a list of latest files that a user has 
   worked on. This list gets changes consistently during a work session.

   @since OOo 2.0.0


/


service PopupMenuController
{

   //-------------------------------------------------------------------------
   /** supports functions to initialize and update a popup menu controller
       implementation.

       A popup menu controller implementation gets initialized with a 
       com::sun::star::awt::XPopupMenu object. This assures
       that a popup menu controller can be implemented with any UNO based
       language.
   */
   interface com::sun::star::frame::XPopupMenuController;
   
   //-------------------------------------------------------------------------
   /** provides functions to initialize a popup menu controller with 
       specific data which are needed. 
       
       This interface should not directly used. A factory service is responsible to 
       initialize every controller correctly.

       A popup menu controller needs at least two additional arguments
       provided as com::sun::star::beans::PropertyValue:
       
       Frame
         specifies the com::sun::star::frame::XFrame instance to which
         the popup menu controller belongs to.

       CommandURL
         specifies which popup menu controller should be created.

       @see PopupMenuControllerFactory
   */
   interface com::sun::star::lang::XInitialization;

   //-------------------------------------------------------------------------
   /** used to brief the popup menu controller with new status information.

       A popup menu controller makes special functions available to users which normally 
       depend on the state of other data. This interface is used to send this data
       to a controller implementation.
   */
   interface com::sun::star::frame::XStatusListener;

};

}; }; }; };

The service description clearly states that we have to implmenent at least three different UNO interfaces.

com::sun::star::frame::XPopupMenuController

This interface is the central part of every popup menu controller. It's used by the OpenOffice.org menu bar implementation to communicate with the controller.

com::sun::star::lang::XInitialization
com::sun::star::frame::XStatusListener

How to implement a popup menu controller

Now we know which interfaces our popup menu controller must implement.

The next part (How to implement our new recent files list popup menu controller/Reading the configuration to create the history) will follow next week.

Framework/Tutorial/Popup Menu Controller

Contents

Popup menu controller architecture

Configuration

UNO Services and interfaces

How to implement a popup menu controller

Views

Personal tools

Navigation

Search

Tools