Difference between revisions of "Framework/Tutorial/Popup Menu Controller"

From Apache OpenOffice Wiki
Jump to: navigation, search
Line 233: Line 233:
 
   ...
 
   ...
 
</code>
 
</code>
 +
 +
''The next part (How to implement a popup menu controller) will follow next week.
 +
 +
[[Category:Development]]
 +
[[Category:Framework:Tutorial]]

Revision as of 14:26, 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.

Menu-Popupmenu-controller-architecture.png

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

The next part (How to implement a popup menu controller) will follow next week.

Personal tools