Framework/Tutorial/Popup Menu Controller
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 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:
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. |
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> ...