Difference between revisions of "Framework/Article/General Architecture Of The Framework User Interface Implementation"

Revision as of 13:34, 9 July 2007

This article describes the general architecture of the framework user interface implementation. The framework user interface implementation is responsible to provide application modules and users the following services:

• Layout of the user interface elements
• Creation, destruction and
• Persistent and transient customization of the user interface elements

Overview

The Layout Manager

The layout manager is the central instance of a frame controlling the user interface. A layout manager controls the visibility, size and position of the user interface elements of OpenOffice.org. Every created frame has an associated layout manager that can be retrieved using the property LayoutManager. For OpenOffice.org 2.3 and earlier the layout manager is responsible for:

• Menubar
• Toolbars
• Statusbar

Docking windows are controlled by a C++ implementation which is currently independent from the layout manager. It's planned to move the docking window implementation to the layout manager.

[cpp] //=============================================================================

module com { module sun { module star { module frame {

   Layout management is the process of determining the size and position of 
   user interface elements. By default, each Frame has a layout 
   manager -- it performs layout management for the user interface elements 
   within the frame. User interface elements can provide size and alignment 
   hints to layout managers, but layout managers have the final decision on 
   the size and position of those user interface elements. 

   @since OOo 2.0.0

   /** central interface to query for, create, destroy and manipulate user 
       interface elements which are bound to a frame.

       @see ::com::sun::star::frame::XLayoutManager;
   */
   interface ::com::sun::star::frame::XLayoutManager;
       
   /** notification interface to receive status information about the state 
       of the connected frame.

       E.g., you can receive events of instantiation/destruction and
       activation/deactivation of a frame.

       @see XFrame::addFrameActionListener()
       @see XFrame::removeFrameActionListener()
   */
   interface ::com::sun::star::frame::XFrameActionListener;

   /** notification interface to receive change messages of user interface 
       elements which are part of the layout manager.

       E.g., you can receive events of insertion/replacing and
       removing of settings data of user interface elements.

       @see com::sun::star::ui::XUIConfiguration
   */
   interface ::com::sun::star::ui::XUIConfigurationListener;

   /** provides functions to merge menus for inplace editing of components
       inside OpenOffice.org.
   */
   interface ::com::sun::star::frame::XMenuBarMergingAcceptor;

   /** registers listeners that want to receive layout manager
       events.
   */
   [optional] interface ::com::sun::star::frame::XLayoutManagerEventBroadcaster;

   /** interface to support settings a menu bar for inplace editing of 
       components inside OpenOffice.org.

       @deprecated
   */    
   [optional] interface ::com::sun::star::frame::XInplaceLayout;

}; }; }; };

Example to retrieve the layout manager instance from a frame. [cpp]

   try
   {
       xLayoutManager.set( xPropSet->getPropertyValue( 
           ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM( "LayoutManager" ))), 
           ::com::sun::star::uno::UNO_QUERY );
   }
   catch ( com::sun::star::beans::UnknownPropertyException& )
   {
   }

}

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 and statusbar

• 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. Add-on toolbars use the prefix "addon_" and are also controlled by the layout manager automatically.

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 for a user interface element as every frame which is bound to a document provides context information that is used to address the correct configuration data.

Toolbars

Menubar

Statusbar

The User Interface Configuration API

The Module User Interface Configuration Manager

The Document User Interface Configuration Manager

Persistence

User Interface Configuration Data Format

Maintenance of Menus, Toolbars and User Interface Commands

The resource file system which stored the user interface configuration data for older OpenOffice.org version is obsolete for most user interface elements of Openoffice.org 2.x (except context menus). As described in chapter 9 of the OpenOffice.org XML File Format documentation all user interface configuration data is stored in a XML based file, 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 for an installed OpenOffice.org are located at: <Office installation>/share/registry/org/openoffice/Office/UI. The schema definition of these configuration files can be found below:

[xml] <?xml version="1.0" encoding="UTF-8"?> <!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="Commands" oor:package="org.openoffice.Office.UI" xml:lang="en-US">

 <info>
   <author>CD</author>
     <desc >Contains general information about ~ and rules, and about actions based on office commands.</desc>
 </info>
 <templates>
   <group oor:name="LabelType">
     <info>
       <desc>Provides a mapping between commands and their textual representation on the user interface.</desc>
     </info>
     <prop oor:name="Label" oor:type="xs:string" oor:localized="true">
       <info>
         <desc>A localized text that describes the command or identifier. Can be used as a label inside a menu or as short tool tip help.</desc>
       </info>
     </prop>
     <prop oor:name="ContextLabel" oor:type="xs:string" oor:localized="true">
       <info>
         <desc>A localized text that describes the identifier of a command in a structured menu.  </desc>
       </info>
     </prop>
     <prop oor:name="Properties" oor:type="xs:int">
       <info>
         <desc>
           Additional information about a single command.
           Bit 0 = Command has an image.
           Bit 1 = Image must be mirrored  (CTL/vertical text).
           Bit 2 = Image must be rotated (CTL/vertical text).
         </desc>
       </info>
       <value>0</value>
     </prop>
   </group>
 </templates>

<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 OpenOffice.org 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] <?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>

The configuration files for all modules are maintained in the project officecfg within the folder officecfg/registry/data/org/openoffice/Office/UI.

Adding a new Toolbar

How to add, replace or remove a User Interface Command