Revision as of 15:48, 19 March 2007

This tutorial will give you a detailed overview of the OpenOffice.org status bar and how to create a status bar conbtroller. Everybody is invited to participate. May be someone wants to translate the extension to a different language (e.g. Java or Python) or wants to have more information about a specific topic. You can set a link to this page, if you think that this page adds valuable information. The outcome of this tutorial will be a status bar controller that will show the current position of the cursor (e.g. line, column).

The reader of this tutorial should have the following programming skills

Programming with UNO
C++ knowledge
How to create an extension with the "OpenOffice.org SDK"

1 The OpenOffice.org status bar
- 1.1 Statusbar Configuration
  - 1.1.1 Status Bar
  - 1.1.2 Status Bar Item
2 General abstract of the status bar controller concept
- 2.1 Status bar controller architecture
  - 2.1.1 Configuration
3 The cursor position status bar controller
- 3.1 A status bar controller skeleton
- 3.2 The cursor position part

The OpenOffice.org status bar

The OpenOffice.org status bar is controlled by the frame based layout manager. Every frame contains a layout manager that controls the user interfaces elements (e.g. menu bar, status bar, toolbars). The layout manager identifies every user interface element via a unique url. The status bar can be addressed by the following url: private:resource/statusbar/statusbar. The status bar is always located at the bottom side of a frame. It's also responsible to show the progress bar during loading of a document.

The status bar consists of several status bar controller which each controls a different aspect. For example the default OpenOffice.org Writer status bar contains nine different controllers you can see on the following illustration.

Statusbar Configuration

The structure of a status bar is defined by a XML file located in the OpenOffice.org installation folder. The default location is here:

<OpenOffice.org installation>/share/config/soffice.cfg/modules/<application module identifier>/statusbar/statusbar.xml

The following snippet shows the content of the OpenOffice.org Writer status bar XML file.

[xml] <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE statusbar:statusbar PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "statusbar.dtd"> <statusbar:statusbar xmlns:statusbar="http://openoffice.org/2001/statusbar" xmlns:xlink="http://www.w3.org/1999/xlink">


<statusbar:statusbaritem xlink:href=".uno:StatePageNumber" statusbar:align="left" statusbar:autosize="true" statusbar:width="54"/>
<statusbar:statusbaritem xlink:href=".uno:PageStyleName" statusbar:align="left" statusbar:autosize="true" statusbar:width="79"/>
<statusbar:statusbaritem xlink:href=".uno:Zoom" statusbar:align="center" statusbar:width="35" />
<statusbar:statusbaritem xlink:href=".uno:InsertMode" statusbar:align="center" statusbar:width="37" />
<statusbar:statusbaritem xlink:href=".uno:SelectionMode" statusbar:align="center" statusbar:width="30" />
<statusbar:statusbaritem xlink:href=".uno:ExecHyperlinks" statusbar:align="center" statusbar:width="22" />
<statusbar:statusbaritem xlink:href=".uno:ModifiedStatus" statusbar:align="center" statusbar:width="9" />
<statusbar:statusbaritem xlink:href=".uno:Signature" statusbar:align="center" statusbar:ownerdraw="true" statusbar:width="16" />
<statusbar:statusbaritem xlink:href=".uno:Size" statusbar:align="left" statusbar:autosize="true" statusbar:ownerdraw="true" statusbar:width="129"/>

</statusbar:statusbar>

The xml configuration file supports the following elements, attributes and rules.

You must locate a <statusbar:statusbaritem> element inside a <statusbar:statusbar> element.
You cannot nest <statusbar:statusbar> elements.

Status Bar

[xml] The <statusbar:statusbar> element is a container element for status bar items.

XML Code : <statusbar:statusbar> Rules : You must include all status bar items in a this element. DTD : <!ELEMENT statusbar:statusbar (statusbar:statusbaritem*)>


          <!ATTLIST statusbar:statusbar
                    xmlns:statusbar CDATA #FIXED "http://openoffice.org/2001/statusbar"
                    xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink">

Status Bar Item

[xml] XML Code : <statusbar:statusbaritem> Rules : You must specify a valid value for the xlink:href attribute DTD : <!ELEMENT statusbar:statusbaritem EMPTY>


          <!ATTLIST statusbar:statusbaritem
                    xlink:href CDATA #REQUIRED
                    statusbar:align %alignment; #IMPLIED
                    statusbar:style %style; #IMPLIED
                    statusbar:autosive %boolean; #IMPLIED
                    statusbar:ownertraw %boolean; #IMPLIED
                    statusbar:width %numeric; #IMPLIED
                    statusbar:offset %numeric; #IMPLIED>

xlink:href

The xlink:href attribute specifies the status bar control that is instantiated for this status bar item

[xml] XML Code : <xlink:href> Rules : The value of this attribute must be a valid status URL. If the URL don't


          have a status bar controller associated it will be ignored.

DTD : <!ATTLIST statusbar:statusbaritem xlink:href CDATA #REQUIRED>

statusbar:align

The statusbar:align attribute specifies how the information is aligned in the bounding box of the status bar control window.

[xml] XML Code : <statusbar:align> Rules : The value of this attribute can be one of the following:


          - left  : The status bar control output should be aligned to the left border
                    the bounding box.
          - center: The status bar control output should be aligned to the center of
                    the bounding box.
          - right : The status bar control output should be aligned to the right border
                    of the bounding box.

DTD      : <!ENTITY % alignment "(left|center|right)">

          <!ATTLIST statusbar:statusbaritem statusbar:align %alignment; "center">

statusbar:style

The statusbar:style attribute specifies how the bounding box of a status bar item is displayed.

[xml] XML Code : <statusbar:style> Rules : The value of this attribute can be one of the following:


          - in   : The bounding box of the status bar control is painted engraved.
          - out  : The bounding box of the status bar control is painted embossed.
          - flat : The bounding box of the status bar control is painted normally, no 3D effect.

DTD      : <!ENTITY % style "(in|out|flat)">

          <!ATTLIST statusbar:statusbaritem statusbar:style %style; "in">

statusbar:autosize

The statusbar:autosize attribute specifies whether or not the size of the bounding box for the status bar item is controlled automatically by the status bar.

[xml] XML Code : <statusbar:autosize> Rules : The value of this attribute can be true or false. If the value if true the size of the bounding box is set


          automatically by the status bar. If the value is false the statusbar:width attribute determines the size of the bounding
          box. The default value is false.

DTD : <!ATTLIST statusbar:statusbaritem statusbar:autosize %boolean; "false">

statusbar:ownerdraw

The statusbar:ownerdraw attribute specifies whether or not the status bar item uses an external function to display its content.

[xml] XML Code : <statusbar:ownerdraw> Rules : The value of this attribute can be true or false. The value must be true to use an external function to display the


          content.

DTD : <!ATTLIST statusbar:statusbaritem statusbar:ownerdraw %boolean; "false">

statusbar:width

The statusbar:width attribute specifies the width of the bounding box for a status bar item in pixel.

[xml] XML Code : <statusbar:width> Rules : This attribute is only processed if the value of the statusbar:autosize attribute is set to false. DTD : <!ENTITY % numeric "CDATA">


          <!ATTLIST statusbar:statusbaritem statusbar:width %numeric; "0">

General abstract of the status bar controller concept

Status bar controller architecture

A status bar controller is responsible for a single aspect that should be accessible via status bar. It must be implemented via UNO using the status bar controller service. This service is called com.sun.star.frame.StatusbarController. The OpenOffice.org status bar implementation uses the different interfaces of the service for creation, initialization, destruction and communication. The following snippet shows the UNO IDL description of the central com.sun.star.frame.StatusbarController service:

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


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

//=============================================================================
/** is an abstract service for a component which offers a more complex user 

   interface to users within a status bar.

   A generic status bar function is represented as a text field which has 
   provides status information to the user. A status bar controller can be 
   added to a status bar and provide information or functions with a more 
   sophisticated user interface.
   A typical example for a status bar controller is the zoom level chooser 
   within the statusbar. It provides an option to change the zoom level of 
   an application.

   see com::sun::star::frame::XDispatchProvider
   see com::sun::star::frame::XStatusbarController

   since OOo 2.0.0
*/

service StatusbarController
{

   //-------------------------------------------------------------------------
   /** with this interface a component can receive events if a feature has 
       changed.

       The toolbar controller implementation should register itself as a 
       listener when its com::sun::star::util::XUpdatable interface has 
       been called.
    */
   interface com::sun::star::frame::XStatusListener;

   /** used to initialize a component with required arguments.

       A toolbar controller needs at least three additional arguments 
       provided as com::sun::star::beans::PropertyValue:

       Frame
       com::sun::star::frame::XFrame instance to which the toolbar 
       controller belongs.
       
       CommandURL
       a string which specifies the command a statusbar controller is bound.

       ServiceManager
       a com::sun::star::lang::XMultiServiceFactory instance which can 
       be used to create additional UNO services.
   */
   interface com::sun::star::lang::XInitialization;

   /** used to notify an implementation that it needs to add its listener or 
       remove and add them again.

       A status bar controller instance is ready for use after this call has 
       been made the first time. The status bar implementation guarentees that 
       the controller's item window has been added to the status bar and its 
       reference is held by it.
   */
   interface com::sun::star::util::XUpdatable;

   //-------------------------------------------------------------------------
   /** used to notify changed features and requests for additional user 
       interface items.

       Mostly used by a status bar implementation to forward information to 
       and request services from a status bar controller component. This 
       interface must be useable after 
       com::sun::star::lang::XInitialitation::initialize has been called.  
       The behavior of the interface is undefined if the controller component 
       hasn't been initialized.
    */
   interface com::sun::star::frame::XStatusbarController;

};

}; }; }; };

Configuration

Every UNO based status bar controller must be registered in the OpenOffice.org configuration to be accessible by the status bar factory. The following snippet shows the schema of this controller configuration.

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

<oor:component-schema oor:name="Controller" 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>
 <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">
  ...
  <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 extracted from a org/openoffice/Office/UI/Controller.xcu configuration file which is part of every OpenOffice.org 2.x installation.

<OpenOffice.org installation>/share/registry/data/org/openoffice/Office/UI/Controller.xcu

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

<oor:component-data oor:name="Controller" oor:package="org.openoffice.Office.UI" xmlns:install="http://openoffice.org/2004/installation" 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="Registered">
 <node oor:name="StatusBar">
  <node oor:name="c1" oor:op="replace">
   <prop oor:name="Command">
    <value>.uno:DBStatusType</value>
   </prop>
   <prop oor:name="Module">
    <value>com.sun.star.sdb.OfficeDatabaseDocument</value>
   </prop>
   <prop oor:name="Controller">
    <value>com.sun.star.sdb.ApplicationStatusbarController</value>
   </prop>
  </node>
  <node oor:name="c2" oor:op="replace">
   <prop oor:name="Command">
    <value>.uno:DBStatusDBName</value>
   </prop>
   <prop oor:name="Module">
    <value>com.sun.star.sdb.OfficeDatabaseDocument</value>
   </prop>
   <prop oor:name="Controller">
    <value>com.sun.star.sdb.ApplicationStatusbarController</value>
   </prop>
  </node>
  <node oor:name="c3" oor:op="replace">
   <prop oor:name="Command">
    <value>.uno:DBStatusUserName</value>
   </prop>
   <prop oor:name="Module">
    <value>com.sun.star.sdb.OfficeDatabaseDocument</value>
   </prop>
   <prop oor:name="Controller">
    <value>com.sun.star.sdb.ApplicationStatusbarController</value>
   </prop>
  </node>
  <node oor:name="c4" oor:op="replace">
   <prop oor:name="Command">
    <value>.uno:DBStatusHostName</value>
   </prop>
   <prop oor:name="Module">
    <value>com.sun.star.sdb.OfficeDatabaseDocument</value>
   </prop>
   <prop oor:name="Controller">
    <value>com.sun.star.sdb.ApplicationStatusbarController</value>
   </prop>
  </node>
  <node oor:name="c5" oor:op="replace">
   <prop oor:name="Command">
    <value>.uno:StatusbarLogo</value>
   </prop>
   <prop oor:name="Module">
    <value/>
   </prop>
   <prop oor:name="Controller">
    <value>com.sun.star.comp.framework.LogoImageStatusbarController</value>
   </prop>
   </node>
   <node oor:name="c6" oor:op="replace">
    <prop oor:name="Command">
     <value>.uno:StatusbarLogoText</value>
    </prop>
    <prop oor:name="Module">
     <value/>
    </prop>
    <prop oor:name="Controller">
     <value>com.sun.star.comp.framework.LogoTextStatusbarController</value>
    </prop>
   </node>
  </node>
 </node>

</oor:component-data>

This file contains all UNO based status bar controller. There a couple of internal status bar controller which are sfx2 based. These controller are restricted to sfx2 based application modules (e.g. Writer, Calc, Draw, Impress and Math). In the future all controllers will be translated to support the described UNO service (com.sun.star.frame.StatusbarController). This would allow non-sfx2 based application modules to also use them.

The cursor position status bar controller

This chapter describes how to create a cursor position status bar controller. It uses the previous described concepts and descriptions to implement it.

A status bar controller skeleton

The cursor position part

Difference between revisions of "Framework/Tutorial/Statusbar Controller"