Framework/Article/Generic UNO Interfaces for complex toolbar controls

Generic and easy to use complex tool bar controls for add-ons

OpenOffice.org 2.0 state

The user interface framework implemented until OpenOffice 2.0.3 gives developers the ability to integrate more complex controls (other than simple buttons) into their add-on toolbar. Although it's possible implementing these kind of controls for an add-on it's not an easy task. The developer has to implement a toolbar controller ('com.sun.star.ui.ToolbarController') and register it in the Controller.xcu file. The controller must provide an awt control to the framework which puts it into the toolbar. To have full control over the created control a developer has to implement and use several interfaces (e.g. 'com.sun.star.ui.XToolbarController'). This complexity doesn't attract developers who just want to use complex controls without the need to have full control.

Solution

The Addon.xcu file provides a way to describe the user interface for an add-on. It will be enhanced to enable users to provide the control type of every toolbar item. The following control types should be supported.

Control	Image	Description
Image Button		A normal toggle button, but the size of the button depends on the image. At least the width, the height must follow some rules to prevent non-useful toolbars.
Combobox		A normal combo box with edit field inside.
Dropdown box		A normal drop down box (only read only edit field).
Spin field		A edit field with two buttons to increase/decrease numerical values.
Edit field		A normal edit field.
Button		A simple button without any need for status updates. This can useful if the button is always enabled and loading the add-on code on startup is costly.
Toggle button		A simple button which can be controlled by status updates.
Dropdown button		A toggle button with a drop-down button. Introduced by OpenOffice.org 2.0.

The user interface framework generates the controls when the add-on toolbar is created via the toolbar controller factory. Every add-on which wants to support a toolbar must be a dispatch provider. Therefore one communication protocol will be the normal duo com.sun.star.frame.XDispatch / com.sun.star.frame.XStatusListener. The new controls are listener at the dispatch object they get after calling queryDispatch. Depending on the control type they interpret statusChanged calls differently. The following table gives an overview which types could be supported by the new controls. The table can be extended without any problems regarding incompatibility.

Control	UNO type of Event.State provided by statusChanged	Description
Image Button	String	Can be interpreted as a URL to load a new image
	Boolean	Interpreted as on/off
Combobox	String	Set a new text into the edit field.
	Sequence< String >	A new list for the combo box.
Dropdown Box	Long	Select entry number.
	Sequence< String >	A new list for the dropdown box.
Spin field	Long	A new value for the edit field.
	Double	A new value for the edit field.
	com.sun.star.awt.Selection	Lower and upper limit for a numerical spin field.
Edit field	String	A next text for the edit field.
Button	---	Simple button doesn't support status updates.
Toggle button	Boolean	Interpreted as on/off
Dropdown button	---	Currently I don't see something here.

A new interface must be implemented by the add-on developer to get notifications generated the controls. It will be called ���com.sun.star.frame.XControlNotification���.

There is no option to provide an com.sun.star.awt based interface to the add-on as we would have several technical problems.

• A developer could damage the OpenOffice framework infrastructure as the awt-based interfaces are low-level.
• Some functions are not bound to the control itself, but to the parent window (toolbar), e.g. set a new quick help text, hide the control
  There is currently no interface to get access to the toolbar
• Low-level interfaces can be problematic, if we want to use a different user interface technology.
• Not all available controls do have an awt interface.

The current solution will still be available, so power developers will be able to have much more control over there controls.

2