Framework/Article/Generic UNO Interfaces for complex toolbar controls

    From The Document Foundation Wiki

    Technical specification

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

    State before OpenOffice.org 2.0.3

    The current user interface framework implemented for OpenOffice 2.0 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 (<idls>com.sun.star.frame.ToolbarController</idls>) 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. <idls>com.sun.star.frame.XToolbarController</idls>). 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 table shows all properties which are supported for toolbar items in Addons configuration file. The bold properties mark the new properties.

    Property

    Type

    Description

    URL

    String

    The command which is bound to the toolbar item.

    Title

    String/localized

    A localized text which is used as a label and/or quick help text.

    ImageIdentifier

    String

    An optional identifier to an image. Normally not used as the set "UserImages" associates images to commands.

    Target

    String

    Defines how to find a dispatcher for the command.

    Context

    String

    Determines for which contexts the control should be visible.

    ControlType

    String

    Defines the type of control.

    Width

    Long

    Defines the width of the control. Only controls with a dynamic width support this property (e.g. Combo box, edit field, spin field)

    The following control types should be supported.

    Control

    Description

    ImageButton

    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.

    Dropdownbox

    A normal drop down box (only read only edit field).

    Spinfield

    A edit field with two buttons to increase/decrease numerical values.

    Editfield

    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.

    ToggleButton

    A simple button which can be controlled by status updates.

    DropdownButton

    A drop-down only button. Newly introduced by OpenOffice.org 2.0.

    ToggleDropdownButton

    A toggle button with a drop-down button. Newly 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 for the new controls 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. The new controls will listen for special updates where a new struct called "ControlCommand" is provided. The ControlCommand struct offers developers a way to send commands to the control. It uses a string as command descriptor and a sequence of com.sun.star.beans.NamedValues for the arguments. This solution can be extended in the future and makes the implementation on the control side much easier.

    module com { module sun { module star { module frame {
    
    struct ControlCommand
    {
      //-------------------------------------------------------------------------
      /** specifies the command which should be processed by the toolbar
          control.
      */
      string Command;
    
      //-------------------------------------------------------------------------
      /** specifies a sequence of named values which are used as argument
          for the command. The number and type of arguments depend on the
          command and control.
      */
      sequence< com::sun::star::beans::NamedValue > Arguments;
    };
    
    }; }; }; };

    Control commands

    Depending on the control type the command calls are interpreted. The following table gives an overview which commands could be supported by the new controls. The table can be extended without any problems regarding incompatibility. Please be aware that this table only shows the current state. New commands can be added in later OpenOffice.org versions.

    Control

    Command/Status Update

    Arguments

    Description

    ImageButton

    SetImage

    URL=String

    Use the provided URL to load a new image

    Combobox

    SetText

    Text=String

    Set a new text into the edit field.


    SetList

    List=Sequence<String>

    A new list for the combo box.


    RemoveEntryPos

    Pos=Long

    Remove entry at position Pos.


    RemoveEntryText

    Text=String

    Remove entry with text = Text.


    InsertEntry

    Pos=Long
    Text=String

    Insert entry at position Pos with text Text.

    Dropdownbox

    SelectEntry

    Entry=Long

    Select entry number.


    SetList

    List=Sequence<String>

    A new list for the dropdown box.


    RemoveEntryPos

    Pos=Long

    Remove entry at position Pos.


    RemoveEntryText

    Text=String

    Remove entry with text = Text.


    InsertEntry

    Pos=Long
    Text=String

    Insert entry at position Pos with text Text.

    Spinfield

    SetValue

    Value=Long/Double

    A new value for the edit field.


    SetValues

    Value=Long/Double
    Step=Long/Double
    LowerLimit=Long/Double
    UpperLimit=Long/Double
    OutputFormat=String

    Set all possible values for the spin field at once.


    SetLowerLimit

    LowerLimit=Long/Double

    Set lower limit for the spin field.


    SetUpperLimit

    UpperLimit=Long/Double

    Set upper limit for the spin field.


    SetStep

    Step=Long/Double

    Set single step value for the spin field.


    SetOutputFormat

    OutputFormat=String

    Sets an optional output format string.

    Editfield

    SetText

    Text=String

    A new text for the edit field.

    Button

    ---


    Simple button doesn't support status updates.

    ToggleButton

    ---


    Currently I don't see a useful command here.

    DropdownButton

    SetList

    List=Sequence<String>

    A new list for the drop down box which get displayed when the user activates the drop down button.


    AddEntry

    Text=String

    Adds an entry at the end of the list.


    InsertEntry

    Pos=Long
    Text=String

    Inserts a new entry with text Text to the list at position Pos


    RemoveEntryPos

    Pos=Long

    Removes an entry from the listbox at position Pos


    RemoveEntryText

    Text=String

    Remove entry at position Pos.

    ToggleDropdownButton

    SetList

    List=Sequence<String>

    A new list for the listbox which get displayed when the user activates the dropdown button.


    CheckItemPos

    Pos=Long

    Checks the item at position Pos


    AddEntry

    Text=String

    Adds a new entry at the end of the list.


    InsertEntry

    Pos=Long
    Text=String

    Inserts a new entry with text Text to the list at position Pos


    RemoveEntryPos

    Pos=Long

    Removes an entry from the listbox at position Pos


    RemoveEntryText

    Text=String

    Remove entry at position Pos.



    The following code snippet shows how a command to set a new list for a "ToggleDropdownButton" can look like in C++.

    // The command "SetList" currently supports only one parameter
    Sequence< NamedValue > aArgs( 1 );
    
    // create a sequence of strings for the dropdown menu
    Sequence< rtl::OUString > aContextMenu( 3 );
    aContextMenu[0] = rtl::OUString::createFromAscii( "Command 1" );
    aContextMenu[1] = rtl::OUString::createFromAscii( "Command 2" );
    aContextMenu[2] = rtl::OUString::createFromAscii( "Command 3" );
    
    // argument is called "List"
    aArgs[0].Name = rtl::OUString::createFromAscii( "List" );
    aArgs[0].Value <<= aContextMenu;
    
    FeatureStateEvent aEvent;
    
    aEvent.FeatureURL = aURL;
    aEvent.Source = (::com::sun::star::frame::XDispatch*)this
    aEvent.IsEnabled = bEnabled;
    aEvent.Requery = sal_False;
    
    // initialize control command
    com::sun::star::frame::ControlCommand aCtrlCmd;
    aCtrlCmd.Command = rtl::OUString::createFromAscii( "SetList" );
    aCtrlCmd.Arguments = rArgs;
    
    aEvent.State <<= aCtrlCmd;
    
    // send command via statusChanged to the control
    xControl->statusChanged( aEvent );

    To enable add-on developers to get notifications from the new controls a new interface must be added. It will be called 'com.sun.star.frame.XControlNotificationListener' and should be implemented by the dispatch object provided by 'XDispatchProvider::queryDispatch'. The new controls will send notifications for important events. The notification is not send when a user executes a function with the control itself (e.g. clicking on a button to execute a function will not be notified. 'XDispatch::dispatch(...)' is called instead).

    module com { module sun { module star { module frame {
    
    interface XControlNotificationListener
    {
      //-------------------------------------------------------------------------
      /** notifies that a control event has happened
          @param Event
            contains the event information
      */
      void controlEvent( [in] ControlEvent Event );
    };
    
    }; }; }; };

    The function controlEvent uses another struct called ControlEvent. The following code snippet shows the details of the structure.

    module com { module sun { module star { module frame
    
    struct ControlEvent
    {
      //-------------------------------------------------------------------------
      /** fully parsed URL describing the control that sends this
          notification.
      */
      ::com::sun::star::util::URL
    
      // -------------------------------------------------------------------------
      /** specifies the event which has occurred.
      */
      string EventName;
    
      // -------------------------------------------------------------------------
      /** specifies a sequence of named values which are used as
          additional values for the event. The number and types of
          named values depend on the event.
      */
      sequence< com::sun::star::beans::NamedValue > Information;
    };
    
    }; }; }; };

    As the event name is defined as a string and additional information provided as a sequence com.sun.star.beans.Named, the event system can be easily extended. Depending on the control type the different events are notified. The following table gives an overview which events could be supported by the control types.

    Control

    Command/Status Update

    Information

    Description

    ImageButton

    ImageChanged

    URL=String

    Called when a new image has been set.

    Combobox

    TextChanged

    Text=String

    Called when the text of the edit field has been changed.


    ListChanged

    List=Sequence<String>

    Called when new list for the combo box has been set.


    FocusSet

    -

    Called when the edit field has gained the input focus.


    FocusLost

    -

    Called when the edit field has lost the input focus.

    Dropdownbox

    ListChanged

    List=Sequence<String>

    Called when the entry list of the combo box has been changed.


    FocusSet

    -

    Called when the edit field has gained the input focus.


    FocusLost

    -

    Called when the edit field has lost the input focus.

    Spinfield

    TextChanged

    Text=String

    Called when the text of the edit field has been changed.


    LowerLimitChanged

    Lower=Long/Double

    Called when the lower limit for the spin field has been changed.


    UpperLimitChanged

    Upper=Long/Double

    Called when the upper limit for the spin field has been changed.


    StepChanged

    Step=Long/Double

    Called when the step value for the spin field has been changed.


    FocusSet

    -

    Called when the edit field has gained the input focus.


    FocusLost

    -

    Called when the edit field has lost the input focus.

    Editfield

    TextChanged

    Text=String

    Called when the text of the edit field has been changed.


    FocusSet

    -

    Called when the edit field has gained the input focus.


    FocusLost

    -

    Called when the edit field has lost the input focus.

    Button

    -


    Currently I don't see a useful event here.

    ToggleButton

    -


    Currently I don't see a useful event here.

    DropdownButton

    ListChanged

    List=Sequence<String>

    Called when a new list for the context menu has been set.

    ToggleDropdownButton

    ListChanged

    List=Sequence<String>

    Called when a new list for the context menu has been set.


    ItemChecked

    Pos=Long

    Called when an entry at position Pos has been checked.

    Final conclusion

    The new controls and their interfaces should help normal developer to use complex controls in add-ons. There is also a second way to use these kind of controls which give developers more control, but need more effort. The proposed solution fits into the current framework environment. It reuses interfaces and concepts which every add-on developer already know and use.

    There is an example add-on for Windows and Linux x86 available (source code is also available). The add-on needs at least OOo 2.0.3 to work correctly. You need at least the OOo 2.0.3 SDK to build the add-on. This example is part of the OpenOffice.org 2.2 SDK. You can find it in the folder examples/cpp/complextoolbarcontrols.

    Add-on

    Link

    Demo add-on (Windows/Linux x86)

    http://framework.openoffice.org/files/documents/25/4121/DemoAddOn_cpp.oxt

    Demo add-on source code (C++)

    http://framework.openoffice.org/files/documents/25/4122/complextoolbarcontrols.zip

    Appendix

    Illustration which and how the framework environment objects interact.

    ComplexToolbarControls.jpg

    Apache Feather Logo.svg

    This work is licensed under the Apache License version 2.0