Revision as of 14:11, 24 November 2006

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 - Programming with UNO - C++ knowledge

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 OpenOffice.org 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:

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>

<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.

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>
 ...