Programmatic Control of Menu and Toolbar Items

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Carsten Driesner	July 07, 2004	Draft
Conforms to	
Applies to	framework
Task ID(s)	Parent task: Q-PCD Programmability-5: i20163 i25017, 111899, i6778
Category	

Abstract

This feature should enable 3rd party developers to adapt menu bar and toolbar layouts to their needs. It will make menus and toolbars accessible to UNO developers and provide access to interfaces to insert/remove and modify menu items, popup menus and toolbar items during Office runtime.

i-Team Members

	Name	E-mail Address
Specification Owner	Carsten Driesner (cd)	cd@openoffice.org
User Experience	Matthias Müller-Prove (mmp), Christian Jansen (cj)	mmp@openoffice.org cj@openoffice.org
Development	Carsten Driesner (cd)	cd@openoffice.org
Quality Assurance	Steffen Grund (sg), Thorsten Martens (tm)	sg@openoffice,org, tm@openoffice,org
Documentation		

Approved for Implementation

	Approved by	Date
User Experience	Christian Jansen	February 02, 2004
Development	Mathias Bauer	December 01,2003
Quality Assurance	Steffen Grund	January 26, 2004
Documentation		
String Review	-	-

Document Change History

Rev. Level	Change	Initials	Date
0.1	Initial revision	CD	27.10.03
0.3	Description of major parts of the new design	CD	11.11.03
0.5	Description of the persistence	CD	19.12.03
1.0	Latest draft revision	CD	03.02.04
1.0	Revised last chapter "Maintainance of menus, toolbars and user interface commands"	CD	07.07.04

Contents

Glossary	1

1	Motivation	1

2	Goals	1

3	Requirements and Dependencies	1

3.1	Requirements	1

3.2	Technical Dependencies	2

4	User Scenarios	2

5	Competitive Analyses	2

6	Detailed Specification	3

6.1	Overview	3

6.2	Access Points to the user interface configuration API	4

6.3	Address a single user interface element	9

6.4	User interface configuration API	9

6.5	Persistence	11

6.6	User interface configuration data file format	12

6.7	Maintainance of menus, toolbars and user interface commands	13

7	Future Tasks	19

8	Legal Issues	19

9	Notes	19

10	References	19

Glossary

Term	Description
User interface element	A floating or docked window, toolbar, status bar or menu.
User interface item	A single button within a toolbar or single menu item within a menu bar.
Layout manager	A piece of software which controls the position and size of any user interface element inside the application window. The position and size of an user interface element is controlled by a predefined rule set.
Toolbar	A toolbar is an user interface element which is usually placed along the top of a window and contains a number of buttons that perform common functions which are frequently used.
Status bar	A status bar is an user interface element which is located at the bottom of the window or screen. It displays information about the current application state, like editing mode (insert,overwrite).
Menu bar	A menu bar is an user interface element which is located at the top of the window or screen (Mac). It gives users access to the functions of an application.
User interface configuration file	A XML based file that describes which functions are part of an user interface element and the order of the functions.

Motivation

The menu and toolbar implementation of OpenOffice.org 1,1 and former versions don't allow developers to change them with an UNO API during runtime. They have to copy configuration files to adapt the menu and toolbars to their needs. Developers and ISVs who write new components and applications want to integrate these components into the SO/OOo menu and toolbars. They want to do this programmatically from setup scripts and applications as well as by using configuration tools.

Goals

Provide an UNO API that enables developers to adopt the menu and toolbars to their needs.

Requirements and Dependencies

Requirements

Provide access to menu bar and toolbar layouts from any UNO enabled language.

Support to change, add and remove menu items, popup menus and toolbar items from any UNO enable language.

Support to show/hide menus and toolbars from any UNO enabled language.

Support a way to have dynamic popup menus. The content of the popup menu will be controlled by an UNO based implementation.

Technical Dependencies

This feature is part of the general rework to have a frame based layout manager that manages all the generic user interface elements in a central position.

User Scenarios

There are no user scenarios for this specification.

Competitive Analyses

The main competitor application already has an API to adopt the menu and toolbar layouts to the developers need. It also allows to register handler that are called when a user activates a user interface element. OpenOffice.org supports calling scripting or external code from a menu or toolbar item, but it uses a different concept which does not rely on registered handlers. Instead it is possible to register a arbitrary UNO implementation for a command URL-schema which will be activated whenever the framework implementation detect this kind of command URL. Although this is a different approach it is possible to call user-specific code from any user interface element.

Detailed Specification

Overview

The following illustration shows the main design and the integration of the user interface configuration API into the OpenOffice.org architecture.

The grey rectangles are already part of the OpenOffice.org architecture and the blue rectangles are parts of the new user interface configuration API.

Access Points to the user interface configuration API

The new implementation will provide access to the user interface definitions of menus and toolbars at different access points depending on the purpose. The following table gives an overview which access points will be available and for what purposes they can be used.

Access Point	Purpose
Central user interface configuration manager created from UNO service manager to retrieve a module user interface configuration manager.	Make changes to menu and/or toolbars and store them persistently to the module storage. There is only one user interface configuration manager for every module.
User interface configuration manager retrieved from the document model	Make changes to menu and/or toolbars and store them persistently to the document storage.
Layout manager retrieved from the frame	Make changes to available menu and/or toolbars persistently or without storing the changes depending on the property “Persistence” of a configurable user interface element. Changes are always written back to the location where the configuration data has been retrieved. The layout manager controls the user interface elements and is responsible for their visible layout. Therefor the availability of user interface elements, especially of toolbars, depend on the context of the application module.

Module user interface configuration manager

A module user interface configuration manager can be retrieved from the drafts::com::sun::star::ui::ModuleUIConfigurationManagerSupplier service which can be created with the OpenOffice.org service manager using its service specifier.

service ModuleUIConfigurationManagerSupplier
{
/** controls module based user interface configuration managers.

<p>
There can only exists one user interface configuration manager for
a module. A user interface configuration manager supports to get and set
user interface configuration data for configurable user interface elements.
@see ConfigurableUIElement
@see XUIConfigurationManager
</p>
*/
interface XModuleUIConfigurationManagerSupplier;
};

The ModuleUIConfigurationManagerSupplier service supports the interface XModuleUIConfigurationManagerSupplier to retrieve a module based user interface configuration.

interface XModuleUIConfigurationManagerSupplier : ::com::sun::star::uno::XInterface
{
/** returns the requested module based user interface configuration manager.
@param ModuleIdentifier
a module identifier which identifies an OpenOffice.org module. The
module can be retrieved from the
<type scope=drafts::com::sun::star::frame>ModuleManager</type> service.
@returns
an object implementing
<type scope="::drafts::com::sun::star::ui">ModuleUIConfigurationManager</type>
service. If the provided module identifier is unknown a
<type scope="com::sun::star::container">NoSuchElementException</type> is thrown.
*/
XUIConfigurationManager getUIConfigurationManager( [in] string ModuleIdentifier )
raises ( com::sun::star::container::NoSuchElementException );
};

Document user interface configuration manager

The model of a component attached to a frame can be retrieved with the getModel() function from the controller of the frame. The model supports the interface XUIConfigurationManagerSupplier where the user interface configuration manager of the document can be retrieved. The user interface

interface XUIConfigurationManagerSupplier : ::com::sun::star::uno::XInterface
{
/** returns the user interface configuration manager related to the object.
@returns
an object implementing <type
scope="::drafts::com::sun::star::ui">UIConfigurationManager</type> service.
*/
XUIConfigurationManager getUIConfigurationManager();
};

Layout manager

The layout manager can be retrieved from a frame as the property “LayoutManager”. The layout manager supports to retrieve all currently instanciated user interface elements. It is also possible to retrieve a single user interface element.

A layout manager controls the visibility, size and position of the user interface elements.

The following interface drafts::com::sun::star::frame::XLayoutManager is central access point to the current user interface elements of a frame.

interface XLayoutManager : com::sun::star::uno::XInterface

{

/** attaches a <type>com::sun::star::frame::XFrame</type> to a layout manager.

@param Frame

specifies the frame that should be attached to the layout manager

<p>

A layout manager needs a <type>com::sun::star::frame::XFrame</type> to be

able to work. Without a it no user interface elements can be created.

</p>

*/

void attachFrame( [in] com::sun::star::frame::XFrame Frame );

/** resets the layout manager and all its internal user interface elements.

<p>

All user interface elements will be destroyed and

</p>

*/

void reset();

/** provides the current docking area size of the layout manager.

@return

The <type>com::sun::star::awt::Rectangle</type> contains pixel values. The

members of <type>com::sun::star::awt::Rectangle</type> are filled as following:

<ul>

<li>X = docking area on left side (in pixel)</li>

<li>Y = docking area on top side (in pixel)</li>

<li>Width = docking area on right side (in pixel)</li>

<li>Height = docking area on bottom side (in pixel)</li>

</ul>

*/

com::sun::star::awt::Rectangle getCurrentDockingArea();

/** sets a docking area acceptor that controls the border space of the frame's

container window.

@param xDockingAreaAcceptor

a docking area acceptor which controls the border space of frame's container window.

<p>

A docking area acceptor decides if the layout manager can use requested border space for

docking windows. If the acceptor denies the requested space the layout manager

automatically set all docked windows into floating state and will not use this space for

docking.<br/> After setting a docking area acceptor the object is owned by the layout

manager. It is not allowed to dispose this object, it will be destroyed on reference

count!

</p>

*/

void setDockingAreaAcceptor( [in] drafts::com::sun::star::ui::XDockingAreaAcceptor xDockingAreaAcceptor );

/** creates a new user interface element.

@param ResourceURL

specifies which user interface element should be created. A resourcce URL must meet

the following syntax: "private:resource/<type>/<name>. It is only allowed to use

ascii characters for type and name.

*/

void createElement( [in] string ResourceURL );

/** destroys a user interface element.

@param ResourceURL

specifies which user interface element should be destroyed. A resourcce URL must meet

the following syntax: "private:resource/<type>/<name>. It is only allowed to use

ascii characters for type and name.

*/

void destroyElement( [in] string ResourceURL );

/** retrieves a user interface element which has been created before.

@param ResourceURL

specifies which user interface element should be retrieved. A resourcce URL must meet

the following syntax: "private:resource/<type>/<name>. It is only allowed to use

ascii characters for type and name.

<p>

The layout manager instance is owner of the returned user interface element. That means

that the life time of the user interface element is controlled by the layout manager. It

can be disposed at every time!

</p>

*/

drafts::com::sun::star::ui::XUIElement getElement( [in] string ResourceURL );

/** retrieves all user interface elements which are currently instanciated.

@return

a sequence of user interface elements providing

<type scope="drafts::com::sun::star::ui">XUIElement</type> interface.

<p>

The layout manager instance is owner of the returned user interface elements. That means

that the life time of the user interface elements is controlled by the layout manager.

They can be disposed at every time!

</p>

*/

sequence< drafts::com::sun::star::ui::XUIElement > getElements();

/** shows a user interface element.

@param ResourceURL

specifies which user interface element should be shown. A resourcce URL must meet the

following syntax: "private:resource/<type>/<name>. It is only allowed to use ascii

characters for type and name.

@return

returns <TRUE/> if the user interface element has been shown, otherwise <FALSE/> will

be returned.

*/

boolean showElement( [in] string ResourceURL );

/** hides a user interface element.

@param ResourceURL

specifies which user interface element should be hidden. A resourcce URL must meet

the following syntax: "private:resource/<type>/<name>. It is only allowed to use

ascii characters for type and name.

@return

returns <TRUE/> if the user interface element has been hidden, otherwise <FALSE/>

will be returned.

*/

boolean hideElement( [in] string ResourceURL );

/** docks a window based user interface element to a specified docking area.

@param ResourceURL

specifies which user interface element should be docked. A resourcce URL must

meet the following syntax: "private:resource/<type>/<name>. It is only allowed to use
ascii characters for type and name.

@param DockingArea

specifies to on which docking area the windows based user interface element should

docked.

@param Pos

specifies the position inside the docking area.

@return

returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/>

will be returned.

@see drafts::com::sun::star::ui::DockingArea

*/

boolean dockWindow( [in] string ResourceURL, [in] drafts::com::sun::star::ui::DockingArea

DockingArea, [in] com::sun::star::awt::Point Pos );

/** forces a window based user interface element to float.

@param ResourceURL

specifies which user interface element should be float. A resourcce URL must meet the

following syntax: "private:resource/<type>/<name>. It is only allowed to use ascii

characters for type and name.

@return

returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/>

will be returned.

*/

boolean floatWindow( [in] string ResourceURL );

/** sets a new size for a window based user interface element.

@param ResourceURL

specifies which user interface element should be resized. A resourcce URL must meet

the following syntax: "private:resource/<type>/<name>. It is only allowed to use

ascii characters for type and name.

@param Size

specifies the new size in pixel.

<p>

It is up to the layout manager to decide if the user interface element can be resized.

The new size can be retrieved by calling <member>getElementSize</member>.

</p>

*/

void setElementSize( [in] string ResourceURL, [in] com::sun::star::awt::Size Size );

/** sets a new position for a window based user interface element.

@param ResourceURL

specifies which user interface element should be moved. A resourcce URL must meet the

following syntax: "private:resource/<type>/<name>. It is only allowed to use ascii

characters for type and name.

@param Pos

specifies the new position in pixel.

<p>

It is up to the layout manager to decide if the user interface element can be moved.

The new position can be retrieved by calling <member>getElementPos</member>.

</p>

*/

void setElementPos( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos );

/** sets a new position and size for a window based user interface element.

@param ResourceURL

specifies which user interface element should be moved and resized. A resourcce URL

must meet the following syntax: "private:resource/<type>/<name>. It is only allowed

to use ascii characters for type and name.

@param Pos

specifies the new position in pixel.

@param Size

specifies the new position in pixel.

<p>

It is up to the layout manager to decide if the user interface element can be moved and

resized. The new position and size can be retrieved by calling

<member>getElementPos</member> and <member>getElementSize</member>.

</p>

*/

void setElementPosSize( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos,

[in] com::sun::star::awt::Size Size );

/** retrieves the current visibility state of a window based user interface element.

@param ResourceURL

specifies for which user interface element the visibility state should be retrieved.

A resource URL must meet the following syntax: "private:resource/<type>/<name>. It

is only allowed to use ascii characters for type and name.

@return

<TRUE/> if the user interface element is visible, otherwise <FALSE/>.

*/

boolean isElementVisible( [in] string ResourceURL );

/** retrieves the current floating state of a window based user interface element.

@param ResourceURL

specifies for which user interface element the floating state should be retrieved.

A resource URL must meet the following syntax: "private:resource/<type>/<name>. It is

only allowed to use ascii characters for type and

name.

@return

<TRUE/> if the user interface element is floating, otherwise <FALSE/>.

*/

boolean isElementFloating( [in] string ResourceURL );

/** retrieves the current docking state of a window based user interface element.

@param ResourceURL

specifies for which user interface element the docking state should be retrieved. A

resource URL must meet the following syntax: "private:resource/<type>/<name>. It is

only allowed to use ascii characters for type and name.

@return

<TRUE/> if the user interface element is docked, otherwise <FALSE/>.

*/

boolean isElementDocked( [in] string ResourceURL );

/** retrieves the current size of a window based user interface element.

@param ResourceURL

specifies for which user interface element the current size should be retrieved. A

resource URL must meet the following syntax: "private:resource/<type>/<name>. It is

only allowed to use ascii characters for type and name.

@return

the size in pixel of the user interface element. A non-window based user

interface element provides a zero size.

*/

com::sun::star::awt::Size getElementSize( [in] string ResourceURL );

/** retrieves the current pixel position of a window based user interface element.

@param ResourceURL

specifies for which user interface element the current position should be retrieved.

A resource URL must meet the following syntax: "private:resource/<type>/<name>. It is

only allowed to use ascii characters for type and name.

@return

the size in pixel of the user interface element. A non-window based user interface

element provides a zero size.

*/

com::sun::star::awt::Point getElementPos( [in] string ResourceURL );

/** prohibit all layout updates until unlock is called again.

<p>

This call can be used to speed up the creation process of serveral user interface

elements. Otherwise the layout manager would calculate the layout for every creation.

</p>

*/

void lock();

/** permit layout updates again.

<p>

This function should be called to permit layout updates. The layout manager starts to

calculate the new layout after this call.

</p>

*/

void unlock();

/** forces a complete new layouting of all user interface elements.

*/

void doLayout();

};

Address a single user interface element

The implementation uses a new URL schema to address any user interface element.

private:resource/<user interface element type>/<user interface element name>

User interface element types

Specifies to which type the request user interface element belongs to. The following user interface element types are defined.

“toolbar”

“menubar”

User interface element name

A user interface element name must specify unequivocally a single user interface element within the same type class of a module or document. The name is used to address the user interface definition file. For example, a user interface definition of a toolbar named “tablebar” should only exists once.
User-defined toolbars must start with “user_” following a unique name so they can be identified as user-defined. User-defined toolbars are not context sensitive an therefor are automatically created and shown by a layout manager instance.

The following example shows how to address a menu bar of an application module.

private:resource/menubar/menubar

There is no need to specify the module of a user interface element as every access point has this context information.

User interface configuration API

The user interface configuration API uses a com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > to describe a single user interface item. The following table shows which properties are defined and what's their purpose.

Property	Type	Description	Context
Type	short	Specifies which type the item belongs to. This can be a normal item, like a button or a separator.	All
Label	string	Specifies the text of the user interface item, like a label of a menu item.	All
CommandURL	string	Specifies which function should be executed.	All
HelpURL	string	Contains an URL that points to the a help text.	All
[optional] Style	short	Different styles which influence the appearance of an item and its behavior.	Toolbar/status bar
[optional] Offset	short	Specifies a pixel distance by which output text is shifted on the x-axis	Status bar
[optional] ItemDescriptorContainer	XIndexAccess	Contains all items of a optional sub menu.	Menu
[optional] IsVisible	boolean	Specifies if this item is visible or not.	Toolbar/status bar
[optional] Width	short	Specifies the width (in pixel) of the item inside its parent user interface element.	Status bar

[optional] This property is only defined in a special context, see Context column.

The structure of a user interface element is described by the service drafts::com::sun::star::ui::service UIElementSettings. It supports a com::sun::star::container::XIndexContainer which stores the items.

service UIElementSettings
{
/** provides access to the structure of the user interface element.
<p>
The container contains the items of the user interface element. Every
item is stored as a sequence of <type scope="com::sun::star::beans">PropertyValue</type>.
The properties insides the sequence are defined by the service <type
scope="drafts::com::sun::star::ui">ItemDescriptor</type>.
@see drafts::com::sun::star::ui::ItemDescriptor
@see drafts::com::sun::star::ui::ItemType
@see drafts::com::sun::star::ui::ItemStyle
</p>
*/

interface ::com::sun::star::container::XIndexAccess;
/** determine an optional user interface name of the user interface element.

<p>
A toolbar can show a its user interface name on the window title, when it is in floating	mode.
</p>
*/

[optional, property] string UIName;
};

The container interface supports to retrieve, remove, replace and insert of user interface element items.

Dynamic popup menus.

Dynamic popup menus. The content of the popup menu will be controlled by an UNO based implementation. Every implementation must implement the service drafts::com::sun::star::frame::PopupMenuController.

service PopupMenuController
{
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.
<p>
A popup menu controller implementation gets initialized with a
<type scope="com::sun::star::awt>XPopupMenu</type> object. This assures
that a popup menu controller can be implemented with any UNO based
language.
</p>
*/
interface drafts::com::sun::star::frame::XPopupMenuController;
//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

<p>A popup menu controller needs at least two additional arguments
provided as <type scope="com::sun::star::beans">PropertyValue</type>:
<ul>
<li><b>Frame</b><br>specifies the <type scope="com::sun::star::frame">XFrame</type>
instance to which the popup menu controller belongs to.</li>
<li><b>CommandURL</b><br>specifies which popup menu controller should be
created.</li>
</ul>

This interface should not directly used. A factory service creates and initialize
instances with the correct data.

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

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

<p>
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.
</p>
*/
interface com::sun::star::frame::XStatusListener;
};

The menu bar implementation of OpenOffice.org creates PopupMenuController on demand when a registered controller is found within a menu bar. The design of the interfaces gives every implementation as much freedom as possible. The interface drafts::com::sun::star::frame::XPopupMenuController is used by the OpenOffice.org menu bar implementation to control a popup menu controller.

interface XPopupMenuController : com::sun::star::uno::XInterface

{

/** provides a <type scope="com::sun::star::awt">XPopupMenu</type> to a

popup menu controller implementation. The controller must fill this

popup menu with its functions.

@param PopupMenu

An empty popup menu that must be filled by the popup menu controller.

*/

void setPopupMenu( [in] com::sun::star::awt::XPopupMenu PopupMenu );

/** briefs the popup menu controller to update the contents of the provided

popup menu to reflect the current state.

<p>A controller should <b>never</b> update the popup menu structure on its

own to prevent performance problems. A better way would be that a controller

registers itself as status listener to for a command URL and immediately

deregister after that. Therefor status updates will not be send regularly

for a non visible popup menu.

</p>

*/

void updatePopupMenu();

};

Persistence

The persistence of the user interface element settings is controlled by user interface configuration managers. They provide an interface to saves changes to their associated storage and to check their current state. Every user interface configuration manager supports the interface drafts::com::sun::star::ui::XUIConfigurationPersistence:

interface XUIConfigurationPersistence : ::com::sun::star::uno::XInterface

{

/** reloads the configuration data from the storage and reinitialize the user
interface configuration manager instance with the data

<p>

It is up to the implementation if it defers the first loading process until the

first data request using <type>XUIConfigurationManager</type> interface.

</p>

*/

void reload() raises ( ::com::sun::star::uno::Exception );

/** stores the configuration data to the storage provided by <member>setStorage</member>
from the storage and initialize the user interface configuration manager instance with
the newly data. This call can throw an <type
scope="com::sun::star::io">IOException</type> if <member>store</member> cannot store
its data into the internal storage.

*/

void store() raises ( ::com::sun::star::uno::Exception );

/** stores the configuration data to the provided storage, ignoring the previously set

storage by <member>setStorage</member>. Can be used to make copy of the current
user interface configuration data to another storage. This call will throw an
<type scope="com::sun::star::io">IOException</type> if the provided storage is in
read-only mode.

@param Storage

all configuration data will be stored to this storage.

*/

void storeToStorage( [in] ::com::sun::star::embed::XStorage Storage )
raises ( ::com::sun::star::uno::Exception );

/** provides the current modify state of the configuration manager instance.

@return

<TRUE/> if the configuration manager has changed since the last

<member>store</member> call. <FALSE/> if the configuration manager has not been
changed.

*/

boolean isModified();

/** provides the current read-only state of the user configuration manager. Storing a

user interface configuration to a read-only storage is not possible. A read-only

configuration manager instance will also not support any changes to its configuration

settings.

@return

<TRUE/> if the configuration manager storage is read-only otherwise <FALSE/>.

*/

boolean isReadOnly();

};

User interface configuration data file format

The menu and toolbar configuration file format will be the same as for OpenOffice.org 1.0.x and OpenOffice.org 1.1. The state information about a toolbar is not stored anymore in a document. This should prevent usage problems that other users might have if they load a document with user interface configuration data inside.

As the behavior and structure of toolbars and menus will change to have a better user experience all data is stored in a different substorage inside a document. Another reason are the new command URL's which describe a menu item or toolbar item command. They are not downward compatible with OpenOffice.org 1.1 which uses slot ID's for that purpose.

Within a normal OpenOffice.org installation the default user interface configuration settings are not retrieved anymore from resource files, but from a zip package below $(share)/config/soffice.cfg, called uiconfig.zip. Every OpenOffice.org module has its own sub folder below within the zip package where its default user interface element settings are stored. The naming of sub folders follow this schema:
<short module identifier>/<user interface element type>/<unique user interface element name>.

The short module identifier, user interface element type and unique user interface element name must consists of ascii characters only - additionally '/', '?', %' and '&' characters are also not allowed within these identifier or names!

The following modules (from the user interface point of view) are defined:

Module	Short module identifier
OpenOffice.org Writer	swriter
OpenOffice.org Writer/Web	sweb
OpenOffice.org Writer/Globaldocument	sglobal
OpenOffice.org Calc	scalc
OpenOffice.org Draw	sdraw
OpenOffice.org Impress	simpress
OpenOffice.org Math	smath
OpenOffice.org Chart	schart
OpenOffice.org Bibliography	sbibliography
OpenOffice.org BasicIDE	BasicIDE
OpenOffice.org Database QueryDesign	dbquery
OpenOffice.org Database TableDesign	dbtable
OpenOffice.org Database RelationDesign	dbrelation
OpenOffice.org StartModule (Backing componet)	StartModule

Maintainance of menus, toolbars and user interface commands

The resource file system which stored the user interface configuration data will become obsolete for most user interface elements of Openoffice.org 2.0. As described in chapter 6.6 User interface configuration data format a XML based file format is used for this, which has already been part of Openoffice.org 1.1. This chapter describes how to maintain the necessary files to add/replace and remove new menu items/toolbar items and user interface commands.

Every OpenOffice.org module has a configuration file where all supported user interface commands are stored with their internationalized user interface command label. The label is used to set the correct text of a menu item. The implementation also creates a short command description from the label (without mnemonic and subsequent ...) which is used by toolbar items without an image and the short bubble help.

The configuration files are located at: <Office installation>/share/registry/org/openoffice/Office/UI. The schema definition of these configuration files can be found below:

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-schema oor:name="GenericCommands" oor:package="org.openoffice.Office.UI" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<templates>

<group oor:name="LabelType">

<prop oor:name="Label" oor:type="xs:string" oor:localized="true"/>

<prop oor:name="Properties" oor:type="xs:int">

<value>0</value>

</prop>

</group>

</templates>

<component>

<group oor:name="UserInterface">

<set oor:name="Commands" oor:node-type="LabelType"/>

<set oor:name="Popups" oor:node-type="LabelType"/>

</group>

</component>

</oor:component-schema>

A LabelType consists of two properties.

-Label
A label contains the menu label text with an optional mnemonic (~) and possible “...” characters at the end to specify that a dialog will follow. The Office automatically creates a quick help text out of the label string, it removes the mnemonic and “...” characters at the end.

- Properties
A sal_Int32 type which specifies a bit field to store additional information about the command.
Bit 0 = The command has an associated image. The Office image manager tries to retrieve an image for this command.
Bit 1 = Image must be mirrored in CTL/vertical text contexts.
Bit 2 = Image must be rotated in CTL/vertical text contexts.

A command configuration file has two sets which store different information. Commands which can be executed must be added to the “Commands” set. To support the definition of popup menu labels and to have a unique identifier for every popup-menu there is a second set called “Popups”. Here only labels for popup-menus should be defined, no real command is allowed to be placed here!

The following cutout shows the definition of the generic user interface command “.uno:TransformDialog”.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:name="GenericCommands" oor:package="org.openoffice.Office.UI" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="UserInterface">

<node oor:name="Commands">

<node oor:name=".uno:JustifyPara" oor:op="replace">

<prop oor:name="Label" oor:type="xs:string">

<value xml:lang="de">Blocksatz</value>

<value xml:lang="en-US">Justified</value>

...

</prop>

<prop oor:name="Properties" oor:type="xs:int">

<value>7</value>

</prop>

</node>

...
</node>
<node oor:name=”Popup”>

...

</node>

</node>

</oor:component-data>

A complete list of the OpenOffice.org modules and their configuration files.

Module	Short module identifier	Configuration files
OpenOffice.org Writer	swriter	WriterCommands.xcu WriterWindowState.xcu
OpenOffice.org Writer/Web	sweb	WriterCommands.xcu WriterWebWindowState.xcu
OpenOffice.org Writer/Globaldocument	sglobal	WriterCommands.xcu WriterGlobalWindowState.xcu
OpenOffice.org Calc	scalc	CalcCommands.xcu CalcWindowState.xcu
OpenOffice.org Draw	sdraw	DrawImpressCommands.xcu DrawWindowState.xcu
OpenOffice.org Impress	simpress	DrawImpressCommands.xcu ImpressWindowState.xcu
OpenOffice.org Math	smath	MathCommands.xcu MathWindowState.xcu
OpenOffice.org Chart	schart	ChartCommands.xcu ChartWindowState.xcu
OpenOffice.org Bibliography	sbibliography	BibliographyCommands.xcu BibliographyWindowState.xcu
OpenOffice.org BasicIDE	BasicIDE	BasicIDECommands.xcu BasicIDEWindowState.xcu
OpenOffice.org Database QueryDesign	dbquery	DbuCommands.xcu DbQueryWindowState.xcu
OpenOffice.org Database TableDesign	dbtable	DbuCommands.xcu DbTableWindowState.xcu
OpenOffice.org Database RelationDesign	dbrelation	DbuCommands.xcu DbRelationWindowState.xcu
OpenOffice.org StartModule (Backing componet)	StartModule	StartModuleCommands.xcu StartModuleWindowState.xcu
Openoffice.org Generic commands	*	GenericCommands.xcu -

* The generic commands file is part of every OpenOffice.org module. It cannot be identified as an own module.

The association between module and user interface commands description/window state file is done within the /org/openoffice/Setup.xcu configuration file. Every installed module has its own node within the group “Factories”. The following cutout shows as an example the definition of the OpenOffice.org Chart module:

...

<node oor:name="Factories">

<node oor:name="com.sun.star.chart.ChartDocument" oor:op="replace">

<prop oor:name="ooSetupFactoryCommandConfigRef" oor:type="xs:string">

<value>ChartCommands</value>

</prop>

<prop oor:name="ooSetupFactoryEmptyDocumentURL" oor:type="xs:string">

<value>private:factory/schart</value>

</prop>

<prop oor:name="ooSetupFactoryIcon" oor:type="xs:int">

<value>13</value>

</prop>

<prop oor:name="ooSetupFactoryShortName" oor:type="xs:string">

<value>schart</value>

</prop>

<prop oor:name="ooSetupFactoryTemplateFile" oor:type="xs:string">

<value/>

</prop>

<prop oor:name="ooSetupFactoryWindowAttributes" oor:type="xs:string">

<value/>

</prop>

<prop oor:name="ooSetupFactoryWindowStateConfigRef" oor:type="xs:string">

<value>ChartWindowState</value>

</prop>

</node>

...

The property “ooSetupFactoryCommandConfigRef” contains the reference to the associated user interface commands description file. The property “ooSetupFactoryWindowStateConfigRef” contains the reference to the associated window state file. The extension “.xcu” must be omitted for both properties. The entries of Setup.xcu are written during installation.

A window state configuration file has the following structure:

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

<desc xml:lang="en-US">Contains state information of all dockable user interface elements based on a Window class which belongs to the Writer text module.</desc

</info>
<import oor:component="org.openoffice.Office.UI.WindowState"/>
<uses oor:component="org.openoffice.Office.UI.WindowState"/>
<templates/>
<component>
<group oor:name="UIElements">
<info>

<desc xml:lang="en-US">Contains user interface element state data specific for the Writer text module."</desc>

</info>
<set oor:name="States" oor:node-type="WindowStateType" oor:component="org.openoffice.Office.UI.WindowState">
<info>
<desc xml:lang="en-US">Contains states of all known dockable user interface elements of the Writer text module."</desc>
</info>
</set>
</group>
</component>
</oor:component-schema>

It uses the following template schema which defines a group that specifies several properties of a single toolbar.

<!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="WindowState" oor:package="org.openoffice.Office.UI" xml:lang="en-US">
<info>
<author>CD</author>
<desc xml:lang="en-US">Contains state information of all dockable user interface elements based on a Window class.</desc>
</info>
<templates>
<group oor:name="WindowStateType">
<info>
<desc xml:lang="en-US">Provides a mapping between commands and their textual representation on the user interface.</desc>
</info>
<prop oor:name="Locked" oor:type="xs:boolean">
<info>
<desc xml:lang="en-US">A locked user interface element cannot be moved or undocked by the user. This property is only active when the user interface element is in a docked state.</desc>
</info>
</prop>
<prop oor:name="Docked" oor:type="xs:boolean">
<info>
<desc xml:lang="en-US">Specifies if the user interface element is currently docked.</desc>
</info>
</prop>
<prop oor:name="Visible" oor:type="xs:boolean">
<info>
<desc xml:lang="en-US">Specifies if the user interface element is visible.</desc>
</info>
</prop>
<prop oor:name="DockingArea" oor:type="xs:int">
<info>
<desc xml:lang="en-US">Specifies the docking area to which a user interface element belongs to. Only valid if 'Docked' is true. Top docking area=0, bottom=1, left=2, right=3.</desc>
</info>
</prop>
<prop oor:name="DockPos" oor:type="xs:string">
<info>
<desc xml:lang="en-US">Specifies the position of a docked user interface element. For top/bottom docked elements X describes a pixel position and Y the row number, left/right docked elements uses X for the column and Y for the pixel position. X and Y coordinates must be splitted by an comma.</desc>
</info>
</prop>
<prop oor:name="DockSize" oor:type="xs:string">
<info>
<desc xml:lang="en-US">Specifies the size of a docked user interface element in pixel. The real size can differ if the layout manager decides to resize it due to current circumenstances. Width and height must be splitted by a comma.</desc>
</info>
</prop>
<prop oor:name="Pos" oor:type="xs:string">
<info>
<desc xml:lang="en-US">Specifies the position of a floating user interface element in pixel. X and Y coordinates must be splitted by an comma and are relative to the document frame.</desc>
</info>
</prop>
<prop oor:name="Size" oor:type="xs:string">
<info>
<desc xml:lang="en-US">Specifies the size of a floating user interface element in pixel. The real size can differ if the layout manager decides to resize it due to current circumenstances. Width and height must be splitted by an comma.</desc>
</info>
</prop>
<prop oor:name="UIName" oor:type="xs:string" oor:localized="true">
<info>
<desc xml:lang="en-US">Specifies the user interface element name. It is used for floating user interface elements to set the title and for the bubble help.</desc>
</info>
</prop>
<prop oor:name="InternalState" oor:type="xs:int">
<info>
<desc xml:lang="en-US">Specifies an internal state for the user interface element. Please don't change this value it describes an internal value.</desc>
</info>
</prop>
<prop oor:name="Style" oor:type="xs:int">
<info>
<desc xml:lang="en-US">Specifies the style of a toolbar. This property is only used by toolbar user interface elements.</desc>
</info>
</prop>
</group>
</templates>
<component/>
</oor:component-schema>

The definition of every user interface elements of an OpenOffice.org module is stored within the project of the module. The XML basesd configuration files can be found at <project>/uiconfig/<short module identifier>/<user interface element type>/<user interface element name>. For example the OpenOffice.org Writer/Web menu bar can be found at: sw/uiconfig/sweb/menubar/menubar.xml.

Add, replace and remove a command visible in the User Interface

A sfx2 based Openoffice.org module should obtain a new slot ID and creates a SID_<COMMAND> definition for it (This is also true for non-sfx2 based modules which wants to create a new global command). It depends on the new command if it is part of the generic commands or only dependent on a single module. The slot must be defined within a SDI file of the chosen project. Generic commands can be part of the sfx2 or svx based SDI files. A module based command must be part of a respective module based SDI file. A already defined command definition can be used as a template, but must be carefully adapted. A very important step is to assign a new command name to the created user interface command. It must be at least unique within the generic and module based configuration file. Please keep in mind that command definitions are case-insensitve and should be carefully chosen. The command cannot be changed after release as it is also part of the dispatch API.

A user interface command must at least set one of the entries AccelConfig, MenuConfig, StatusBarConfig or ToolBoxConfig to true. Otherwise the command cannot be configured to a the respective user interface element. A SfxSlotInfo entry must be part of the definition where a short user interface description is made. The SfxSlotInfo can be become obsolete in the future this is not decided yet. The slot itself must be added to the correct shell. As the new command can also be part of the menu bar or a toolbar we have to add a new entry within the respective configuration file GenericCommands.xcu or the module dependent configuration file. This depends on the command itself. If the command should be part of the menu bar or a toolbar the command must be added to the XML based configuration file within the module's project.

Images

If the command have images you have to do the following additional steps:

Rename all your images to the following schema:

sc_<commandname> for small color images

lc_<commandname> for large color images

sch_<commandname> for small highcontrast images

lch_<commandname> for large highcontrast images

Copy the files to the following directories: res/commandimagelist, so_res/commandimagelist. If you work on a CWS you have to cwsadd these folders.

Add a prop node called “Properties” to the command xcu file and set the integer value to the needed value. Please read the section before where this property node is explained.

If you want to build your CWS you must also add the “framework” project to your CWS. You only need to do a dmake in the util folder to create a commandimagelist.ilst file. It contains the list of all image files within the commandimagelist folder of res and so_res.

Please don't use the old schema sc<number> as it is outdated and all images using this schema and are related to toolbars or menus will be removed. Their use is deprecated and only the above

Adding a new toolbar

There are some additional steps necessary if you want to add a new toolbar to the Office. There are two possible situations which must be handled:

Adding a shell based toolbar

A shell based toolbar will be opened/closed automatically by sfx2/framework code. Whenever the shell is pushed to the shell stack a open/close command is triggered at the framework based layout manager. As the sfx2 is the starting point for the open/close command the toolbar must be registered at the shell. You also need a unqiue identifier for your toolbar (in the past this was also the resource ID for the toolbar). The sfx has a mapping table which can be found in the file: sfx2/source/appl/workwin.cxx. It starts with the following lines:
static const ResIdToResName pToolBarResToName[] =
{
{ 558, "fullscreenbar" },
{ 560, "standardbar", },
{ 18003, "formsnavigationbar" },
...
{ 25000, “newtoolbar” }
};
You have to add a line which maps the unique identifier of your toolbar to the new internal toolbar name which also defines the xml filename which contains the structure data of the toolbar. You have to create the xml file and define the toolbar items within your toolbar. If your new shell is used by more than one application module you have to copy the xml file to the uiconfig folder of all dependent modules. The UI name for the toolbar must be specified within the window state configuration file of every module that uses the toolbar. The following example specifies the UI name for a new toolbar called “newtoolbar”:

<node oor:name="private:resource/toolbar/newtoolbar" oor:op="replace">
<prop oor:name="UIName" oor:type="xs:string">
<value xml:lang="en-US">My new toolbar</value>
<value xml:lang="de">Meine neue Toolbar</value>
</prop>
</node>

Adding a non-shell based toolbar

A non-shell based toolbar can be defined without adapting any sfx2/shell based code. You have to define a unique internal name for toolbar, e.g newtoolbar. Create a xml file that specifies which commands are part of the toolbar. Copy the toolbar xml file to the application module projects that must have access to it (normally there exists a folder called “uiconfig” in every application project).
The UI name for the toolbar must be specified within the window state configuration file of every module that uses the toolbar. The following example specifies the UI name for a new toolbar called “newtoolbar”:

<node oor:name="private:resource/toolbar/newtoolbar" oor:op="replace">
<prop oor:name="UIName" oor:type="xs:string">
<value xml:lang="en-US">My new toolbar</value>
<value xml:lang="de">Meine neue Toolbar</value>
</prop>
</node>

Future Tasks

Legal Issues

Notes

<Questions will arise during the writing of the specification. State these in here.>

References

The new toolbar specification for OpenOffice.org 2.0:
See http://specs.openoffice.org/ui_in_general/toolbar_concept/openoffice_org_toolbar_spec.sxw

The XML based file format description of use interface configuration
See http://xml.openoffice.org/xml_specification.pdf

<Required – This paragraphs gives the audience idea of what to aspect from this document. It should be described shortly what problem will be solved.>

The source of software product implementation and change is the I-Team (Implementation Team). I-Teams are typically comprised of people who have skills in the areas of Product Marketing, Development Engineering, Technical Publications, and Test Engineering. I-Teams define the features or set of changes (based on input from SCs, customers, Engineering, or Marketing), plan the implementation project, perform the implementation and testing...

<Required - List all error conditions, and the action the system takes about them. If an alert box comes up, which kind is it? Include exact text of messages, or say what points need to be covered. Error Messages need a string list>

<Recommended - If there are features which couldn't be implemented but have to be implemented in the future. State these in here with a description why the feature couldn't be implemented right now.>

<Recommended - If there are any legal issues to deal with the should be described here. Legal issues could be for example we have to redistribute third party technology. This section can also contain links the Legal Review Tool.If the Specification will be published on OpenOffice.org this section has to be removed.>

<Recommended - Questions will arise during the writing of the specification. State these in here.>

Required - Give references to related documentation, such as engineering designs, technical specs, and other sources for related units. Also include links to documents that other sections in this spec need to refer to, such as user opinions usability test reports.

Programmatic Control of Menu and Toolbar Items

Page 13

<Required - Path to specification>x

Carsten Driesner

2003-09-10T14:44:12