Apache OpenOffice Wiki - User contributions [en]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-13T06:31:46Z

Dtardon: replace HTML entities in code listings by characters

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-13T05:55:45Z

Dtardon: replace HTML entities in the code showing class SfxToolBoxControl by characters

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-13T04:49:30Z

Dtardon: add some missing curly braces to examples

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:40:46Z

Dtardon: fix formatting of source code

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:18:05Z

Dtardon: fix formatting of source code

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<source lang="xml">
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</source>
A popup menu controller must support the following services / interfaces: 

<source lang="idl">
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</source>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<source lang="idl">
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{
//-------------------------------------------------------------------------

/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------

/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------

/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------

/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------

/** contains the state of the feature in this dispatch.*/
any State;
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.

It should be called directly after the object is created.
*/
void initialize( [in] sequence<any> aArguments )
raises( com::sun::star::uno::Exception );
};

//=============================================================================

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module util {

published interface XUpdatable: com::sun::star::uno::XInterface
{
//-------------------------------------------------------------------------
/** refreshes the data of the object from the connected data source. */
void update();
};

//=============================================================================

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

interface XToolbarController : com::sun::star::uno::XInterface
{
//=============================================================================
/** provides a function to execute the command which is bound to the toolbar controller.

@param
a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys.


This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus.

*/
void execute( [in] short KeyModifier );

//=============================================================================
/** notifies a component that a single click has been made on the toolbar item.
*/
void click();

//=============================================================================
/** notifies a component that a double click has been made on the toolbar item.
*/
void doubleClick();

//=============================================================================
/** requests to create a popup window for additional functions.

@return
a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window.
*/
com::sun::star::awt::XWindow createPopupWindow();

//=============================================================================
/** requests to create an item window which can be added to the toolbar.

@param Parent
a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window.

@return
a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window.
*/
com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

interface XSubToolbarController : com::sun::star::uno::XInterface
{
//=============================================================================
/** if the controller features a sub-toolbar.

@return
<TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>.


Enables implementations to dynamically decide to support sub-toolbars
or not.

*/
boolean opensSubToolbar();

//=============================================================================
/** provides the resource URL of the sub-toolbar this controller opens.

@return
name of the sub-toolbar this controller offers. A empty string
will be interpreted as if this controller offers no sub-toolbar.
*/
string getSubToolbarName();

//=============================================================================
/** gets called to notify a controller that a sub-toolbar function has been
selected.

@param aCommand
a string which identifies the function that has been selected by
a user.
*/
void functionSelected( [in] string aCommand );

//=============================================================================
/** gets called to notify a controller that it should set an image which
represents the current selected function.


Only the controller instance is able to set the correct image for the
current function. A toolbar implementation will ask sub-toolbar
controllers to update their image whenever it has to update the images
of all its buttons.

*/
void updateImage();
};

}; }; }; };
</source>

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:13:00Z

Dtardon: /* Toolbar item controller */

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<source lang="xml">
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</source>
A popup menu controller must support the following services / interfaces: 

<source lang="idl">
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</source>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<source lang="idl">
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</source>

 

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

 

published interface XStatusListener: com::sun::star::lang::XEventListener

{

 /** is called when the status of the feature changes. @param State provides information about changes of the requested feature */

 [oneway] void statusChanged( [in] FeatureStateEvent State );

};

 

}; }; }; };

 

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

 

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{

 //-------------------------------------------------------------------------

 /** contains the URL of the feature. */

 com::sun::star::util::URL FeatureURL;

 

 //-------------------------------------------------------------------------

 /** contains a descriptor of the feature for the user interface.*/

 string FeatureDescriptor;

 

 //-------------------------------------------------------------------------

 /** specifies whether the feature is currently enabled or disabled. */

 boolean IsEnabled;

 

 //-------------------------------------------------------------------------

 /** specifies whether the <type>XDispatch</type> has to be requeried. */

 boolean Requery;

 

 //-------------------------------------------------------------------------

 /** contains the state of the feature in this dispatch.*/

 any State;

}; 

 

}; }; }; };

 

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** provides a function to execute the command which is bound to the toolbar controller. @param a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys. This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus. */ void execute( [in] short KeyModifier ); //============================================================================= /** notifies a component that a single click has been made on the toolbar item. */ void click(); //============================================================================= /** notifies a component that a double click has been made on the toolbar item. */ void doubleClick(); //============================================================================= /** requests to create a popup window for additional functions. @return a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window. */ com::sun::star::awt::XWindow createPopupWindow(); //============================================================================= /** requests to create an item window which can be added to the toolbar. @param Parent a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window. @return a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window. */ com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent ); }; }; }; }; };

 

module com { module sun { module star { module frame { interface XSubToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** if the controller features a sub-toolbar. @return <TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>. Enables implementations to dynamically decide to support sub-toolbars or not. */ boolean opensSubToolbar(); //============================================================================= /** provides the resource URL of the sub-toolbar this controller opens. @return name of the sub-toolbar this controller offers. A empty string will be interpreted as if this controller offers no sub-toolbar. */ string getSubToolbarName(); //============================================================================= /** gets called to notify a controller that a sub-toolbar function has been selected. @param aCommand a string which identifies the function that has been selected by a user. */ void functionSelected( [in] string aCommand ); //============================================================================= /** gets called to notify a controller that it should set an image which represents the current selected function. Only the controller instance is able to set the correct image for the current function. A toolbar implementation will ask sub-toolbar controllers to update their image whenever it has to update the images of all its buttons. */ void updateImage(); }; }; }; }; }; 

 

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:10:40Z

Dtardon: fix formatting of example

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<source lang="xml">
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</source>
A popup menu controller must support the following services / interfaces: 

<source lang="idl">
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</source>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<source lang="idl">
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</source>

 

<source lang="idl">
module com { module sun { module star { module frame { 

 

published interface XStatusListener: com::sun::star::lang::XEventListener

{

 /** is called when the status of the feature changes. @param State provides information about changes of the requested feature */

 [oneway] void statusChanged( [in] FeatureStateEvent State );

};

 

}; }; }; };

 

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

 

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{

 //-------------------------------------------------------------------------

 /** contains the URL of the feature. */

 com::sun::star::util::URL FeatureURL;

 

 //-------------------------------------------------------------------------

 /** contains a descriptor of the feature for the user interface.*/

 string FeatureDescriptor;

 

 //-------------------------------------------------------------------------

 /** specifies whether the feature is currently enabled or disabled. */

 boolean IsEnabled;

 

 //-------------------------------------------------------------------------

 /** specifies whether the <type>XDispatch</type> has to be requeried. */

 boolean Requery;

 

 //-------------------------------------------------------------------------

 /** contains the state of the feature in this dispatch.*/

 any State;

}; 

 

}; }; }; };

 

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** provides a function to execute the command which is bound to the toolbar controller. @param a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys. This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus. */ void execute( [in] short KeyModifier ); //============================================================================= /** notifies a component that a single click has been made on the toolbar item. */ void click(); //============================================================================= /** notifies a component that a double click has been made on the toolbar item. */ void doubleClick(); //============================================================================= /** requests to create a popup window for additional functions. @return a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window. */ com::sun::star::awt::XWindow createPopupWindow(); //============================================================================= /** requests to create an item window which can be added to the toolbar. @param Parent a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window. @return a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window. */ com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent ); }; }; }; }; };

 

module com { module sun { module star { module frame { interface XSubToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** if the controller features a sub-toolbar. @return <TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>. Enables implementations to dynamically decide to support sub-toolbars or not. */ boolean opensSubToolbar(); //============================================================================= /** provides the resource URL of the sub-toolbar this controller opens. @return name of the sub-toolbar this controller offers. A empty string will be interpreted as if this controller offers no sub-toolbar. */ string getSubToolbarName(); //============================================================================= /** gets called to notify a controller that a sub-toolbar function has been selected. @param aCommand a string which identifies the function that has been selected by a user. */ void functionSelected( [in] string aCommand ); //============================================================================= /** gets called to notify a controller that it should set an image which represents the current selected function. Only the controller instance is able to set the correct image for the current function. A toolbar implementation will ask sub-toolbar controllers to update their image whenever it has to update the images of all its buttons. */ void updateImage(); }; }; }; }; }; 

 

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:07:58Z

Dtardon: /* Generic menu item controller */

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<source lang="xml">
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</source>
A popup menu controller must support the following services / interfaces: 

<source lang="idl">
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</source>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<code>[cpp]
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</code>

 

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

 

published interface XStatusListener: com::sun::star::lang::XEventListener

{

 /** is called when the status of the feature changes. @param State provides information about changes of the requested feature */

 [oneway] void statusChanged( [in] FeatureStateEvent State );

};

 

}; }; }; };

 

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

 

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{

 //-------------------------------------------------------------------------

 /** contains the URL of the feature. */

 com::sun::star::util::URL FeatureURL;

 

 //-------------------------------------------------------------------------

 /** contains a descriptor of the feature for the user interface.*/

 string FeatureDescriptor;

 

 //-------------------------------------------------------------------------

 /** specifies whether the feature is currently enabled or disabled. */

 boolean IsEnabled;

 

 //-------------------------------------------------------------------------

 /** specifies whether the <type>XDispatch</type> has to be requeried. */

 boolean Requery;

 

 //-------------------------------------------------------------------------

 /** contains the state of the feature in this dispatch.*/

 any State;

}; 

 

}; }; }; };

 

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** provides a function to execute the command which is bound to the toolbar controller. @param a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys. This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus. */ void execute( [in] short KeyModifier ); //============================================================================= /** notifies a component that a single click has been made on the toolbar item. */ void click(); //============================================================================= /** notifies a component that a double click has been made on the toolbar item. */ void doubleClick(); //============================================================================= /** requests to create a popup window for additional functions. @return a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window. */ com::sun::star::awt::XWindow createPopupWindow(); //============================================================================= /** requests to create an item window which can be added to the toolbar. @param Parent a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window. @return a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window. */ com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent ); }; }; }; }; };

 

module com { module sun { module star { module frame { interface XSubToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** if the controller features a sub-toolbar. @return <TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>. Enables implementations to dynamically decide to support sub-toolbars or not. */ boolean opensSubToolbar(); //============================================================================= /** provides the resource URL of the sub-toolbar this controller opens. @return name of the sub-toolbar this controller offers. A empty string will be interpreted as if this controller offers no sub-toolbar. */ string getSubToolbarName(); //============================================================================= /** gets called to notify a controller that a sub-toolbar function has been selected. @param aCommand a string which identifies the function that has been selected by a user. */ void functionSelected( [in] string aCommand ); //============================================================================= /** gets called to notify a controller that it should set an image which represents the current selected function. Only the controller instance is able to set the correct image for the current function. A toolbar implementation will ask sub-toolbar controllers to update their image whenever it has to update the images of all its buttons. */ void updateImage(); }; }; }; }; }; 

 

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:07:00Z

Dtardon: fix formatting of examples

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };

module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<source lang="xml">
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</source>
A popup menu controller must support the following services / interfaces: 

<source lang="idl">
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</source>

<source lang="idl">
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</source>

<source lang="idl">
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</source>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<code>[cpp]
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</code>

 

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

 

published interface XStatusListener: com::sun::star::lang::XEventListener

{

 /** is called when the status of the feature changes. @param State provides information about changes of the requested feature */

 [oneway] void statusChanged( [in] FeatureStateEvent State );

};

 

}; }; }; };

 

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

 

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{

 //-------------------------------------------------------------------------

 /** contains the URL of the feature. */

 com::sun::star::util::URL FeatureURL;

 

 //-------------------------------------------------------------------------

 /** contains a descriptor of the feature for the user interface.*/

 string FeatureDescriptor;

 

 //-------------------------------------------------------------------------

 /** specifies whether the feature is currently enabled or disabled. */

 boolean IsEnabled;

 

 //-------------------------------------------------------------------------

 /** specifies whether the <type>XDispatch</type> has to be requeried. */

 boolean Requery;

 

 //-------------------------------------------------------------------------

 /** contains the state of the feature in this dispatch.*/

 any State;

}; 

 

}; }; }; };

 

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** provides a function to execute the command which is bound to the toolbar controller. @param a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys. This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus. */ void execute( [in] short KeyModifier ); //============================================================================= /** notifies a component that a single click has been made on the toolbar item. */ void click(); //============================================================================= /** notifies a component that a double click has been made on the toolbar item. */ void doubleClick(); //============================================================================= /** requests to create a popup window for additional functions. @return a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window. */ com::sun::star::awt::XWindow createPopupWindow(); //============================================================================= /** requests to create an item window which can be added to the toolbar. @param Parent a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window. @return a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window. */ com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent ); }; }; }; }; };

 

module com { module sun { module star { module frame { interface XSubToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** if the controller features a sub-toolbar. @return <TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>. Enables implementations to dynamically decide to support sub-toolbars or not. */ boolean opensSubToolbar(); //============================================================================= /** provides the resource URL of the sub-toolbar this controller opens. @return name of the sub-toolbar this controller offers. A empty string will be interpreted as if this controller offers no sub-toolbar. */ string getSubToolbarName(); //============================================================================= /** gets called to notify a controller that a sub-toolbar function has been selected. @param aCommand a string which identifies the function that has been selected by a user. */ void functionSelected( [in] string aCommand ); //============================================================================= /** gets called to notify a controller that it should set an image which represents the current selected function. Only the controller instance is able to set the correct image for the current function. A toolbar implementation will ask sub-toolbar controllers to update their image whenever it has to update the images of all its buttons. */ void updateImage(); }; }; }; }; }; 

 

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/OpenOffice.org 2.0 User Interface Controller Internals

2009-08-11T17:05:31Z

Dtardon: fix formatting of examples

= OpenOffice.org 2.0 User Interface Controller Internals =

A typical OOo 2.0 document contains different user interface elements. They have to provide their functions to the user and display the current state of the document view.

If you want to know about the different controller type then you should read the controller tutorials available in the [[Framework#Articles_.26_Tutorials|articles&tutorials chapter]].

'''How and in which infrastructure do they work?'''

[[Image:OpenOffice2UserInterfaceElements.png]]

The user interface elements are using controllers for each of their elements to bind them to the dynamic state of the application module. It's the responsibility of every user interface controller to call and to display the current state of its bound function.

OOo 2.0 uses the following user interface controllers:

* Menubar
** Popup menu controller
** Generic menu item controller
** Internal menu controller
* Toolbar
** Generic toolbar item controller
** Specific toolbar item controller
* Statusbar
** Specific statusbar item controller

== Menubar ==

=== Generic menu item controller ===

A normal menu item is controlled by a generic menu item controller. A menu bar of an application module uses for about 90% of its menu items generic item controllers. For example the Edit - Undo, Redo and Edit - Cut, Copy and Paste menu items are implemented using generic menu item controllers.

A generic menu item controller supports the following interfaces:
<source lang="idl">
module com { module sun { module star { module frame {
published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.
@param State
provides information about changes of the requested feature */
[oneway] void statusChanged( [in] FeatureStateEvent State );
};
}; }; }; };

module com { module sun { module star { module frame {
published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the <type>XDispatch</type> has to be requeried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.*/
any State;
};
}; }; }; };
</source>

It supports the following generic functions by listing to status updates provided by function statusChanged. 
{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Menu item changes its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Menu item checks or unchecks its menu item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Menu item will be made visible or invisible, according to the provided state.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Menu item is enabled or disabled according to the value of IsEnabled.
|}
 

=== Internal menu controller ===

An Internal menu controllers is used for special menu items, like the window list (accessible via the Window popup menu). Internal menu controllers are completely responsible for their menu items. Currently there is no special menu controller which is implemented outside the framework library. There exists no UNO API to implement internal menu controllers.

=== Popup menu controller ===

A popup menu controller is a special menu controller which is responsible for a whole popup menu inside a menu bar. A popup menu controller must be a UNO service and registered in the configuration controller set, which can be found at org.openoffice.Office.UI.Controller/Registered/PopupMenu. The configuration set associates UNO service names implementing a popup menu controller with a command URL. The command URL is used by our XML based menu bar description. A popup menu controller is created by a popup menu controller factory which uses the configuration set to retrieve the correct service name and to initialize it.
 
An abstract from the org.openoffice.Office.UI.Controller/Registered/PopupMenu:

<code>[xml]
<!DOCTYPE oor:component-data SYSTEM "../../../../../component-update.dtd">
<oor:component-data oor:name="Controller" 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="Registered">
<node oor:name="PopupMenu">
<node oor:name="c1" oor:op="replace">
<prop oor:name="Command">
<value>.uno:CharFontName</value>
</prop>
<prop oor:name="Module">
<value/>
</prop>
<prop oor:name="Controller">
<value>com.sun.star.comp.framework.FontMenuController</value>
</prop>
</node>
...
</code>
A popup menu controller must support the following services / interfaces: 

<code>[cpp]
module com { module sun { module star { module frame {

service PopupMenuController
//-------------------------------------------------------------------------
/** supports functions to initialize and update a popup menu controller
implementation.

A popup menu controller implementation gets initialized with a
com::sun::star::awt::XPopupMenu object. This assures
that a popup menu controller can be implemented with any UNO based
language.
*/
interface com::sun::star::frame::XPopupMenuController;

//-------------------------------------------------------------------------
/** provides functions to initialize a popup menu controller with
specific data which are needed.

This interface should not directly used. A factory service is responsible to
initialize every controller correctly.
popup menu controller needs at least two additional arguments
provided as com::sun::star::beans::PropertyValue.

Frame
specifies the com::sun::star::frame::XFrame instance to which the
popup menu controller belongs to.

CommandURL
specifies which popup menu controller should be created.

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

//-------------------------------------------------------------------------
/** used to brief the popup menu controller with new status information.
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.
*/
interface com::sun::star::frame::XStatusListener; 
};
}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

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

/** provides a com::sun::star::awt::XPopupMenu 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. A
controller should never 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
for a command URL and immediately deregister after that.
Therefore status updates will not be send regularly for a
non visible popup menu.
*/
void updatePopupMenu();

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module lang {

published interface XInitialization: com::sun::star::uno::XInterface
{
// DocMerge from xml: method com::sun::star::lang::XInitialization::initialize
/** initializes the object.
It should be called directly after the object has been created.
*/
void initialize( [in] sequence< any > aArguments ) raises( com::sun::star::uno::Exception );
};

//============================================================================= }; }; }; };

</code>

<code>[cpp]
module com { module sun { module star { module frame {

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );
};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature. */
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface. */
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled. */
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be re-queried. */
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch. */
any State;
};

}; }; }; };
</code>

The framework project provides a base class to implement popup menu controller easier. It can be found in ''framework/inc/helper/popupmenucontrollerbase.hxx''. There are several implementations for popup menu controller in ''framework/source/uielement'' which uses the base class and can be used as templates. 
 
Currently OOo 2.0 provides the following popup menu controllers:
 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="24%" |
Command
! width="12%" |
Modules
! width="31%" |
Service
! width="34%" |
Purpose
|- valign="TOP"
| width="24%" |
.uno:CharFontName
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontMenuController
| width="34%" |
Provides a popup menu with all supported fonts.
|- valign="TOP"
| width="24%" |
.uno:FontHeight
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FontSizeMenuController
| width="34%" |
Provides a popup menu with all supported font sizes.
|- valign="TOP"
| width="24%" |
.uno:ObjectMenue
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ObjectMenuController
| width="34%" |
Provides a popup menu with all supported commands of an embedded object.
|- valign="TOP"
| width="24%" |
.uno:InsertPageHeader
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.HeaderMenuController
| width="34%" |
Provides a popup menu to insert pages headers.
|- valign="TOP"
| width="24%" |
.uno:InsertPageFooter
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.FooterMenuController
| width="34%" |
Provides a popup menu to insert page footers.
|- valign="TOP"
| width="24%" |
.uno:ChangeControlType
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ControlMenuController
| width="34%" |
Provides a popup menu to change the control type of a selected form control.
|- valign="TOP"
| width="24%" |
.uno:AvailableToolbars
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.ToolBarsMenuController
| width="34%" |
Provides a popup menu to show/hide toolbars.
|- valign="TOP"
| width="24%" |
.uno:ScriptOrganizer
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.MacrosMenuController
| width="34%" |
Provides a popup menu with all available scripting languages.
|- valign="TOP"
| width="24%" |
.uno:RecentFileList
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.RecentFilesMenuController
| width="34%" |
Provides a popup menu with recently opened files.
|- valign="TOP"
| width="24%" |
.uno:AddDirect
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu to create document for all available application modules.
|- valign="TOP"
| width="24%" |
.uno:AutoPilotMenu
| width="12%" |
all
| width="31%" |
com.sun.star.comp.framework.NewMenuController
| width="34%" |
Provides a popup menu with all available wizards.
|}

The menu bar is completely controlled by an UNO implementations and is not based on any old sfx2 code. Therefor old sfx2 based and new non-sfx2 application modules are equally supported.

== Toolbar ==

=== Toolbar item controller ===

Toolbar item controllers are responsible for a single toolbar button or toolbar item window (like a combobox, dropdown-box or an edit field). A toolbar item controller must support the following services and interfaces.

 

<code>[cpp]
module com { module sun { module star { module frame {

service ToolbarController
{
//-------------------------------------------------------------------------
/** 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
a com::sun::star::frame::XFrame instance to which the toolbar controller belongs.

CommandURL
a string which specifies the command a toolbar 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 toolbar controller instance is ready for use after this call has been made
the first time. The toolbar implementation guarantees that the controller's
item window has been added to the toolbar 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 toolbar implementation to forward information to and request
services from a toolbar 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::XToolbarController;

//-------------------------------------------------------------------------
/** used to notify and retrieve information that are specific for sub-toolbar
controllers.

Used by implementations that want to provide the toolbar button sub-toolbar
function feature. A controller supporting this interface exchanges the
function of its own toolbar button, that opened the sub-toolbar, with the
one that has been selected on the sub-toolbar.
*/
[optional] interface ::com::sun::star::frame::XSubToolbarController;
};

}; }; }; };
</code>

 

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

 

published interface XStatusListener: com::sun::star::lang::XEventListener

{

 /** is called when the status of the feature changes. @param State provides information about changes of the requested feature */

 [oneway] void statusChanged( [in] FeatureStateEvent State );

};

 

}; }; }; };

 

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

 

published struct FeatureStateEvent: com::sun::star::lang::EventObject

{

 //-------------------------------------------------------------------------

 /** contains the URL of the feature. */

 com::sun::star::util::URL FeatureURL;

 

 //-------------------------------------------------------------------------

 /** contains a descriptor of the feature for the user interface.*/

 string FeatureDescriptor;

 

 //-------------------------------------------------------------------------

 /** specifies whether the feature is currently enabled or disabled. */

 boolean IsEnabled;

 

 //-------------------------------------------------------------------------

 /** specifies whether the <type>XDispatch</type> has to be requeried. */

 boolean Requery;

 

 //-------------------------------------------------------------------------

 /** contains the state of the feature in this dispatch.*/

 any State;

}; 

 

}; }; }; };

 

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** provides a function to execute the command which is bound to the toolbar controller. @param a combination of <type scope="com::sun::star::awt">KeyModifier</type> value that represent the current state of the modifier keys. This function is usally called by a toolbar implementation when a user clicked on a toolbar button or pressed enter on the keyboard when the item has the input focus. */ void execute( [in] short KeyModifier ); //============================================================================= /** notifies a component that a single click has been made on the toolbar item. */ void click(); //============================================================================= /** notifies a component that a double click has been made on the toolbar item. */ void doubleClick(); //============================================================================= /** requests to create a popup window for additional functions. @return a <type scope="com::sun::star::awt">XWindow</type> which provides additional functions to the user. The reference must be empty if component does not want to provide a separate window. */ com::sun::star::awt::XWindow createPopupWindow(); //============================================================================= /** requests to create an item window which can be added to the toolbar. @param Parent a <type scope="com::sun::star::awt">XWindow</type> which must be used as a parent for the requested item window. @return a <type scope="com::sun::star::awt">XWindow</type> which can be added to a toolbar. The reference must be empty if a component does not want to provide an item window. */ com::sun::star::awt::XWindow createItemWindow( [in] com::sun::star::awt::XWindow Parent ); }; }; }; }; };

 

module com { module sun { module star { module frame { interface XSubToolbarController : com::sun::star::uno::XInterface { //============================================================================= /** if the controller features a sub-toolbar. @return <TRUE/> if the controller offers a sub toolbar, otherwise <FALSE/>. Enables implementations to dynamically decide to support sub-toolbars or not. */ boolean opensSubToolbar(); //============================================================================= /** provides the resource URL of the sub-toolbar this controller opens. @return name of the sub-toolbar this controller offers. A empty string will be interpreted as if this controller offers no sub-toolbar. */ string getSubToolbarName(); //============================================================================= /** gets called to notify a controller that a sub-toolbar function has been selected. @param aCommand a string which identifies the function that has been selected by a user. */ void functionSelected( [in] string aCommand ); //============================================================================= /** gets called to notify a controller that it should set an image which represents the current selected function. Only the controller instance is able to set the correct image for the current function. A toolbar implementation will ask sub-toolbar controllers to update their image whenever it has to update the images of all its buttons. */ void updateImage(); }; }; }; }; }; 

 

=== Generic toolbar item controller ===

A generic toolbar item controller is used by toolbar implementation for simple toolbar buttons. Normally most items of a toolbar consists of generic toolbar item controllers. They support the following generic functions by listening to status updates provided by the application module controller.

 

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action
|- valign="TOP"
| width="15%" |
State
| width="42%" |
String / SfxStringItem
| width="43%" |
Toolbar item changes its quick help and its label to the content of the provided string.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item, according to the boolean value.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item will be made visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item is set to normal or tri-state according to the provided member ItemStatus.State (see ''dont_care'' value in com.sun.star.frame.status.ItemState)
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item is enabled or disabled according to the value of IsEnabled.
|}

 

Generic toolbar item controllers are not able to support the creation of sub-toolbars or floating windows.

 

=== Specific toolbar item controllers ===

Specific toolbar item controllers are much more flexible and can support the creation of sub-toolbars or floating windows. As they are much more powerful they have sole responsibility to react correctly on status updates received by the application module controller.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="15%" |
Variable
! width="42%" |
UNO Type/Poolitem
! width="43%" |
Action required
|- valign="TOP"
| width="15%" |
State
| width="42%" |
Boolean / SfxBoolItem
| width="43%" |
Toolbar item checks or unchecks its item according to the boolean value, if this makes sense in the context.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.VisibilityItem / SfxVisibilityItem
| width="43%" |
Toolbar item should make itself visible or invisible according to the provided state.
|- valign="TOP"
| width="15%" |
State
| width="42%" |
com.sun.star.frame.status.ItemStatus ( Will be directly retrieved with Dispatcher->QueryState(...) or transported by SfxItemState ).
| width="43%" |
Toolbar item should set itself to normal or tri-state according to the provided member ItemStatus.State. It depends on the specific toolbar item if this makes sense.
|- valign="TOP"
| width="15%" |
IsEnabled
| width="42%" |
Boolean
| width="43%" |
Toolbar item must enabled or disabled itself according to the value of IsEnabled.
|}

 

Specific toolbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Toolbar when they are implemented via an UNO service.

An abstract from the Controller.xcu with registered specific toolbar item controllers:

 ...

<node oor:name="ToolBar"> <node oor:name="c1" oor:op="replace"> <prop oor:name="Command"> <value>.uno:DBNewForm</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> <node oor:name="c2" oor:op="replace"> <prop oor:name="Command"> <value>.uno:Refresh</value> </prop> <prop oor:name="Module"> <value>com.sun.star.sdb.OfficeDatabaseDocument</value> </prop> <prop oor:name="Controller"> <value>com.sun.star.sdb.ApplicationToolboxController</value> </prop> </node> </node>

 ...

 

The framework provides a base class which makes it much easier to implement UNO based specific toolbar item controllers. It can be found in svtools/inc/toolboxcontroller.hxx.

The sfx2 based specific toolbar item controllers are registered by calling ''ToolbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special toolbar controller factory to create instances of sfx2 based specific toolbar item controllers. Sfx2 based specific toolbar controllers can use the known base class sfx2/inc/tbxctrl.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based toolbar controllers.</nowiki>

 

class SFX2_DLLPUBLIC SfxToolBoxControl: public ::com::sun::star::awt::XDockableWindowListener, public ::com::sun::star::frame::XSubToolbarController, public svt::ToolboxController { friend class SfxToolbox; friend class SfxToolBox_Impl; friend class SfxToolboxCustomizer; friend class SfxPopupWindow; friend struct SfxTbxCtrlFactory; SfxToolBoxControl_Impl* pImpl; protected: DECL_LINK( PopupModeEndHdl, void * ); DECL_LINK( ClosePopupWindow, SfxPopupWindow * ); // old SfxToolBoxControl methods virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Select( BOOL bMod1 = FALSE ); virtual void Select( USHORT nModifier ); virtual void DoubleClick(); virtual void Click(); virtual SfxPopupWindowType GetPopupWindowType() const; virtual SfxPopupWindow* CreatePopupWindow(); virtual SfxPopupWindow* CreatePopupWindowCascading(); virtual Window* CreateItemWindow( Window *pParent ); // Must be called by subclass to set a new popup window instance void SetPopupWindow( SfxPopupWindow* pWindow ); // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // new controller API // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XToolbarController virtual void SAL_CALL execute( sal_Int16 KeyModifier ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createPopupWindow() throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow > SAL_CALL createItemWindow( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow >& rParent ) throw (::com::sun::star::uno::RuntimeException); // XSubToolbarController virtual ::sal_Bool SAL_CALL opensSubToolbar( ) throw (::com::sun::star::uno::RuntimeException); virtual ::rtl::OUString SAL_CALL getSubToolbarName( ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL functionSelected( const ::rtl::OUString& aCommand ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL updateImage( ) throw (::com::sun::star::uno::RuntimeException); // XDockableWindowListener virtual void SAL_CALL startDocking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual ::com::sun::star::awt::DockingData SAL_CALL docking( const ::com::sun::star::awt::DockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endDocking( const ::com::sun::star::awt::EndDockingEvent& e ) throw (::com::sun::star::uno::RuntimeException); virtual sal_Bool SAL_CALL prepareToggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL toggleFloatingMode( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL closed( const ::com::sun::star::lang::EventObject& e ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL endPopupMode( const ::com::sun::star::awt::EndPopupModeEvent& e ) throw (::com::sun::star::uno::RuntimeException); // helper methods void createAndPositionSubToolBar( const ::rtl::OUString& rSubToolBarResName ); ::Size getPersistentFloatingSize( const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XFrame >& xFrame, const ::rtl::OUString& rSubToolBarResName ); public: SFX_DECL_TOOLBOX_CONTROL(); SfxToolBoxControl( USHORT nSlotID, USHORT nId, ToolBox& rBox, BOOL bShowStrings = FALSE ); virtual ~SfxToolBoxControl(); ToolBox& GetToolBox() const; unsigned short GetId() const; unsigned short GetSlotId() const; void Dispatch( 

 const ::rtl::OUString& aCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static void Dispatch( 

const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XDispatchProvider >& rDispatchProvider, const rtl::OUString& rCommand, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& aArgs ); static SfxItemState GetItemState( const SfxPoolItem* pState ); static SfxToolBoxControl* CreateControl( USHORT nSlotId, USHORT nTbxId, ToolBox *pBox, SfxModule *pMod ); };

 

 

== Statusbar ==

=== Specific statusbar item controller ===

The statusbar implementation only supports specific statusbar item controllers. There are no generic statusbar item controllers which could provide generic functions.

A statusbar item controller must support the following services and interfaces.

module com { module sun { module star { module frame { service StatusbarController { //------------------------------------------------------------------------- /** with this interface a component can receive events if a feature has changed. The statusbar controller implementation should register itself as a listener when its <member scope="com::sun::star::util">XUpdatable</member> interface has been called. */ interface com::sun::star::frame::XStatusListener; /** used to initialize a component with required arguments. A statusbar controller needs at least three additional arguments provided as <type scope="com::sun::star::beans">PropertyValue</type>: <ul> <li>Frame a <type scope="com::sun::star::frame">XFrame</type> instance to which the toolbar controller belongs.</li> <li>CommandURL a string which specifies the command a statusbar controller is bound.</li> <li>ServiceManager a <type scope="com::sun::star::lang"> XMultiServiceFactory</type> instance which can be used to create additional UNO services.</li> </ul> */ 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 <member scope="com::sun::star::lang">XInitialitation::initialize</member> has been called. The behavior of the interface is undefined if the controller component hasn't been initialized. */ interface com::sun::star::frame::XStatusbarController; }; }; }; }; }; 

 

<code>[cpp]
module com { module sun { module star { module frame { 

published interface XStatusListener: com::sun::star::lang::XEventListener
{
/** is called when the status of the feature changes.

@param State
provides information about changes of the requested feature
*/
[oneway] void statusChanged( [in] FeatureStateEvent State );

};

}; }; }; };
</code>

<code>[cpp]
module com { module sun { module star { module frame {

published struct FeatureStateEvent: com::sun::star::lang::EventObject
{
//-------------------------------------------------------------------------
/** contains the URL of the feature.
*/
com::sun::star::util::URL FeatureURL;

//-------------------------------------------------------------------------
/** contains a descriptor of the feature for the user interface.
*/
string FeatureDescriptor;

//-------------------------------------------------------------------------
/** specifies whether the feature is currently enabled or disabled.
*/
boolean IsEnabled;

//-------------------------------------------------------------------------
/** specifies whether the XDispatch object has to be requeried.
*/
boolean Requery;

//-------------------------------------------------------------------------
/** contains the state of the feature in this dispatch.
*/
any State;

};
}; }; }; };
</code>

module com { module sun { module star { module lang { published interface XInitialization: com::sun::star::uno::XInterface { // DocMerge from xml: method com::sun::star::lang::XInitialization::initialize /** initializes the object. It should be called directly after the object is created. */ void initialize( [in] sequence<any> aArguments ) raises( com::sun::star::uno::Exception ); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module util { published interface XUpdatable: com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** refreshes the data of the object from the connected data source. */ void update(); }; //============================================================================= }; }; }; };

 

module com { module sun { module star { module frame { interface XStatusbarController : ::com::sun::star::uno::XInterface { //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been pressed. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse has been moved. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if the mouse position is within the controller and a mouse button has been released. If the controller has captured the mouse input this function is also called when the mouse position is not within the controller. @param aMouseEvent current information about the mouse pointer. @return return <TRUE/> if the event should not be processed and <FALSE/> if the event should be processed by the status bar. */ boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param aPos the current mouse position in pixel. @param nCommand describes which command has been invoked. @param bMouseEvent <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>. @param aData for future use only. */ void command( [in] ::com::sun::star::awt::Point aPos, [in] long nCommand, [in] boolean bMouseEvent, [in] any aData ); //============================================================================= /** is called by a status bar if a command event is available for a controller. @param xGraphics the current graphics which should be used for painting. @param rOutputRectangle the output rectangle for graphic operations. @param nItemId the item id of the controller. @param nStyle the style of the statusbar item. The controller should respect the provided

style when paints. */ void paint( [in] ::com::sun::star::awt::XGraphics xGraphics, [in] ::com::sun::star::awt::Rectangle rOutputRectangle, [in] long nItemId, [in] long nStyle ); //============================================================================= /** is called by a status bar if the user clicked with mouse into the field of the corresponding control. */ void click(); //============================================================================= /** is called by a status bar if the user double-clicked with mouse into the field of the corresponding control. */ void doubleClick(); }; }; }; }; };

OOo 2.0 supports two kind of specific statusbar item controllers. UNO based specific statusbar item controllers must be registered in the configuration set org.openoffice.Office.UI.Controller/Registered/Statusbar.

An abstract from the Controller.xcu with registered specific statusbar item controllers:

 ...

<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="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>

 

The framework library provides a base class in svtools/inc/statusbarcontroller.hxx which makes it simpler to implement a UNO based specific status bar controller.

The sfx2 based specific statusbar item controllers are registered by calling ''StatusbarControllerClass''<nowiki>::RegisterControl(SlotID, SfxModule* ). The framework implementation uses a special statusbar controller factory to create instances of sfx2 based specific statusbar item controllers. Sfx2 based specific statusbar controllers can use the known base class sfx2/inc/stbitem.hxx. It's a special wrapper which converts calls to the its UNO interfaces to the needs of sfx2 based statusbar controllers.</nowiki>

class SFX2_DLLPUBLIC SfxStatusBarControl: public svt::StatusbarController { USHORT nSlotId; USHORT nId; StatusBar* pBar; protected: // new controller API // XInterface virtual ::com::sun::star::uno::Any SAL_CALL queryInterface( const ::com::sun::star::uno::Type & rType ) throw(::com::sun::star::uno::RuntimeException); virtual void SAL_CALL acquire() throw(); virtual void SAL_CALL release() throw(); // XEventListener virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& aEvent ) throw( ::com::sun::star::uno::RuntimeException ); // XComponent virtual void SAL_CALL dispose() throw (::com::sun::star::uno::RuntimeException); // XStatusListener virtual void SAL_CALL statusChanged( const ::com::sun::star::frame::FeatureStateEvent& Event ) throw ( ::com::sun::star::uno::RuntimeException ); // XStatusbarController virtual ::sal_Bool SAL_CALL mouseButtonDown( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseMove( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual ::sal_Bool SAL_CALL mouseButtonUp( const ::com::sun::star::awt::MouseEvent& aMouseEvent ) throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL command( const ::com::sun::star::awt::Point& aPos, ::sal_Int32 nCommand, ::sal_Bool bMouseEvent, const ::com::sun::star::uno::Any& aData ) 

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL paint( const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XGraphics >& xGraphics, const ::com::sun::star::awt::Rectangle& rOutputRectangle, ::sal_Int32 nItemId, 

<nowiki>::sal_Int32 nStyle )</nowiki>

throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL click() throw (::com::sun::star::uno::RuntimeException); virtual void SAL_CALL doubleClick() throw (::com::sun::star::uno::RuntimeException); // Old sfx2 interface virtual void StateChanged( USHORT nSID, SfxItemState eState, const SfxPoolItem* pState ); virtual void Click(); virtual void DoubleClick(); virtual void Command( const CommandEvent& rCEvt ); virtual BOOL MouseButtonDown( const MouseEvent & ); virtual BOOL MouseMove( const MouseEvent & ); virtual BOOL MouseButtonUp( const MouseEvent & ); virtual void Paint( const UserDrawEvent &rUDEvt ); static USHORT convertAwtToVCLMouseButtons( sal_Int16 nAwtMouseButtons ); public: SfxStatusBarControl( USHORT nSlotID, USHORT nId, StatusBar& rBar ); virtual ~SfxStatusBarControl(); USHORT GetSlotId() const { return nSlotId; } USHORT GetId() const { return nId; } StatusBar& GetStatusBar() const { return *pBar; } void CaptureMouse(); void ReleaseMouse(); static SfxStatusBarControl* CreateControl( USHORT nSlotID, USHORT nId, StatusBar *pBar, SfxModule* ); };

 

 

=User interface controllers in the mixed sfx2/uno environment=

==How user interface controllers work in a pure UNO based environment?==

[[Image:EnvironmentPureUnoUserInterfaceController.png]]

==How user interface controllers work in our mixed sfx2/UNO based environment?==

[[Image:EnvironmentUserInterfaceController.png]]

Let's see what happens in more detail, especially when we switch from one layer to another one.

# A shell wants to invalidate a slot and calls SfxShell::Invalidate( SlotID ).
# The bindings updates the SfxStateCache for the provided slot ID normally through a update timer or directly.
# The SfxStateCache calls StateChanged with the new state on a SfxDispatchController_Impl object.
# The SfxDispatchController_Impl now maps the sfx2 state information based on SfxPoolItem to UNO information and sends them to UNO based toolbar controller.

...

<nowiki>::cppu::OInterfaceContainerHelper* pContnr = pDispatch->GetListeners().getContainer( aDispatchURL.Complete );</nowiki>

if ( bNotify && pContnr )

{

<nowiki>::com::sun::star::uno::Any aState;</nowiki>

 if ( ( eState >= SFX_ITEM_AVAILABLE ) && pState && !IsInvalidItem( pState ) && !pState->ISA(SfxVoidItem) )

{

 // Retrieve metric from pool to have correct sub ID when calling QueryValue

USHORT nSubId( 0 );

SfxMapUnit eMapUnit( SFX_MAPUNIT_100TH_MM );

 

 // retrieve the core metric

 // it's enough to check the objectshell, the only shell that does not 

 // use the pool of the document is SfxViewFrame, but it hasn't any metric parameters

 if ( pSlotServ && pDispatcher )

{

SfxShell* pShell = pDispatcher->GetShell( pSlotServ->GetShellLevel() );

DBG_ASSERT( pShell, "Can't get core metric without shell!" );

 if ( pShell )

eMapUnit = GetCoreMetric( pShell->GetPool(), nSID );

}

 

 if ( eMapUnit == SFX_MAPUNIT_TWIP )

nSubId |= CONVERT_TWIPS;

 

'''pState->QueryValue( aState, (BYTE)nSubId );'''

}

 else if ( eState == SFX_ITEM_DONTCARE )

{

 // Use special uno struct to transport don't care state

<nowiki>::com::sun::star::frame::status::ItemStatus aItemStatus;</nowiki>

aItemStatus.State = ::com::sun::star::frame::status::ItemState::dont_care;

aState = makeAny( aItemStatus );

}

 

<nowiki>::com::sun::star::frame::FeatureStateEvent aEvent;</nowiki>

aEvent.FeatureURL = aDispatchURL;

aEvent.Source = (::com::sun::star::frame::XDispatch*) pDispatch;

aEvent.IsEnabled = eState != SFX_ITEM_DISABLED;

aEvent.Requery = sal_False;

aEvent.State = aState;

 

<nowiki>::cppu::OInterfaceIteratorHelper aIt( *pContnr );</nowiki>

 while( aIt.hasMoreElements() )

{

 try

{

'''((::com::sun::star::frame::XStatusListener *)aIt.next())->statusChanged( aEvent );'''

}

 catch( ::com::sun::star::uno::RuntimeException& )

{

aIt.remove();

}

}

}

...

 

 

How does QueryValue work and convert an item to UNO com::sun::star::uno::any?

 

You can find the base class of any pool item in ''svtools/inc/poolitem.hxx''

class SVL_DLLPUBLIC SfxPoolItem

{

friend class SfxItemPool;

friend class SfxItemDesruptor_Impl;

friend class SfxItemPoolCache;

friend class SfxItemSet;

friend class SfxVoidItem;

 

 ULONG nRefCount; // Referenzzaehler

 USHORT nWhich;

 USHORT nKind;

 

private<nowiki>:</nowiki>

 inline void SetRefCount( ULONG n );

 inline void SetKind( USHORT n );

public<nowiki>:</nowiki>

 inline ULONG AddRef( ULONG n = 1 ) const<nowiki>;</nowiki>

private<nowiki>:</nowiki>

 inline ULONG ReleaseRef( ULONG n = 1 ) const<nowiki>;</nowiki>

 SVL_DLLPRIVATE long Delete_Impl(void<nowiki>*);</nowiki>

 

protected<nowiki>:</nowiki>

 SfxPoolItem( USHORT nWhich = 0 );

 SfxPoolItem( const SfxPoolItem& );

 

public<nowiki>:</nowiki>

''' TYPEINFO();'''

 

 virtual ~SfxPoolItem();

 void SetWhich( USHORT nId ) 

 { DBG_CHKTHIS(SfxPoolItem, 0); nWhich = nId; }

 USHORT Which() const { DBG_CHKTHIS(SfxPoolItem, 0); return nWhich; }

 virtual int operator<nowiki>==( </nowiki>const SfxPoolItem& ) const = 0;

 int operator<nowiki>!=( </nowiki>const SfxPoolItem& rItem ) const

 { return !(*this == rItem); }

 virtual int Compare( const SfxPoolItem &rWith ) const<nowiki>;</nowiki>

 virtual int Compare( const SfxPoolItem &rWith, const IntlWrapper& rIntlWrapper ) const<nowiki>;</nowiki>

 

 virtual SfxItemPresentation GetPresentation( SfxItemPresentation ePresentation,

 SfxMapUnit eCoreMetric,

 SfxMapUnit ePresentationMetric,

 XubString &rText,

 const IntlWrapper * pIntlWrapper = 0 ) const<nowiki>;</nowiki>

 

 virtual USHORT GetVersion( USHORT nFileFormatVersion ) const<nowiki>;</nowiki>

 virtual int ScaleMetrics( long lMult, long lDiv );

 virtual int HasMetrics() const<nowiki>;</nowiki>

 

 

 '''virtual BOOL QueryValue( com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 ) const<nowiki>;</nowiki>'''

''' virtual BOOL PutValue( const com::sun::star::uno::Any& rVal, BYTE nMemberId = 0 );'''

 

 virtual SfxPoolItem* Create( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SvStream& Store( SvStream &, USHORT nItemVersion ) const<nowiki>;</nowiki>

 virtual SfxPoolItem* Clone( SfxItemPool *pPool = 0 ) const = 0;

 

 ULONG GetRefCount() const { return nRefCount; }

 inline USHORT GetKind() const { return nKind; }

 

 static bool readByteString(SvStream & rStream, UniString & rString);

 static void writeByteString(SvStream & rStream,UniString const & rString);

 static bool readUnicodeString(SvStream & rStream, UniString & rString, bool bUnicode);

 static void writeUnicodeString(SvStream & rStream, UniString const & rString);

 

private<nowiki>:</nowiki>

 SfxPoolItem& operator<nowiki>=( </nowiki>const SfxPoolItem& ); // n.i.!!

};

 

A example how to implement QueryValue can be found in the implementation of the SvxULSpaceItem (located in svx/source/items/frmitems.cxx).

 

sal_Bool SvxULSpaceItem::QueryValue( uno::Any& rVal, BYTE nMemberId ) const

{

sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);

nMemberId &= ~CONVERT_TWIPS;

 switch( nMemberId )

{

 // jetzt alles signed

 case 0:

{

<nowiki>::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;</nowiki>

aUpperLowerMarginScale.Upper = (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper);

aUpperLowerMarginScale.Lower = (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nPropUpper);

aUpperLowerMarginScale.ScaleUpper = (sal_Int16)nPropUpper;

aUpperLowerMarginScale.ScaleLower = (sal_Int16)nPropLower;

rVal <<= aUpperLowerMarginScale;

 break<nowiki>;</nowiki>

}

 case MID_UP_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nUpper) : nUpper); break<nowiki>;</nowiki>

 case MID_LO_MARGIN: rVal <<= (sal_Int32)(bConvert ? TWIP_TO_MM100(nLower) : nLower); break<nowiki>;</nowiki>

 case MID_UP_REL_MARGIN: rVal <<= (sal_Int16) nPropUpper; break<nowiki>;</nowiki>

 case MID_LO_REL_MARGIN: rVal <<= (sal_Int16) nPropLower; break<nowiki>;</nowiki>

}

 return sal_True;

}

 

# The UNO based toolbar controller now has to convert the state information (com::sun::star::uno::Any) again to provide it in a format that the sfx2 based toolbar controller implementation knows (SfxPoolItem).

<code>[cpp]
// XStatusListener

void SAL_CALL SfxToolBoxControl::statusChanged( const FeatureStateEvent& rEvent )
throw ( ::com::sun::star::uno::RuntimeException )
{
SfxViewFrame* pViewFrame = NULL;
Reference < XController > xController;

::vos::OGuard aGuard( Application::GetSolarMutex() );
if ( getFrameInterface().is() )
xController = getFrameInterface()->getController();

Reference < XDispatchProvider > xProvider( xController, UNO_QUERY );
if ( xProvider.is() )
{
Reference < XDispatch > xDisp = xProvider->queryDispatch(
rEvent.FeatureURL, ::rtl::OUString(), 0 );
if ( xDisp.is() )
{
Reference< XUnoTunnel > xTunnel( xDisp, UNO_QUERY );
SfxOfficeDispatch* pDisp = NULL;
if ( xTunnel.is() )
{
sal_Int64 nImplementation = xTunnel>getSomething
SfxOfficeDispatch::impl_getStaticIdentifier() );
pDisp = (SfxOfficeDispatch*)(nImplementation);
}

if ( pDisp )
pViewFrame = pDisp->GetDispatcher_Impl()->GetFrame();
}
}

USHORT nSlotId = 0;
SfxSlotPool& rPool = SFX_APP()->GetSlotPool( pViewFrame );
const SfxSlot* pSlot = rPool.GetUnoSlot( rEvent.FeatureURL.Path );
if ( pSlot )
nSlotId = pSlot->GetSlotId();

if ( nSlotId > 0 )
{
if ( rEvent.Requery )
svt::ToolboxController::statusChanged( rEvent );
else
{
SfxItemState eState = SFX_ITEM_DISABLED;
SfxPoolItem* pItem = NULL;

if ( rEvent.IsEnabled )
{
eState = SFX_ITEM_AVAILABLE;
::com::sun::star::uno::Type pType = rEvent.State.getValueType();

if ( pType == ::getVoidCppuType() )
{
pItem = new SfxVoidItem( nSlotId );
eState = SFX_ITEM_UNKNOWN;
}
else if ( pType == ::getBooleanCppuType() )
{
sal_Bool bTemp ;
rEvent.State >>= bTemp ;
pItem = new SfxBoolItem( nSlotId, bTemp );
}
else if ( pType == ::getCppuType((const sal_uInt16*)0) )
{
sal_uInt16 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt16Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const sal_uInt32*)0) )
{
sal_uInt32 nTemp ;
rEvent.State >>= nTemp ;
pItem = new SfxUInt32Item( nSlotId, nTemp );
}
else if ( pType == ::getCppuType((const ::rtl::OUString*)0) )
{
::rtl::OUString sTemp ;
rEvent.State >>= sTemp ;
pItem = new SfxStringItem( nSlotId, sTemp );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::ItemStatus* )0) )
{
ItemStatus aItemStatus;
rEvent.State >>= aItemStatus;
eState = aItemStatus.State;
pItem = new SfxVoidItem( nSlotId );
}
else if ( pType == ::getCppuType(( const
::com::sun::star::frame::status::Visibility*)0) )
{
Visibility aVisibilityStatus;
rEvent.State >>= aVisibilityStatus;
pItem = new SfxVisibilityItem( nSlotId, aVisibilityStatus.bVisible );
}
else
{
if ( pSlot )
pItem = pSlot->GetType()->CreateItem();
if ( pItem )
{
pItem->SetWhich( nSlotId );
pItem->PutValue( rEvent.State );
}
else
pItem = new SfxVoidItem( nSlotId );
}
}

StateChanged( nSlotId, eState, pItem );
delete pItem;
}
}
}
</code>

As you can see the implementation retrieves the type of the slot and creates an empty item of that type. Now it has to use PutValue to convert the UNO com::sun::star::uno::Any back to an item. Let's see how the SvxULSpaceItem implements PutValue:

<code>[cpp]
sal_Bool SvxULSpaceItem::PutValue( const uno::Any& rVal, BYTE nMemberId )
{
sal_Bool bConvert = 0!=(nMemberId&CONVERT_TWIPS);
nMemberId &= ~CONVERT_TWIPS;

sal_Int32 nVal;
switch( nMemberId )
{
case 0:
{
::com::sun::star::frame::status::UpperLowerMarginScale aUpperLowerMarginScale;
if ( !(rVal >>= aUpperLowerMarginScale ))
return sal_False;
else
{
SetUpper((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Upper ) : aUpperLowerMarginScale.Upper));
SetLower((sal_uInt16)(bConvert ?
MM100_TO_TWIP( aUpperLowerMarginScale.Lower ) : aUpperLowerMarginScale.Lower));
if( aUpperLowerMarginScale.ScaleUpper > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleUpper;
if( aUpperLowerMarginScale.ScaleLower > 1 )
nPropUpper = aUpperLowerMarginScale.ScaleLower;
}
}

case MID_UP_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetUpper((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_LO_MARGIN :
if(!(rVal >>= nVal) || nVal < 0)
return sal_False;
SetLower((sal_uInt16)bConvert ? MM100_TO_TWIP(nVal) : nVal);
break;

case MID_UP_REL_MARGIN:
case MID_LO_REL_MARGIN:
{
sal_Int32 nRel;
if((rVal >>= nRel) && nRel > 1 )
{
if(MID_UP_REL_MARGIN == nMemberId)
nPropUpper = nRel;
else
nPropLower = nRel;
}
else
return FALSE;
}
break;

default:
DBG_ERROR("unknown MemberId");
return sal_False;
}

return sal_True;
}
</code>

'''''We should now see some very important rules that this conversion can work correctly.'''''

 

* Never use the value 0 of the nMemberID to convert the ''default part'' of an item. This will immediately break our user interface updates.
* If you want to add a new slot that can be used by the user interface, your MUST support Query- and PutValue. At least the default value 0 must be implemented.
* Never use other arguments to call a slot than the ones that are declared in your SDI file. The conversion methods in sfx2 use the type description of the slot to map UNO types to items and cannot do this for unknown arguments.

[[Category:Development]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T17:01:14Z

Dtardon: /* Items and UNO structs */

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomic or structured type is done by using a mapping table in another sdi file. Here's an example for atomic types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 SbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomic and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each member of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments were assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally in SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to an atomic type, but this mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomic type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomic types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomic members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:59:27Z

Dtardon: /* Items and UNO structs */

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomic or structured type is done by using a mapping table in another sdi file. Here's an example for atomic types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 SbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomic and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each member of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments were assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomic type, but his mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomic type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomic types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomic members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:56:57Z

Dtardon: /* Items and UNO structs */

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomic or structured type is done by using a mapping table in another sdi file. Here's an example for atomic types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 SbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomic and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomic type, but his mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomic type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomic types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomic members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:56:26Z

Dtardon: /* Items and UNO structs */

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomic or structured type is done by using a mapping table in another sdi file. Here's an example for atomic types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomic and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomic type, but his mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomic type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomic types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomic members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:55:32Z

Dtardon: /* Items and UNO structs */

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomic or structured type is done by using a mapping table in another sdi file. Here's an example for atomar types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomar and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomar type, but his mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomar type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomar types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomar members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:54:12Z

Dtardon: fix formatting of examples

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomar or structured type is done by using a mapping table in another sdi file. Here's an example for atomar types from the SFX module:
<source lang="cpp">
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</source>
It's pretty straightforward: "item" declares the type to be atomar and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<source lang="cpp">
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</source>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomar type, but his mapping is never used:
<source lang="cpp">
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</source>
The svidl compiler creates the type mappings into the following form:
<source lang="cpp">
// example for an atomar type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</source>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomar types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomar members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:34:27Z

Dtardon: fix of the previous fix :(

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<source lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</source>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<source lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</source>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<source lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</source>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<source lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</source>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<source lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</source>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<source lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</source>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomar or structured type is done by using a mapping table in another sdi file. Here's an example for atomar types from the SFX module:
<code>[cpp]
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</code>
It's pretty straightforward: "item" declares the type to be atomar and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<code>[cpp]
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</code>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomar type, but his mapping is never used:
<code>[cpp]
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</code>
The svidl compiler creates the type mappings into the following form:
<code>[cpp]
// example for an atomar type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</code>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomar types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomar members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:33:13Z

Dtardon: fix formatting of examples

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<script lang="cpp">
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</script>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<script lang="cpp">
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</script>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<script lang="cpp">
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</script>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<script lang="cpp">
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</script>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<script lang="cpp">
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</script>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<script lang="cpp">
#define SfxObjectShell
#include "sfxslots.hxx"
</script>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomar or structured type is done by using a mapping table in another sdi file. Here's an example for atomar types from the SFX module:
<code>[cpp]
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</code>
It's pretty straightforward: "item" declares the type to be atomar and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<code>[cpp]
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</code>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomar type, but his mapping is never used:
<code>[cpp]
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</code>
The svidl compiler creates the type mappings into the following form:
<code>[cpp]
// example for an atomar type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</code>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomar types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomar members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Framework/Article/Implementation of the Dispatch API In SFX2

2009-08-11T16:26:40Z

Dtardon: fix formatting of slot definitions

== Implementation of the Dispatch API in SFX2 ==

The Dispatch API as described in chapter 7.1.6 of the Developer's Guide is the backbone of our communication between "generic" UI elements and the document core implementations. 

Traditionally SFX based components implemented this communication with a much older framework based on the so called ''slots'' and their organization into ''shells''. While up to OpenOffice.org 1.1 our generic UI elements (menus, toolbars, etc.) still used the SFX based API directly to a large degree in OpenOffice.org 2.0 we changed this to using the Dispatch API exclusively, thus enabling us to share the UI components with other, not SFX based components. This paper describes how the old SFX implementation is matched to the ''DispatchProvider'' implementation that the component provides to the outside to make this happen. 

=== Commands ===

The basic entity in the dispatch API is a command, and it's represented by a ''CommandURL''. For simplifications we suppose that this CommandURL is a string (though the API transport it as a pre-parsed struct). All commands supported by our components have the form ''.uno:xxxxx'' for historical reasons, where ''xxxxx'' represents an internal command name. Examples are “.uno:Print” or “.uno:Paste”. The functionality provided by the Dispatch API is support to execute such commands and getting status information for them (enabled/disabled or explicit information if the commands represents something type, a boolean, a string etc.). 

As explained in the Developer's Guide the Dispatch API builds on the idea that such commands can be passed along a chain of Dispatch Provider objects. Every object in this chain is free to decide whether it will handle a command or wants to pass it to the next chain member. Each document window and the Frame object managing it has such a chain of Dispatch providers and at least one object in this chain belongs to the document model/view pair bound to this window. It's the so called Controller object that amongst other interfaces supports the XDispatchProvider interface.

=== Controller objects in SFX2 ===

SFX2 based components share a common base class for their Controller object implementation, SfxBaseController. It has a queryDispatch() implementation of the XDispatchProvider interface where the received CommandURLs are compared with the CommandURLs in the set of commands the particular component supports. It uses some comparable functionality in the old SFX2 framework that also is able to execute commands and give status information about them. The main difference between the old SFX2 base framework and the UNO framework is that the latter defines commands by strings (CommandURLs) and the former does it by integer values (SlotID, see below). So the main job of the queryDispatch() implementation in the SfxBaseController is to match a commandURL to the corresponding SlotID and then proceed using the internal old SFX2 implementation.

SFX2 organizes functionality in contexts that can be merged together and exposed to the outside world by a single point of contact. This contact point is an SfxDispatcher object that every SfxBaseController owns. [Remark: this ownership is indirect as the real owner of the SfxDispatcher is an SfxViewFrame; but there is always a 1:1 relationship between an SfxViewFrame and an SfxBaseController.]
The SfxDispatcher internally maintains a stack of objects, each representing a context. Examples for these contexts are “document”, “view”, “text”, “table”, “cell” etc. All these objects are derived from a common base class “SfxShell”. The complete stack of all contextual objects available in a particular situation, the “merged context”, represents the function set applicable to the current selection or cursor position in a document. Context changes inside the document's editing window cause pushing and popping of shell objects to and from the stack.

This is how a typical stack in Writer looks when the cursor is in a normal text paragraph:

* Text
* View
* Document
* Frame
* Module
* Application

The same stack when the cursor is in a text paragraph in a table:

* Text
* Table
* View
* Document
* Frame
* Module
* Application

Another stack when a graphic is selected:

* Graphic
* View
* Document
* Frame
* Module
* Application

The ''Frame'' and ''Application'' contexts are there for historical reasons, we are still in the process of moving their functionality to the framework where other ''DispatchProviders'' outside of the component take over. I omitted the "Form" context here because it's somewhat confusing. 

== Slots and Interfaces ==

Each SfxShell class has a static member called SfxInterface. It is an object containing an array of SfxSlot structs. Each “slot” represents a command supported by the context (shell) it is assigned to. So the complete SfxInterface defines the functionality an instance of the particular SfxShell class using this interface provides.

=== The SfxSlot struct ===

The “slot” struct contains all necessary information that the SfxDispatcher needs to work together with the Shell object containing the slot. The slot contains function pointers that the dispatcher can call to either execute the command represented by the slot or get status information about it. Thus the dispatcher doesn't need to know the concrete implementation classes of the shells, it can work with them through their base class (SfxShell) interface.

Other important parts of the SfxSlot struct are the “name” of the slot and the numerical ID of it, its so called SlotID. Slot names have been chosen so that they match the part after the colon in “.uno:...” CommandURLs. Mapping between CommandURLs and SlotIDs to then need a simple lookup in all SfxInterfaces of the SfxShells on the shell stack of the SfxDispatcher. More about slots can be found below.

When the SfxDispatcher is asked for support of a particular command it searches for a slot with the given internal command name starting with the top most shell on the stack and then proceeding with the next one until success. This way “higher prioritized” contexts can overrule functionality from “lower prioritized” contexts. As an example, the “document” context has a generic implementation of the “Print” command, but each particular “view” context can overrule the generic behavior and define a specific way of printing.

=== The SfxInterface class ===

The slot arrays aka SfxInterfaces are static to each shell class and so each interface is a part of the data segment of the library that contains the shell code assigned to this interface. The data for these arrays needs to be predefined in source files. Writing huge arrays into C++ source files is a very tedious work and so we use a different kind of source file that is easier to edit and have a compiler (“svidl”) that takes these files and compiles them into a generated header file containing the definition of the arrays. These idl files are located in the sdi sub folders of each SFX based project and have the extension “sdi”. The generated header file contains the definitions (not only declarations) of all “interfaces” of the library and some “#define” magic allows to have each interface generated only once. More about this process below.

=== Slots, interfaces, shells, dispatchers ===

In OOo1.x the SfxBaseController utilized its SfxDispatcher and its stack to provide a generic Dispatch object for every supported command. It gets the CommandURL in the queryDispatch call, looks for a slot on the dispatcher stack with a suitable internal command name and in case of success creates a dispatch object and returns it. There is a drawback in this approach: if the context changes (means: shells are pushed or popped) slots might appear or disappear from the stack so commands that had been supported aren't any longer or the other way around. This forces the DispatchProvider to request a complete refetching of all dispatch objects and so can be time consuming.

In OOo2.x we utilize the “slot pool” of the SFX based modules. This is the entirety of all “interfaces” (slot arrays) the module supports. On startup all interfaces register at the module class (SfxModule base class) so it is easy to iterate through its interfaces. Now a Dispatch Object is returned when the slot is found anywhere in the slot pool, even if the interface is not on the stack, but in this case the Dispatch Object reports its slots as disabled everytime it is used. This can be determined dynamically so context changes don't need external updates, it's enough to update the internal status of the already created Dispatch Objects. This approach also enables some future optimizations for the representation of slot arrays that will be discussed later.

== Slot Processing ==

In former (Pre-UNO) time the slots where not only used for command dispatching but also for the implementation of our Basic API (up to StarOffice 5.2), so the slot arrays where "real" ''interfaces''. There are a lot residues of the in the sdi files (see below), but they aren't used anymore. 

=== Slot definitions ===

The use case explains why there are two different kinds of slots, property slots and method slots, and the difference between them can be spotted easily from the definition of a slot in the sdi file. Here are two examples, the first one describing a method slot and the second one describing a property slot:

<source lang="cpp">
SfxVoidItem About SID_ABOUT
()
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]

SfxBoolItem DesignerDialog SID_STYLE_DESIGNER

[
/* flags: */
AutoUpdate = TRUE,
Cachable = Cachable,
FastCall = TRUE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

Readyonly = FALSE,

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_FORMAT;
]
</source>
Each slot is a block in rectangular bracket filled with attributes that is preceded by two lines that identify the slot and define its nature. The exact meaning of all the attributes is explained below, the most notable difference is seen in the second line of each block: the paranthesis of the "About" slot classify it as a method while the other one (without paranthesis) is a property. As explained above, this classification goes back to the old Basic API but besides that it's important for the implementation of macro recording that is also based on the Dispatch API (and for SFX component it's implemented using slots). "Method" and "property" slots are recorded differently.
 
The name in the middle of each first line of a block was used as the name of the property or method in the Basic API and today this name is the internal command name that is matched to any ".uno:xxx" CommandURLs of the Dispatch API. As an example, the slot named "Undo" is assigned to the ".uno:Undo" command. This matching requires that the internal command names have to be unique in the complete module. This uniqueness is verified by the svidl compiler that breaks in case if name clashes in a module.
 
The last part of each first line is the so called SlotID that in former times was the real identifier (not as today the internal command name) and it was also used inside the GUI element configuration files where today CommandURLs are used. So this SlotID had to be unique for the module at least, currently it's even globally unique but at least theoretically it is now obsolete. Inside the slot processing only the textual representation of the SlotID is relevant , not its numerical value.
 
Property slots have a type specified by the first part of the first line. The same data in a method slot specifies the return value of the associated method. Method slots also can gave parameters (non empty paranthesis) and a return value that could be used in the old Basic API of StarOffice, but also in internal methods of the SfxDispatcher. Strictly speaking the latter is still possible but we try to get rid of this. Here are two examples for slots with arguments, with and without return value:

<source lang="cpp">
SfxVoidItem Undo SID_UNDO
( SfxUInt16Item Undo SID_UNDO )
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Volatile,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = FALSE,
ReadyOnlyDoc = FALSE,
Toggle = FALSE,
Container = FALSE,
RecordAbsolute = FALSE,
RecordPerSet;
Synchron;

/* status */
SlotType = SfxStringItem

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_EDIT;
]

SfxObjectItem Open SID_OPENDOC
(SfxStringItem URL SID_FILE_NAME, SfxStringItem FilterName SID_FILTER_NAME, SfxStringItem OpenFlags SID_OPTIONS,
SfxStringItem Password SID_PASSWORD, SfxStringItem FilterOptions SID_FILE_FILTEROPTIONS, SfxInt16Item Version SID_VERSION,
SfxStringItem Referer SID_REFERER)
[
/* flags: */
AutoUpdate = FALSE,
Cachable = Cachable,
FastCall = FALSE,
HasCoreId = FALSE,
HasDialog = TRUE,
ReadyOnlyDoc = TRUE,
Toggle = FALSE,
Container = TRUE,
RecordAbsolute = FALSE,
RecordPerSet;
Asynchron;

/* config */
AccelConfig = TRUE,
MenuConfig = TRUE,
StatusBarConfig = FALSE,
ToolBoxConfig = TRUE,
GroupId = GID_APPLICATION;
]
</source>
As shown in the examples, property types and return values are given as ''Items'', the whole slot "API" is based on SfxPoolItems, each identified by its ID. These IDs must be unique only in the context of the method.
 
Slots are used to bind their functionality to UI elements. In former times this was done by writing the SlotIDs into the UI element configuration files, today we use CommandURLs. Binding slots to UI elements (today indirectly through the ''Dispatch Object'') means that the binding client wants to get status information from it and/or possibly wants to execute it, in most cases (means: the standard controllers) without any parameters.
 
The type of the status update information is given by the ''SlotType'' attribute. For property slots like "DesignerDialog" this is identical with its property type (and so this attribute is not explictly assigned in the block), for method slots it must be specified like shown in the "Undo" example. If a method slot doesn't specify a SlotType it has no status (except ''disabled'' or ''enabled''). So in the examples "Undo" is of type String, "DesignerDialog" of type Boolean while the other slots don't have a status.
 
A menu controller will reflect this by showing status of the "Undo" entry as its title and setting or unsetting a check mark in front of the "DesignerDialof" entry reflecting its boolean status, a toolbar controller reflects the latter one in a pressed/unpressed state, the former in different button titles (or quick help texts that replace the button title if it's switched off). Other types of status information need speccialized controller that know how to deal with this kind of information.
 
All the other attributes inside the block of a slot are ''flags'' that define the behavior of the slot at runtime. Some of the attributes are contradicting (like synchron or asynchron) and so of course only one of them can be set. The table below sums them up in one line.

{| width="80%" border="1" cellpadding="2"
!width="40%"|Attribute
!width="60%"|Meaning
|-
||Cachable (Volatile)|| Slot status is cached, sending a new status to controllers need an ''Invalidate()'' call that forces SFX to fetch a new status. Volatile slots are not cached and SFX permanently asks for status information based on a timer.
|-
|AutoUpdate || TRUE: After execution of the slot SFX automatically fetches the new status, no ''Invalidate()'' call necessary
|-
|FastCall || TRUE: SFX doesn't check "enable" status before executing a slot
|-
|Toggle || Execute without parameters automatically toggles the current status. Works for property slots with boolean or enum type.
|-
|HasCoreId || Obsolete
|-
|HasDialog || Obsolete
|-
|ReadOnlyDoc || FALSE: SFX automatically disables this slot if the document is read only
|-
|Container || TRUE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the object. FALSE: in case of OLE inplace editing this slot is automatically disabled by SFX if the component is the container.
|-
|RecordAbsolute || Obsolete
|-
|RecordPerSet (RecordPerItem, NoRecord) || See explanation for Recording.
|-
|Synchron (Asynchron) || Asynchron: SFX execute the slot by posting a user event instead of directly calling the execute function of the slot
|-
|Readonly || Obsolete
|-
|AccelConfig || Slot may be offered in the configuration dialog for keyboard shortcuts
|-
|MenuConfig || Slot may be offered in the configuration dialog for menus
|-
|StatusBarConfig || Slot may be offered in the configuration dialog for status bar
|-
|ToolboxConfig || Slot may be offered in the configuration dialog for toolbars
|-
|GroupId || Assign the slot to a function group in the configuration dialogs (module is free to define categories)
|-
|ImageRotation || Toolbar images are rotated in case of writing direction from right to left
|-
|ImageReflection || Toolbar images are rotated in case of vertical text orientation
|-
|}

=== Interface definitions ===

As already mentioned, slots are bundled to interfaces and interfaces are used by shells. SDI files know both terms. Here's an example how this looks. For clarity only a few slots are shown, the read file contains much more of them.
<code>[cpp]
interface Document : Object
[
Automation = FALSE ;
]
{
SID_CLOSEDOC
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
}

interface OfficeDocument : Document
[
Automation = FALSE
]
{
SID_DOC_MODIFIED
[
StateMethod = GetState_Impl ;
]

SID_PRINTDOC
[
ExecMethod = PrintExec_Impl ;
StateMethod = NoState ;
]
}

shell SfxObjectShell

{
import OfficeDocument [AUTOMATION];

SID_DOCINFO
[
ExecMethod = ExecFile_Impl ;
StateMethod = GetState_Impl ;
]
};
</code>
The interface term is used slightly different in the sdi files that it is used by SFX, so now we use the name "slot arrays" for what the SFX itself calls "interfaces" to avoid confusion.
 
As a residue of the old Basic API sdi files define interfaces and shells separately, thus differentiating between slots for both Basic and UI usage and slots only used for UI purposes. This is obsolete today, but still used. Additionally sdi files define base and derived interfaces and shells in a granularity we don't need anymore, but this is also a residue of the StarBasic support. This might change in the near future. Some interfaces even contained real basic properties that are '''not''' represented by slots at all (like the "object" interface referenced in the example) but they are not used anymore.
 
The "shell" defined in the file references a C++ implementation class SfxObjectShell. This part of the sdi file defines the complete slot interface of this class. The "import" statement tells the svidl compiler that it should add all slots of the interface "OfficeDocument" here (and of course all slots of its "base class" interfaces).
 
The "Automation" attribute that is assigned to both interfaces and shells tells the svidl compiler whether it should generate a slot array definition for this interface/shell or not. We only generate arrays for shell, not for interfaces (because we don't need them anymore). In former times we also generated arrays for interfaces, and the "Automation" attribute allowed us to prevent svidl from generating them for base class interfaces also. The "Automation" attribute will become obsolete pretty soon.
 
Inside the interface/shell definition block slots are referenced by their SlotID. Svidl will get all attributes of the slot it needs to generate the array definition from the slot definition (that of course needs to be included and processed before svidl gets to the shell definition). In the block below this identifier (again with rectangular brackets) two additional attributes are specified: the names of one or two methods can be defined that SFX calls to get status information or execute the slot. These methods have a prescribed signature:
<code>[cpp]
void Class::StateMethod( SfxItemSet& );
void Class::ExecMethod( SfxRequest& );
</code>
The ItemSet is used to collect the status information, the SfxRequest contains everything necessary for the execution of a slot.
 
The svidl compiler takes the shell class name and the method name and generates an inline stub function that calls the C++ member. A pointer to each stub is generated into the slot definitions. The stubs are generated into the same header file that contains the generated arrays. Here is an example for the first slot of the interface "Document" shown above:
<code>[cpp]
SFX_EXEC_STUB( SfxObjectShell, ExecFile_Impl )
SFX_STATE_STUB( SfxObjectShell, GetState_Impl )
</code>
We use function stubs here because pointer to member functions don't have a fixed size and so we can't store them inside a struct like SfxSlot. A pointer to a C function always has the same size as normal pointer on the machine.
 
The slots in our example show that both pointers can be set or only one of them. A slot without an "Exec" function is a slot that only has a status, execution is done by another slot. A slot without a "GetState" function is always enabled and has no status. SFX automatically generates empty stub in these cases.
 
Inside the block defining the functions theoretically all slot attributes of the referenced slot can be overwritten and sometimes this can be found. This should be seen as exceptional cases and it might happen in the near future that this overwriting will become forbidden for more and more attributes. The benefit of this is very limited but the risk of dangerous inconsistencies is high.
 
Here's an exerpt of the generated header file that belongs to the SID_CLOSEDOC slot shown above:
<code>[cpp]
SFX_SLOTMAP_ARG(SfxObjectShell)
{
// Slot Nr. 0 : 5502
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_SAVEASDOC,SID_SAVEASDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[1] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_SYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
0/*Offset*/, 9/*Count*/,".SaveAs",SFX_SLOT_METHOD|0,"SaveAs" ),
// Slot Nr.1 : 5503
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_CLOSEDOC,SID_CLOSEDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[3] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR(SfxObjectShell,GetState_Impl),
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
9/*Offset*/, 2/*Count*/,".CloseDoc",SFX_SLOT_METHOD|0,"CloseDoc" ),
// Slot Nr.2 : 5504
SFX_NEW_SLOT_ARG( SfxObjectShell,SID_PRINTDOC,SID_PRINTDOC,GID_DOCUMENT,
0,&aSfxObjectShellSlots_Impl[2] /* Offset Next*/,
SFX_STUB_PTR(SfxObjectShell,ExecFile_Impl),SFX_STUB_PTR_NONE,
SFX_SLOT_CACHABLE|SFX_SLOT_ASYNCHRON|SFX_SLOT_RECORDPERSET|SFX_SLOT_HASDIALOG|SFX_SLOT_MENUCONFIG|
SFX_SLOT_TOOLBOXCONFIG|SFX_SLOT_ACCELCONFIG|SFX_SLOT_CONTAINER|SFX_SLOT_READONLYDOC|0,
0,
SfxStringItem,
11/*Offset*/, 10/*Count*/,".Print",SFX_SLOT_METHOD|0,"Print" ),

// ... to be continued ...
</code>
The SFX_NEW_SLOT_ARG macro initializes a complete slot. Most of it should be pretty obvious from what was described already, please note the macros for the generated stubs (and especially SFX_STUB_PTR_STATE_NONE for the empty stub).
 
An interesting addition is the second line of each block, it contains an "Offset Next". It is a pointer that points to the next slot in this shell that uses the same "GetState" method as the current slot. This enables SFX to collects status information for several slots at once when a complete update is requested. In general the shell code allows to group slots together in Exec/GetState methods and have more than one per shell for clarity reasons.
 
The last line in each block also contains an offset and a count. These attributes point to the arguments of the slot (of course only for methods). All possible arguments of all slots inside a shell are grouped into a single array, arguments that belong to the same slot of course beneath each other. The offset points to the first argument of a slot:
<code>[cpp]
SFX_ARGUMENTMAP(SfxObjectShell)
{
SFX_ARGUMENT(SID_FILE_NAME,"URL",SfxStringItem),
SFX_ARGUMENT(SID_FILTER_NAME,"FilterName",SfxStringItem),
SFX_ARGUMENT(SID_PASSWORD,"Password",SfxStringItem),
SFX_ARGUMENT(SID_FILE_FILTEROPTIONS,"FilterOptions",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_COMMENTS,"VersionComment",SfxStringItem),
SFX_ARGUMENT(SID_DOCINFO_AUTHOR,"VersionAuthor",SfxStringItem),
SFX_ARGUMENT(SID_OVERWRITE,"Overwrite",SfxBoolItem),
SFX_ARGUMENT(SID_UNPACK,"Unpacked",SfxBoolItem),
SFX_ARGUMENT(SID_SAVETO,"SaveTo",SfxBoolItem),
SFX_ARGUMENT(SID_CLOSEDOC_SAVE,"SaveChanges",SfxBoolItem), // <---- here args for SID_CLOSEDOC start
SFX_ARGUMENT(SID_CLOSEDOC_FILENAME,"FileName",SfxStringItem), // "count" is 2, so this is the second one

// ... to be continued ...
};
</code>
In each module one header file containing all shells is created. It must be included in the source file of each shell class that contains the SFX_IMPL_INTERFACE macro. To avoid multiple definitions of the slot arrays by this multiple inclusion each code block assigned to a particular shell is framed by an "#ifdef ClassName" block, so in the source file the typical code sequence is
<code>[cpp]
#define SfxObjectShell
#include "sfxslots.hxx"
</code>
Other parts of the header file are framed by "#ifdef SFX_TYPEMAP" and this part mustbe activated only once also so each module contains one file that includes the generated header file and defined SFX_TYPEMAP before. This can be on e of the shell files that also defines its shell interface or it can be a different one. The part of the generated header file that is activated here is not necessary for the SFX core (the slot dispatching), but was necessary in former times for the type information of the old Basic API and for macro recording. Today it is used for the wrapper that mediates between SFX dispatching and the Dispatch API and thus also for macro recording because the current macro recorder also uses the Dispatch API.

=== Items and UNO structs ===

The old SFX based Basic API was made up by the property and method slot defined in the sdi files. All types are specified as SfxPoolItems and this was fine for StarBasic because internally these types are used also (for Sbx classes). For recording purposes it was necessary to know the "real" types behind a particular SfxPoolItem type and especially structured items needed to be split up into basic types because StarBasic doesn't support structs.
 
The mapping from a SfxPoolItem to an atomar or structured type is done by using a mapping table in another sdi file. Here's an example for atomar types from the SFX module:
<code>[cpp]
item void SfxVoidItem
item BOOL SfxBoolItem
item INT32 SfxUInt16Item
item INT16 SfxInt16Item
item INT32 SfxUInt32Item
item INT32 SfxInt32Item
item String SfxStringItem
item BYTE SfxByteItem
item INT16 SfxEnumItem
item INT16 SfxAllEnumItem
item INT16 TbxImageItem
</code>
It's pretty straightforward: "item" declares the type to be atomar and it is followed by the Basic (or better: UNO) type and the Item representing it.
 
Structured types are a little bit more complicated:
<code>[cpp]
struct Point
{
INT32 X MID_X;
INT32 Y MID_Y;
};
item Point SfxPointItem;

struct Rectangle
{
INT32 Left MID_RECT_LEFT;
INT32 Top MID_RECT_TOP;
INT32 Width MID_WIDTH;
INT32 Height MID_HEIGHT;
};
item Rectangle SfxRectangleItem;

struct DocInfo
{
BOOL UseUserData MID_DOCINFO_USEUSERDATA;
BOOL DeleteUserData MID_DOCINFO_DELETEUSERDATA;
String Title MID_DOCINFO_TITLE;
String Subject MID_DOCINFO_SUBJECT;
String KeyWords MID_DOCINFO_KEYWORDS;
String Description MID_DOCINFO_KEYWORDS;
BOOL AutoReload MID_DOCINFO_AUTOLOADENABLED;
};
item DocInfo SfxDocumentInfoItem;
</code>
The examples show simple structs like a Point or more complex structs like a DocInfo. Structs can be nested, a DocInfo could contain a Point also. In the old StarBasic and also in todays macro recording each number of a struct was represented by an individual item (so an ID was needed that is unique in the complete argument set) and the names of these arguments where assembled from the name of the struct parameter name and the member name in the obvious from ArgName.MemberName.
 
For some items that are used only internally SFX based code (but not for recording purposes) no mapping was necessary and for syntactical completeness they are mapped to any atomar type, but his mapping is never used:
<code>[cpp]
item String SbxItem; //! Dummy
item String SfxObjectItem; //! Dummy
item String SfxTemplateItem; //! Dummy
item String SfxMacroInfoItem; //! Dummy
item String SfxImageItem; //! Dummy
item String SfxFrameItem; //! Dummy
item String SfxObjectShellItem; //! Dummy
</code>
The svidl compiler creates the type mappings into the following form:
<code>[cpp]
// example for an atomar type
#ifdef SFX_TYPEMAP
SfxType0 aSfxStringItem_Impl =
{
TYPE(SfxStringItem), 0
};
#endif

// example for a struct with 4 members
extern SfxType4 aSfxRectangleItem_Impl;
#ifdef SFX_TYPEMAP
SfxType4 aSfxRectangleItem_Impl =
{
TYPE(SfxRectangleItem}, 4, { {MID_RECT_LEFT,"Left"}, {MID_RECT_TOP,"Top"}, {MID_WIDTH,"Width"},
{MID_HEIGHT,"Height"} }
};
#endif
</code>
It utilizes the TOOLS based RTTI that allows to offer a static factory method by using one of the TYPEINIT_AUTOFACTORY macros. This factory that can be used to create an item of the particular class. This is very important for the conversion routines that match items to UNO structs and vice versa. An item that does not offer a factory can't be converted properly and so macro recording and Dispatch API are broken for this item.
 
The conversion between an item and a UNO type uses the virtual PutValue and QueryValue methods of the items. In the case of macro recording (where only atomar types are allowed) the "MemberID" parameter of these calls is used always in case of structured items and so it is important that the MIDs in the sdi file match the MIDs used in the implementation of the item. As an example, an SfxRectangleItem is recorded as two integer values.
 
The matching we use for the Dispatch API in our controllers on the other hand always converts to complete structs, not to atomar members, so the SfxRectangleItem is converted to a com.sun.star.awt.Rectangle. The rect Put/QueryValue in this case is called with MID=0. It's vital for this process that '''"0" is an invalid MID''' that must not be used for any member.

[[Category:Development]]
[[Category:Article]]
[[Category:Framework]]
[[Category:Framework:Article]]

Drawing framework

2009-03-24T09:21:13Z

Dtardon: /* Providing a New Resource */

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations were.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or be able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<source lang="cpp">
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<source lang="cpp">
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</source>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</source>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<source lang="cpp">
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</source>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<source lang="cpp">
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</source>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<source lang="cpp">
class SlideSorterBarManager : public XConfigurationChangeListener
{
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
}

};
</source>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<source lang="cpp">
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</source>
<source lang="cpp">
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</source>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<source lang="xml">
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</source>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FrameworkHelper::msRightPaneURL));
</source>

[[Category:Impress]]

Drawing framework

2009-03-24T09:09:01Z

Dtardon: /* Reacting to Modifications of the Configuration */

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations were.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or be able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<source lang="cpp">
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<source lang="cpp">
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</source>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</source>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<source lang="cpp">
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</source>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<source lang="cpp">
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</source>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<source lang="cpp">
class SlideSorterBarManager : public XConfigurationChangeListener
{
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
}

};
</source>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<source lang="cpp">
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</source>
<source lang="cpp">
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</source>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<source lang="xml">
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</source>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</source>

[[Category:Impress]]

Drawing framework

2009-03-24T08:36:26Z

Dtardon: Marked the code listings as source code

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations were.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or be able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<source lang="cpp">
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<source lang="cpp">
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</source>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</source>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</source>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<source lang="cpp">
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</source>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<source lang="cpp">
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</source>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<source lang="cpp">
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</source>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<source lang="cpp">
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</source>
<source lang="cpp">
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</source>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<source lang="xml">
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</source>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<source lang="cpp">
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</source>

[[Category:Impress]]

Drawing framework

2009-03-24T07:33:35Z

Dtardon: /* FrameworkHelper */

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations were.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or be able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<pre>
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<pre>
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</pre>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<pre>
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<pre>
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</pre>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<pre>
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</pre>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<pre>
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</pre>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<pre>
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</pre>
<pre>
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</pre>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<pre>
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</pre>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</pre>

[[Category:Impress]]

Drawing framework

2009-03-24T06:07:01Z

Dtardon: /* Two phase updates */

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations were.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or are able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<pre>
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<pre>
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</pre>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<pre>
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<pre>
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</pre>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<pre>
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</pre>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<pre>
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</pre>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<pre>
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</pre>
<pre>
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</pre>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<pre>
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</pre>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</pre>

[[Category:Impress]]

Drawing framework

2009-03-24T06:05:26Z

Dtardon:

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations where.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or are able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<pre>
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<pre>
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</pre>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<pre>
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<pre>
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</pre>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<pre>
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</pre>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<pre>
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</pre>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<pre>
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</pre>
<pre>
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</pre>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<pre>
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</pre>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</pre>

[[Category:Impress]]

Programming OOoDraw and OOoImpress

2009-03-15T09:48:12Z

Dtardon:

==Introduction==
OOoDraw is my favorite application of OpenOffice.org suite. I think then I will spend a lot of time with this chapter. I start writing this chapter with the Help of Christian post in OOoForum (Code snippets)
[http://www.oooforum.org/forum/viewtopic.phtml?t=11128 Working with a Presentation Document in C++]
In this chapter, we use again the starting code described [[UNO_automation_with_a_binary_%28executable%29 | here ]]. It consists of a subprogram “ooConnect()” and a main. Working with this code consists of adding new code in the main (see the red comment). We give again the main program slightly modified to fit OOoDraw requirements :
<source lang="cpp">
//Listing 1 Again the starting Code
// C++
// adapted for OOoDraw
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();
if( rOfficeServiceManager.is() ){
printf( "Connected sucessfully to the office\n" );
}

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
if( rComponentLoader.is() ){
printf( "XComponentloader successfully instanciated\n" );
}

//get an instance of the OOoDraw document
Reference< XComponent > xcomponent = rComponentLoader->loadComponentFromURL(
OUString::createFromAscii("private:factory/sdraw"),
OUString::createFromAscii("_blank"),
0,
Sequence < ::com::sun::star::beans::PropertyValue >());
// add code here
return 0;
}
</source>

You can find more explanations [[IDL_Files_and_Cpp#IDL__and_C.2B.2B|here]] (if you are not a beginner).

=Finding the drawing Slide=
Bear in mind that if OOoSheet opens with three sheets by default, OOoDraw opens with only one page/slide (index 0).
== An existing Slide ==
If only the index of the slide is known, have look at <idl>com.sun.star.drawing.XDrawPagesSupplier</idl> and <idl>com.sun.star.container.XIndexAccess</idl> interfaces :

<source lang="cpp">
//Listing 2 Index access to a draw Slide
// C++
// Don't forget to add : using namespace com::sun::star::drawing;
// Don't forget to add : #include <com/sun/star/drawing/XDrawPagesSupplier.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawPagesSupplier \" in the makefile
// Don't forget to add : using namespace com::sun::star::container;
// Don't forget to add : #include <com/sun/star/container/XIndexAccess.hpp>
// Don't forget to add "com.sun.star.container.XIndexAccess \" in the makefile

Reference< XDrawPagesSupplier > rDrawDoc(xcomponent, UNO_QUERY);

// query the XDrawPages Interface
Reference< XDrawPages > rDrawPages = rDrawDoc->getDrawPages();

// query the XIndexAccess Interface
Reference< XIndexAccess > rPageIndexAccess(rDrawPages, UNO_QUERY);

Any DrawPage = rPageIndexAccess->getByIndex(0);
</source>

If you want to know how many pages belong to your document, you can reach it from rPageIndexAccess object with :
<source lang="cpp">
//Listing 3 How many Slides ?
// C++
rPageIndexAccess->getCount();
</source>
If you only know the page name (see <idl>com.sun.star.container.XNameAccess</idl> interface):
<source lang="cpp">
//Listing 4 Slide Name Access
//C++
// Don't forget to add : #include <com/sun/star/container/XNameAccess.hpp>
// Don't forget to add "com.sun.star.container.XNameAccess \" in the makefile

//query the XNameAccess Interface
Reference< XNameAccess > rNameAccess(rDrawPages, UNO_QUERY);

if (rNameAccess->hasByName(OUString::createFromAscii("Slide 1"))) {
Any DrawPage = rNameAccess->
getByName(OUString::createFromAscii("Slide 1"));
}
</source>

==Create, rename, copy and remove a Slide ==
=== Create===
Create a new slide with a known Index (see <idl>com.sun.star.drawing.XDrawPagesSupplier</idl>, <idl>com.sun.star.drawing.XDrawPage</idl>, <idl>com.sun.star.drawing.XDrawPages</idl> and <idl>com.sun.star.container.XIndexAccess</idl> interfaces) :
<source lang="cpp">
//Listing 5 Creating a new Slide
// C++
// Don't forget to add : using namespace com::sun::star::drawing;
// Don't forget to add : #include <com/sun/star/drawing/XDrawPagesSupplier.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawPagesSupplier \" in the makefile
// Don't forget to add : using namespace com::sun::star::container;
// Don't forget to add : #include <com/sun/star/container/XIndexAccess.hpp>
// Don't forget to add "com.sun.star.container.XIndexAccess \" in the makefile

Reference< XDrawPagesSupplier > rDrawDoc(xcomponent, UNO_QUERY);

// query the XDrawPages Interface
Reference< XDrawPages > rDrawPages = rDrawDoc->getDrawPages();

// query for the XDrawPage Inteface
Reference< XDrawPage > rDrawPage = rDrawPages->insertNewByIndex(2);
</source>
In this example, the new slide is indexed with value 2 and then its default name is “Slide 3”. You can see a difference between [[Programming_OOoDraw_and_OOoImpress#An_existing_Slide|previous code]] and this one : the former uses an Any type variable (DrawPage) although the latter code obtains directly a <idl>com.sun.star.drawing.XDrawPage</idl> interface. One more step is needed to obtain a <idl>com.sun.star.drawing.XDrawPage</idl> when working with Any : a UNO query. Add the above code to the former and you obtain like the latter code a <idl>com.sun.star.drawing.XDrawPage</idl> interface.
<source lang="cpp">
//Listing 6 Accessing the XDrawPage Service
// C++
// Don't forget to add : #include <com/sun/star/drawing/XDrawPage.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawPage \" in the makefile
// Query the XDrawPage Interface
Reference< XDrawPage > rDrawPage(DrawPage, UNO_QUERY);
</source>

===Rename===
How to rename your slide ? You have to change the Name property of the slide (see <idl>com.sun.star.container.XNamed</idl> interface):
<source lang="cpp">
//Listing 7 Renaming a Slide
// C++
// Don't forget to add : #include <com/sun/star/container/XNamed.hpp>
// Don't forget to add "com.sun.star.container.XNamed \" in the makefile

// query for the XNamed Interface
Reference< XNamed > rNamed(rDrawPage, UNO_QUERY);
rNamed->setName(OUString::createFromAscii("My second page"));
</source>
The <idl>com.sun.star.container.XNamed</idl> interface is your friend as seen in this code. The corresponding IDL code is given now :
<source lang="idl">
// IDL
module com { module sun { module star { module container {

interface XNamed: com::sun::star::uno::XInterface
{
string getName();
[oneway] void setName( [in] string aName );
};
}; }; }; };
</source>
As seen only two methods are available setName already used in the example and getName.
We have already focused our attention on the difference between PageDraw and rPageDraw variables : please note we can use both in the previous code.
===Copy===
And now you want to copy a page : you have to query the <idl>com.sun.star.drawing.XDrawPageDuplicator</idl> interface.
We have to pass a draw page reference to the method duplicate(). A new draw page is appended at the end of the page list, using the default naming scheme for pages, Slide n .
<source lang="cpp">
//Listing 8 This Listing doesn't work at the Moment
// C++ to check (doesn't work !!!)
// Don't forget to add : #include <com/sun/star/drawing/XDrawPageDuplicator.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawPageDuplicator \" in the makefile

// query for the XDrawPageDuplicator Interface
Reference< XDrawPageDuplicator > rDrawPageDuplicator(rDrawPage(s)???, UNO_QUERY);

Reference< XDrawPage> rDrawPage2 = rDrawPageDuplicator->duplicate(rDrawPage);
// This last line doesn't work
</source>
===Remove===
If you want to remove a page known by its index (see <idl>com.sun.star.drawing.XDrawPagesSupplier</idl> and <idl>com.sun.star.container.XIndexAccess</idl> interfaces)
<source lang="cpp">
//Listing 9 Index access
// C++
// Don't forget to add : using namespace com::sun::star::drawing;
// Don't forget to add : #include <com/sun/star/drawing/XDrawPagesSupplier.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawPagesSupplier \" in the makefile
// Don't forget to add : using namespace com::sun::star::container;
// Don't forget to add : #include <com/sun/star/container/XIndexAccess.hpp>
// Don't forget to add "com.sun.star.container.XIndexAccess \" in the makefile

Reference< XDrawPagesSupplier > rDrawDoc(xcomponent, UNO_QUERY);

// query the XDrawPages Interface
Reference< XDrawPages > rDrawPages = rDrawDoc->getDrawPages();

// query for the XDrawPage Inteface
Reference< XDrawPage > rDrawPage = rDrawPages->insertNewByIndex(0);

rDrawPages->remove(rDrawPage);
</source>
Removing a page known by its name is let as an exercise.

== Setting the Focus on a Slide==
If you obtain a <idl>com.sun.star.drawing.XDrawPage</idl> interface corresponding to a hidden page and you want to put it on the top, have a look on <idl>com.sun.star.frame.XModel</idl> and <idl>com.sun.star.drawing.XDrawView</idl> interfaces :
<source lang="cpp">
//Listing 10 Setting a Slide as currently focused
// C++
// First Obtain a XDrawPage interface for this page, and after :

// Don't forget to add : using namespace com::sun::star::frame;
// Don't forget to add : #include <com/sun/star/frame/XModel.hpp>
// Don't forget to add "com.sun.star.frame.XModel \" in the makefile

// Don't forget to add : #include <com/sun/star/drawing/XDrawView.hpp>
// Don't forget to add "com.sun.star.drawing.XDrawView \" in the makefile

// Query the XModel Interface
Reference< XModel > rmodel(rDrawDoc, UNO_QUERY);
Reference< XController > ctl = rmodel->getCurrentController();

// Query the XDrawView interface
Reference< XDrawView > rDrawView(ctl, UNO_QUERY);
rDrawView->setCurrentPage(rDrawPage);
</source>

See also <idl>com.sun.star.frame.XModel</idl> and <idl>com.sun.star.drawing.XDrawView</idl>.

==Property of a Slide==
Properties belong to the slide are presented :
; slide's properties
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |Properties||Signification
|- style="text-align:center"
| Name ||Name of the slide
|- style="text-align:center"
| BorderLeft ||Left margin in 1/100 mm
|- style="text-align:center"
| BorderRight||Right margin in 1/100 mm
|- style="text-align:center"
| BorderTop ||Top margin in 1/100 mm
|- style="text-align:center"
| MBorderBottom ||Bottom margin in 1/100 mm
|- style="text-align:center"
| Height ||Height of the page in 1/100 mm
|- style="text-align:center"
| Width ||Width of the page in 1/100 mm
|- style="text-align:center"
| Number ||Number of the page begins from 1
|- style="text-align:center"
| Orientation ||Portrait : com.sun.star.view.PaperOrientation.PORTRAIT
or
Landscape : com.sun.star.view.PaperOrientation.LANDSCAPE
|}

If you want for instance retrieve the page width (a property), use this code with the <idl>com.sun.star.beans.XPropertySet</idl> interface :
<source lang="cpp">
//Listing 11 Slide Properties
// C++
// Don't forget to add : using namespace com::sun::star::beans;
// Don't forget to add : #include <com/sun/star/beans/XPropertySet.hpp>
// Don't forget to add "com.sun.star.beans.XPropertySet \" in the makefile
// find out page width
Reference< XPropertySet > rPageProps(rDrawPage, UNO_QUERY);

Any ApageWidth = rPageProps->getPropertyValue(OUString::createFromAscii("Width"));
sal_Int32 pageWidth;
ApageWidth >>= pageWidth;
</source>
If you want to set the four page margins properties you can use this code :
<source lang="cpp">
//Listing 12 Margin Properties
// C++
// Obtain rPageProps like previous code
Any props[4];
props[0] <<= (short)1200;
props[1] <<= (short)1200;
props[2] <<= (short)1200;
props[3] <<= (short)1200;

rPageProps->setPropertyValue(OUString::createFromAscii("BorderLeft"),props[0]);
rPageProps->setPropertyValue(OUString::createFromAscii("BorderRight"),props[1]);
rPageProps->setPropertyValue(OUString::createFromAscii("BorderTop"),props[2]);
rPageProps->setPropertyValue(OUString::createFromAscii("BorderBottom"),props[3]);
</source>
An other simpler way is to use the build in makeAny function :
<source lang="cpp">
//Listing 13 Margin Properties and makeAny Function
// C++
// Obtain rPageProps like previous code
rPageProps->
setPropertyValue(OUString::createFromAscii("BorderLeft"),makeAny((short)1200));
rPageProps->
setPropertyValue(OUString::createFromAscii("BorderRight"),makeAny((short)1200));
rPageProps->
setPropertyValue(OUString::createFromAscii("BorderTop"),makeAny((short)1200));
rPageProps->
setPropertyValue(OUString::createFromAscii("BorderBottom"),makeAny((short)1200));
</source>
It's time now to draw shapes on pages.

== Going further with Inspector ==

[[Object Inspector|The new object inspector]] is able to generate Java or C++ or OOoBasic code. In order to try inspector ability to generate C++ code, we want to use it for the following problem : obtaining the default selected slide from a draw document. See also [[Programming_OooWriter#Going_further_with_Inspector|similar problem with writer document]] and particularly the definition of an IDL-tree.

Using inspector gives us the following IDL-tree :

<pre>
MyDocument ->methods
->com.sun.star.frame.XController getCurrentController()
->xController->methods
-> xDrawPage getCurrentPage
->String getName return Slide 2
</pre>

The corresponding C++ code atomatically generated is presented below. It use <idl>com.sun.star.frame.XModel</idl>, <idl>com.sun.star.frame.XController</idl>, <idl>com.sun.star.drawing.XDrawView</idl>, <idl>com.sun.star.drawing.XDrawPage</idl> and <idl>com.sun.star.container.XNamed</idl> interfaces, but a closer look shows you have to add include directives :
<source lang="cpp">
#include "com/sun/star/frame/XModel.hpp"
#include "com/sun/star/uno/Reference.hxx"
#include "com/sun/star/uno/XInterface.hpp"
#include "rtl/ustring.hxx"
#include "sal/config.h"
#include "sal/types.h"

namespace css = com::sun::star;
using namespace rtl;

//...
void codesnippet(const css::uno::Reference<css::uno::XInterface>& _oUnoEntryObject ){{
css::uno::Reference<css::frame::XModel> xModel( _oUnoEntryObject, css::uno::UNO_QUERY_THROW);
css::uno::Reference<css::frame::XController> xController = xModel->getCurrentController();
css::uno::Reference<css::drawing::XDrawView> xDrawView( xController, css::uno::UNO_QUERY_THROW);
css::uno::Reference<css::drawing::XDrawPage> xDrawPage = xDrawView->getCurrentPage();
css::uno::Reference<css::container::XNamed> xNamed( xDrawPage, css::uno::UNO_QUERY_THROW);
OUString sName = xNamed->getName();
}
//...
</source>
{{Documentation/Caution|I have not checked this code at the moment. I have probably to add any include directives and because we don't encounter "any" type during the IDL-tree traversing, we probably haven't to modify C++ source of codesnippet sub.}}

=Drawing with OOoDraw=
==Inserting a Shape==
With OOoDraw text is considered as a shape like rectangle, ellipses... Let's then start with a <idl>com.sun.star.drawing.TextShape</idl> service and <idl>com.sun.star.drawing.XShape</idl>, <idl>com.sun.star.drawing.XShapes</idl> and <idl>com.sun.star.text.XText</idl> interfaces:
<source lang="cpp">
//Listing 14 Inserting a text Shape
// C++
// Don't forget to add :using namespace com::sun::star::awt; for Point and Size

// Don't forget to add : #include <com/sun/star/drawing/XShape.hpp>
// Don't forget to add "com.sun.star.drawing.XShape \" in the makefile

// Don't forget to add : #include <com/sun/star/drawing/XShapes.hpp>
// Don't forget to add "com.sun.star.drawing.XShapes \" in the makefile
// Don't forget to add : using namespace com::sun::star::text;
// Don't forget to add : #include <com/sun/star/text/XText.hpp>
// Don't forget to add "com.sun.star.text.XText \" in the makefile

Reference< XMultiServiceFactory > DocFactory(xcomponent, UNO_QUERY);
Reference< XInterface > textshape = DocFactory->createInstance(
OUString::createFromAscii("com.sun.star.drawing.TextShape") );
Reference< XShape > rTxtShape(textshape, UNO_QUERY);

Point *Pos = new ( Point );
Size *TheSize = new ( Size );
Pos->X = 2000;
Pos->Y = 6000;
TheSize->Width = 7000;
TheSize->Height = 2000;
rTxtShape->setPosition(Pos);
rTxtShape->setSize(*TheSize);

// Query XShapes Interface
Reference< XShapes > Shapes(rDrawPage, UNO_QUERY);
Shapes->add(rTxtShape);

// Query the XText Interface
Reference< XText > rText(rTxtShape, UNO_QUERY);
rText->setString(OUString::createFromAscii("Hello people around the world"));
</source>
This listing when executed writes out “Hello people around the world” on a page.
Changing a shape is simple : if you want to draw a rectangle, the only line to change is :
<source lang="cpp">
// Listing 15 Change this Line
// C++
Reference< XInterface > textshape = DocFactory->createInstance(
OUString::createFromAscii("com.sun.star.drawing.TextShape") );
</source>
with corresponding service <idl>com.sun.star.drawing.RectangleShape</idl>:
<source lang="cpp">
//Listing 16 Inserting a Rectangle Shape
// C++
Reference< XInterface > textshape = DocFactory->createInstance(
OUString::createFromAscii("com.sun.star.drawing.RectangleShape") );
</source>
We shall examine how to draw a shape again later. Note that you can write text too with this new shape as explained now.

==Writing Text in a Shape==
Writing text in a shape is obtained with the same way as writing text in a TextShape. For a RectangleShape (rRecShape) we have then to query a <idl>com.sun.star.text.XText</idl> interface :
<source lang="cpp">
//Listing 17 setString method to insert a Text
// C++
// Query the XText Interface
Reference< XText > rText(rRecShape, UNO_QUERY);
rText->setString(OUString::createFromAscii("Hello"));
</source>
which draws a rectangle and writes out “Hello” in this rectangle.

==Giving a Name to the Shape==

Every shape can receive a name. This feature is very interesting if you want transform OOoDraw as a graphical front-end. Here is a code example which give a name to a shape with <idl>com.sun.star.beans.XPropertySet</idl> interface :
<source lang="cpp">
//Listing 18 Naming a Shape
// C++
// Don't forget to add : using namespace com::sun::star::beans;
// Don't forget to add : #include <com/sun/star/beans/XPropertySet.hpp>
// Don't forget to add "com.sun.star.beans.XPropertySet \" in the makefile

// Query the XPropertySet Interface
Reference< XPropertySet > shapeprops(rtxtShape, UNO_QUERY);
shapeprops->setPropertyValue(OUString::createFromAscii("Name"),
makeAny(OUString::createFromAscii("demo")));
</source>
The XShapes interface allows adding, removing as shown in the IDL file :
<source lang="idl">
//Listing 19 Index access to Shapes (IDL file)
// IDL
interface XShapes: com::sun::star::container::XIndexAccess
{
void add( [in] com::sun::star::drawing::XShape xShape );
void remove( [in] com::sun::star::drawing::XShape xShape );
};
</source>
The XIndexAccess inheritance allows also getcount() and getByIndex. This allows the construction of a loop on all shapes.

See also <idl>com.sun.star.beans.XPropertySet</idl> and <idl>com.sun.star.drawing.XShape</idl>.

=Graphics and OOoDraw=
In OOoDraw a graphic is a bitmap or vector picture. We are interesting in this chapter with bitmap graphics.

==Inserting a bitmap==
Here is an example which insert a bitmap. We start as in previous chapter : with a drawing page. The only difference is again with the shape which is now a GraphicObjectShape. And we have to give a file URL and use <idl>com.sun.star.drawing.XShape</idl>, <idl>com.sun.star.drawing.XShapes</idl> and <idl>com.sun.star.beans.XPropertySet</idl> interfaces :
<source lang="cpp">
//Listing 20 Inserting an Image in a Slide
// C++
// Don't forget #include <osl/file.hxx>

// Don't forget to add :using namespace com::sun::star::awt; for Point and size

// Don't forget to add : #include <com/sun/star/drawing/XShape.hpp>
// Don't forget to add "com.sun.star.drawing.XShape \" in the makefile

// Don't forget to add : #include <com/sun/star/drawing/XShapes.hpp>
// Don't forget to add "com.sun.star.drawing.XShapes \" in the makefile

// Don't forget to add : using namespace com::sun::star::beans;
// Don't forget to add : #include <com/sun/star/beans/XPropertySet.hpp>
// Don't forget to add "com.sun.star.beans.XPropertySet \" in the makefile

Reference< XMultiServiceFactory > DocFactory(xcomponent, UNO_QUERY);
Reference< XInterface > GraphicShape = DocFactory->createInstance(
OUString::createFromAscii("com.sun.star.drawing.GraphicObjectShape"));
Reference< XShape > rGrafShape(GraphicShape, UNO_QUERY);

Point *Pos = new (Point);
Size *TheSize = new ( Size );
Pos->X = 2000;
Pos->Y = 6000;
TheSize->Width = 7000;
TheSize->Height = 2000;
rGrafShape->setPosition(*Pos);
rGrafShape->setSize(*TheSize);
OUString sImageUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/photoperso.jpg"),sImageUrl);
Reference< XPropertySet > rShapeProps(rGrafShape, UNO_QUERY);
rShapeProps->setPropertyValue(OUString::createFromAscii("GraphicURL"),
makeAny(sImageUrl));

// Query XShapes Interface
Reference< XShapes > Shapes(rDrawPage, UNO_QUERY);
Shapes->add(rGrafShape);
</source>
This code doesn't insert the picture in the document but the link. Inserting effectively is not possible with the API but with menus :

1. Edition -> link

select all the pictures link

click on deconnect button; confirm

2. Save the document.

Or you copy the bitmap of the linked picture after it was added to the document and create a new shape with it. This new shape contains the actual image and not only the link.

<source lang="cpp">
//Listing 20.2 Inserting an Image and embedding it

// C++
// Don't forget #include <com/sun/star/awt/XBitmap.hpp>

//Only after adding the rGrafShape to the Shapes collection,
//the GraphicObjectFillBitmap is set.

//Get a copy of the image bitmap
Any bmp = rShapeProps->getPropertyValue(
OUString::createFromAscii("GraphicObjectFillBitmap"));
Reference< XBitmap > rBitmap(bmp, UNO_QUERY);

Reference< XInterface > embedShape = DocFactory->createInstance(
OUString::createFromAscii("com.sun.star.drawing.GraphicObjectShape"));
Reference< XShape > rEmbedShape(embedShape , UNO_QUERY);

//Set size and pos again (this time for the embedded shape)
rEmbedShape->setPosition(Position);
rEmbedShape->setSize(TheSize);

Reference< XPropertySet > rEmbedPropSet(rEmbedShape, UNO_QUERY);

//Set the bitmap for the new embedded shape
rEmbedPropSet->setPropertyValue(
OUString::createFromAscii("GraphicObjectFillBitmap"), makeAny(rBitmap));
rEmbedPropSet->setPropertyValue(
OUString::createFromAscii("Name"), makeAny(sImageUrl));

//Finally add the embedded shape to the shapes collection
rShapes->add(rEmbedShape);

//Dont forget to remove the linked shape
rShapes->remove(rGrafShape);
</source>

See also <idl>com.sun.star.drawing.XShape</idl>, <idl>com.sun.star.drawing.XShapes</idl> <idl>com.sun.star.beans.XPropertySet</idl> and <idl>com.sun.star.drawing.GraphicObjectShape</idl>.

==Changing the Size of a Picture==
To keep proportion when changing the size, you have first to calculate it. For that we first get the picture's size in pixels but this is possible only after the “Shapes->add(rGrafShape);” Here is an example which resize the picture with a chosen width and a height calculated.
<source lang="cpp">
//Listing 21 Modifying a Bitmap Size
//C++
// Don't forget to add : #include <com/sun/star/awt/XBitmap.hpp>
// Don't forget to add "com.sun.star.awt.XBitmap \" in the makefile

Any Bitmap = rShapeProps->
getPropertyValue(OUString::createFromAscii("GraphicObjectFillBitmap"));
Reference< XBitmap > rBitmap(Bitmap, UNO_QUERY);
// query the size in pixel
*TheSize = rBitmap->getSize();
sal_Int32 proportion = TheSize->Height/TheSize->Width;
TheSize->Width = 14000;
TheSize->Height = 14000*proportion;
rGrafShape->setSize(*TheSize);
</source>

See also <idl>com.sun.star.awt.XBitmap</idl>.

==Inserting many Pictures==
Every time you insert a picture, you have to query many times the <idl>com.sun.star.drawing.GraphicObjectShape</idl> service, even if you insert many times the same picture.

==Finding a Picture with its Name==
The picture like other shapes can be accessed with an index, not very easy to use. But we can give them a name see ([[ Programming_OOoDraw_and_OOoImpress#Giving_a_Name_to_the_Shape| Giving a Name to the Shape]]) We shall tackle this problem later.

If you want to go further with shapes go to next [[Working_with_Shapes | chapter]].

{{Template:Home_Page}}

= See also=
* Drawing Documents and Presentation Documents [[Documentation/DevGuide/Drawings/Drawing_Documents_and_Presentation_Documents|in Developer's Guide]]
* [[Documentation/BASIC_Guide/Drawings_Presentations|Drawings ans Presentations]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:OOoDraw]]
[[Category:Development]]
[[Category:Uno]]
[[Category:Cpp]]

Framework/Article/General Architecture Of The Framework User Interface Implementation

2009-02-19T07:36:29Z

Dtardon: Fixed tagging of code listings

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 following illustration shows the connections between the most important Framework objects. The blue objects are part of the Framework User Interface API implementation and gray objects are part of the general Framework API implementation.

[[Image:Architecture.png]]

== 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.

<source lang="idl">
//=============================================================================

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

//=============================================================================
/** controls the layout of user interface elements which are part of a 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
*/

service LayoutManager
{
/** 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;
};

}; }; }; };
</source>

Example to retrieve the layout manager instance from a frame.
<source lang="cpp">
::com::sun::star::uno::Reference< ::com::sun::star::frame::XLayoutManager > xLayoutManager;
::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet > xPropSet;

xPropSet = ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >( xFrame, ::com::sun::star::uno::UNO_QUERY );

if ( xPropSet.is() )
{
try
{
xLayoutManager.set( xPropSet->getPropertyValue(
::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM( "LayoutManager" ))),
::com::sun::star::uno::UNO_QUERY );
}
catch ( com::sun::star::beans::UnknownPropertyException& )
{
}
}
</source>
=== Address a single User Interface Element ===

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

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

* 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.
<code>private:resource/menubar/menubar</code>

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 ===

Modern GUI systems support toolbars which are rows, columns, or blocks of onscreen buttons or icons that, when clicked, activate certain functions of the program. Toolbars can be docked to the four sides of the main application window or float on the desktop. OpenOffice.org supports an unlimited number of toolbars. 
Toolbars are addressed by the following generic schema:

<code>private:resource/toolbar/<name of toolbar></code>

Custom toolbars which can be created by the user using "Tools - Customize - Toolbars" use the following schema:

<code>private:resource/toolbar/custom_<name of custom toolbar></code>

Add-on toolbars which can be defined by extensions and use the following schema:

<code>private:resource/toolbar/addon_<name of add-on toolbar></code>

The LayoutManager automatically determines the type of toolbar and according to the type controls the toolbars. Custom and add-on toolbars are never context dependent, while normal toolbars can be context or non-context sensitive.

=== Menubar ===

A menu bar is a region on GUI where application specific functions reside. Its purpose is to provide access to different application-specific menus, such as opening files, window manipulation or help.

The menu bar will be accessed by using the following schema:

<code>private:resource/menubar/menubar</code>

=== Statusbar ===

A status bar in GUI systems is a component (widget) that is often found at the bottom of windows. It's normally divided into sections, each of which shows different information. Its job is primarily to display information about the current state of its window.

A status bar is addressed by using the following schema:

<code>private:resource/statusbar/statusbar</code>

== The User Interface Configuration API ==

=== Overview ===

OpenOffice.org support a user interface configuration API to adapt the user interface elements to the needs of users and developers. User interface configuration data can be global, module or document based. The global user interface configuration layer is only available for accelerators. The following user interface elements can be accessed via the user interface configuration API:

* Tool bars
* Menu bar
* Status bar
* Accelerators
* Command images

=== The Module User Interface Configuration Manager ===

A module user interface configuration manager can be retrieved from the <code>com::sun::star::ui::ModuleUIConfigurationManagerSupplier</code> service which can be created with the OpenOffice.org service manager using its service specifier. One has to provide the module identifier retrieved from the <code>com::sun::star::frame::ModuleManager</code> service to specify which ModuleUIConfigurationManager should be accessed. The following code snippet shows how one can use the ModuleManager to identify the module bound to a frame. The module identifier can then be used to retrieve the ModuleUIConfigurationManager.

<code>[cpp]
...

try
{
::rtl::OUString aModuleIdentifier;

::com::sun::star::uno::Reference< ::com::sun::star::frame::XModuleManager >(
xServiceManager->createInstance( ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.frame.ModuleManager" ))), ::com::sun::star::uno::UNO_QUERY_THROW );

aModuleIdentifier = xModuleManager->identify(
::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >( xFrame, ::com::sun::star::uno::UNO_QUERY ) );
if ( aModuleIdentifier.getLength() )
{
::com::sun::star::uno::Reference< ::com::sun::star::frame::XModuleUIConfigurationManagerSupplier > xModuleCfgSupplier;
xModuleCfgSupplier = Reference< XModuleUIConfigurationManagerSupplier >(
xServiceManager->createInstance( ::rtl::OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.ui.ModuleUIConfigurationManagerSupplier" ))), ::com::sun::star::uno::UNO_QUERY_THROW );
xModuleCfgMgr = ::com::sun::star::uno::Reference< ::com::sun::star::ui::XUIConfiguration >(
xModuleCfgSupplier->getUIConfigurationManager( aModuleIdentifier ), ::com::sun::star::uno::UNO_QUERY );
}
}
catch( ::com::sun::star::uno::Exception& )
{
}

...
</code>

=== 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 [http://xml.openoffice.org/general.html 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: <code><Office installation>/share/registry/org/openoffice/Office/UI</code>. The schema definition of these configuration files can be found below:

<code>[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>
</code>

A LabelType consists of three 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.
* ContextLabel
This is a special label which is used for sub-menu entries located on level two or greater depth. There are some popup menus which have a label which describe an action, e.g. "Insert". All sub-menu entries of this popup menu should not contain "Insert" again (e.g. "Insert Picture").
* 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”.
<code>[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>
</code>

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

==== Adding a new Toolbar ====

There are some additional steps necessary if you want to add a new toolbar to the Office. Two different situations are possible 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: <code>sfx2/source/appl/workwin.cxx</code>. It starts with the following lines:

<code>[cpp]
static const ResIdToResName pToolBarResToName[] =
{
{ 558, "fullscreenbar" },
{ 560, "standardbar", },
{ 18003, "formsnavigationbar" },
...
{ 25000, “newtoolbar” }
};
</code>

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”:

<code>[xml]
<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>
</code>

===== 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 your 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 (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”:
<code>[xml]
<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>
</code>

=== How to add, replace or remove a User Interface Command ===

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 '''NOT''' case-sensitive 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 user interface element. 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 has associated 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

'''ATTENTION: The command name must be in a lower case ascii characters!'''

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

Documentation/DevGuide/UCB/Preconfigured UCBs

2009-02-12T13:19:59Z

Dtardon:

{{Documentation/DevGuide/UCBTOC
|UCB2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/UCB/Unconfigured UCBs
|NextPage=Documentation/DevGuide/UCB/Content Provider Proxies
}}
{{DISPLAYTITLE:Preconfigured UCBs}}
A UCB is called ''preconfigured'' if it was given a UCB configuration at the time it was instantiated. A UCB configuration contains a set of UCP registration information.

To create a preconfigured UCB:

# Create an instance of the UNO service <idl>com.sun.star.ucb.UniversalContentBroker</idl>.
# Pass the configuration as a parameters to the creation function. The UCB instance returned offers all UCPs defined in the given configuration.

Preconfigured UCB:
<source lang="java">
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.uno.Exception;
import com.sun.star.uno.XInterface;

boolean initUCB() {
/////////////////////////////////////////////////////////////////////
// Obtain Process Service Manager.
/////////////////////////////////////////////////////////////////////

XMultiServiceFactory xServiceFactory = ...

/////////////////////////////////////////////////////////////////////
// Create UCB. This needs to be done only once per process.
/////////////////////////////////////////////////////////////////////

XInterface xUCB;
try {
// Supply configuration to use for this UCB instance...
String[] keys = new String[2];
keys[0] = "Local";
keys[1] = "Office";

xUCB = xServiceFactory.createInstanceWithArguments(
"com.sun.star.ucb.UniversalContentBroker", keys);
}
catch (com.sun.star.uno.Exception e) {
}

if (xUCB == null)
return false;

return true;
}
</source>
A UCB configuration used by a preconfigured UCB describes a set of UCPs available in a configuration. All UCPs contained in a configuration are registered at the UCB that is created using this configuration. A UCB configuration is identified by two keys that are strings. The keys allow some structuring in the configuration files, but they do not have a purpose. See the example file below. The standard configuration is "Local" and "Office", that allows access to all UCPs. The XML sample below shows how these keys are used to organize UCB configurations.

The predefined configurations for {{PRODUCTNAME}} are defined in the file ''<OfficePath>/share/config/data/org/openoffice/ucb/Configuration.xcd''. This file must be adapted to add configurations or edit existing configurations. The XCD file is used during the {{PRODUCTNAME}} build process to generate the appropriate XML file. This XML file is part of a {{PRODUCTNAME}} installation and is located in ''<OfficePath>share/config/registry/instance/org/openoffice/ucb/Configuration.xml''. The UCB tries to get configuration data from this XML file.

UCB Configuration (''org/openoffice/ucb/Configuration.xcd''):
<source lang="xml">
<!DOCTYPE schema:package SYSTEM "../schema/schema.description.dtd">
<schema:package package-id="org.openoffice.ucb.Configuration" xml:lang="en-US"
xmlns:schema="http://openoffice.org/2000/registry/schema/description"
xmlns:default="http://openoffice.org/2000/registry/schema/default"
xmlns:cfg="http://openoffice.org/2000/registry/instance">

<schema:templates template-id="org.openoffice.ucb.Configuration">


<schema:group cfg:name="ContentProviderData">
<schema:value cfg:name="ServiceName" cfg:type="string">
</schema:value>
<schema:value cfg:name="URLTemplate" cfg:type="string">
</schema:value>
<schema:value cfg:name="Arguments" cfg:type="string">
</schema:value>
</schema:group>


<schema:group cfg:name="ContentProvidersDataSecondaryKeys">
<schema:set cfg:name="ProviderData"
cfg:element-type="ContentProviderData"/>
</schema:group>


<schema:group cfg:name="ContentProvidersDataPrimaryKeys">
<schema:set cfg:name="SecondaryKeys"
cfg:element-type="ContentProvidersDataSecondaryKeys"/>
</schema:group>
</schema:templates>

<schema:component cfg:writable="true"
component-id="org.openoffice.ucb.Configuration"
cfg:notified="true" cfg:localized="false">
<schema:set cfg:name="ContentProviders"
cfg:element-type="ContentProvidersDataPrimaryKeys">
<default:group cfg:name="Local">
<default:set cfg:name="SecondaryKeys"
cfg:element-type="ContentProvidersDataSecondaryKeys">
<default:group cfg:name="Office">
<default:set cfg:name="ProviderData"
cfg:element-type="ContentProviderData">


<default:group cfg:name="Provider1">
<default:value cfg:name="ServiceName" cfg:type="string">
<default:data>com.sun.star.ucb.HierarchyContentProvider</default:data>
</default:value>
<default:value cfg:name="URLTemplate" cfg:type="string">
<default:data>vnd.sun.star.hier</default:data>
</default:value>
<default:value cfg:name="Arguments" cfg:type="string">
<default:data/>
</default:value>
</default:group>


<default:group cfg:name="Provider2">
<default:value cfg:name="ServiceName" cfg:type="string">
<default:data>com.sun.star.ucb.FileContentProvider</default:data>
</default:value>
<default:value cfg:name="URLTemplate" cfg:type="string">
<default:data>file</default:data>
</default:value>
<default:value cfg:name="Arguments" cfg:type="string">
<default:data/>
</default:value>
</default:group>



</default:set>
</default:group>
</default:set>
</default:group>
</schema:set>
</schema:component>
</schema:package>
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Universal Content Broker]]

Documentation/DevGuide/UCB/Preconfigured UCBs

2009-02-12T13:16:35Z

Dtardon: Fixed array index

{{Documentation/DevGuide/UCBTOC
|UCB2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/UCB/Unconfigured UCBs
|NextPage=Documentation/DevGuide/UCB/Content Provider Proxies
}}
{{DISPLAYTITLE:Preconfigured UCBs}}
A UCB is called ''preconfigured'' if it was given a UCB configuration at the time it was instantiated. A UCB configuration contains a set of UCP registration information.

To create a preconfigured UCB:

# Create an instance of the UNO service <idl>com.sun.star.ucb.UniversalContentBroker</idl>.
# Pass the configuration as a parameters to the creation function. The UCB instance returned offers all UCPs defined in the given configuration.

Preconfigured UCB:
<source lang="java">
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.uno.Exception;
import com.sun.star.uno.XInterface;

boolean initUCB() {
/////////////////////////////////////////////////////////////////////
// Obtain Process Service Manager.
/////////////////////////////////////////////////////////////////////

XMultiServiceFactory xServiceFactory = ...

/////////////////////////////////////////////////////////////////////
// Create UCB. This needs to be done only once per process.
/////////////////////////////////////////////////////////////////////

XInterface xUCB;
try {
// Supply configuration to use for this UCB instance...
String[] keys = new String[2];
keys[0] = "Local";
keys[1] = "Office";

xUCB = xServiceFactory.createInstanceWithArguments(
"com.sun.star.ucb.UniversalContentBroker", keys);
}
catch (com.sun.star.uno.Exception e) {
}

if (xUCB == null)
return false;

return true;
}
</source>
A UCB configuration used by a preconfigured UCB describes a set of UCPs available in a configuration. All UCPs contained in a configuration are registered at the UCB that is created using this configuration. A UCB configuration is identified by two keys that are strings. The keys allow some structuring in the configuration files ), but they do not have a purpose. See the example file below. The standard configuration is "Local" and "Office", that allows access to all UCPs. The XML sample below shows how these keys are used to organize UCB configurations.

The predefined configurations for {{PRODUCTNAME}} are defined in the file ''<OfficePath>/share/config/data/org/openoffice/ucb/Configuration.xcd''. This file must be adapted to add configurations or edit existing configurations. The XCD file is used during the {{PRODUCTNAME}} build process to generate the appropriate XML file. This XML file is part of a {{PRODUCTNAME}} installation and is located in ''<OfficePath>share/config/registry/instance/org/openoffice/ucb/Configuration.xml''. The UCB tries to get configuration data from this XML file.

UCB Configuration (''org/openoffice/ucb/Configuration.xcd''):
<source lang="xml">
<!DOCTYPE schema:package SYSTEM "../schema/schema.description.dtd">
<schema:package package-id="org.openoffice.ucb.Configuration" xml:lang="en-US"
xmlns:schema="http://openoffice.org/2000/registry/schema/description"
xmlns:default="http://openoffice.org/2000/registry/schema/default"
xmlns:cfg="http://openoffice.org/2000/registry/instance">

<schema:templates template-id="org.openoffice.ucb.Configuration">


<schema:group cfg:name="ContentProviderData">
<schema:value cfg:name="ServiceName" cfg:type="string">
</schema:value>
<schema:value cfg:name="URLTemplate" cfg:type="string">
</schema:value>
<schema:value cfg:name="Arguments" cfg:type="string">
</schema:value>
</schema:group>


<schema:group cfg:name="ContentProvidersDataSecondaryKeys">
<schema:set cfg:name="ProviderData"
cfg:element-type="ContentProviderData"/>
</schema:group>


<schema:group cfg:name="ContentProvidersDataPrimaryKeys">
<schema:set cfg:name="SecondaryKeys"
cfg:element-type="ContentProvidersDataSecondaryKeys"/>
</schema:group>
</schema:templates>

<schema:component cfg:writable="true"
component-id="org.openoffice.ucb.Configuration"
cfg:notified="true" cfg:localized="false">
<schema:set cfg:name="ContentProviders"
cfg:element-type="ContentProvidersDataPrimaryKeys">
<default:group cfg:name="Local">
<default:set cfg:name="SecondaryKeys"
cfg:element-type="ContentProvidersDataSecondaryKeys">
<default:group cfg:name="Office">
<default:set cfg:name="ProviderData"
cfg:element-type="ContentProviderData">


<default:group cfg:name="Provider1">
<default:value cfg:name="ServiceName" cfg:type="string">
<default:data>com.sun.star.ucb.HierarchyContentProvider</default:data>
</default:value>
<default:value cfg:name="URLTemplate" cfg:type="string">
<default:data>vnd.sun.star.hier</default:data>
</default:value>
<default:value cfg:name="Arguments" cfg:type="string">
<default:data/>
</default:value>
</default:group>


<default:group cfg:name="Provider2">
<default:value cfg:name="ServiceName" cfg:type="string">
<default:data>com.sun.star.ucb.FileContentProvider</default:data>
</default:value>
<default:value cfg:name="URLTemplate" cfg:type="string">
<default:data>file</default:data>
</default:value>
<default:value cfg:name="Arguments" cfg:type="string">
<default:data/>
</default:value>
</default:group>



</default:set>
</default:group>
</default:set>
</default:group>
</schema:set>
</schema:component>
</schema:package>
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Universal Content Broker]]

Documentation/DevGuide/UCB/Accessing a UCB Content

2009-02-12T07:57:08Z

Dtardon: Fixed mistyped method name

{{Documentation/DevGuide/UCBTOC
|UCB2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/UCB/Instantiating the UCB
|NextPage=Documentation/DevGuide/UCB/Executing Content Commands
}}
{{DISPLAYTITLE:Accessing a UCB Content}}

Each UCB content can be identified using a URL that points to a folder or a document content in the data source you want to work with. To create a content object for a given URL:

# Obtain access to the UCB.
# Let the UCB create a content identifier object for the requested URL using <code>createContentIdentifier()</code> at the <idl>com.sun.star.ucb.XContentIdentifierFactory</idl> of the UCB.
# Let the UCB create a content object for the content identifier using <code>queryContent()</code> at the <idl>com.sun.star.ucb.XContentProvider</idl> interface of the UCB.

The UCB selects a UCP according to the URL contained in the identifier object and dispatches the <code>queryContent()</code> call to it. The UCP creates the content implementation object and returns it to the UCB, which passes it on to the caller.

Creating a UCB content from a given URL:

<source lang="java">
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.Xinterface;
import com.sun.star.ucb.*;

{
String aURL = ...

/////////////////////////////////////////////////////////////////////
// Obtain access to UCB...
/////////////////////////////////////////////////////////////////////

XInterface xUCB = ...

// Obtain required UCB interfaces XContentIdentifierFactory and XContentProvider
XContentIdentifierFactory xIdFactory = (XContentIdentifierFactory)UnoRuntime.queryInterface(
XContentIdentifierFactory.class, xUCB);
XContentProvider xProvider = (XContentProvider)UnoRuntime.queryInterface(
XContentProvider.class, xUCB);

/////////////////////////////////////////////////////////////////////
// Obtain content object from UCB...
/////////////////////////////////////////////////////////////////////

// Create identifier object for given URL.
XContentIdentifier xId = xIdFactory.createContentIdentifier(aURL);

XContent xContent = xProvider.queryContent(xId);
}
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Universal Content Broker]]

Documentation/DevGuide/UCB/Instantiating the UCB

2009-02-12T07:45:01Z

Dtardon: Fixed array index

{{Documentation/DevGuide/UCBTOC
|UCB2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/UCB/Using the UCB API
|NextPage=Documentation/DevGuide/UCB/Accessing a UCB Content
}}
{{DISPLAYTITLE:Instantiating the UCB}}

The following steps have to be performed before a process can use the UCB:

* Create and set the UNO service manager.
* Create an instance of the UNO service <idl>com.sun.star.ucb.UniversalContentBroker</idl>, passing the keys identifying a predefined UCB configuration to <code>createInstanceWithArguments()</code>.

There are several predefined UCB configurations. Each configuration contains data that describes a set of UCPs. All UCPs contained in a configuration are registered at the UCB that is created using this configuration. A UCB configuration is identified by two keys that are strings. The standard configuration is "<code>Local</code>" and "<code>Office</code>", which generally allows access to all UCPs available in a local installation.
<source lang="java">
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.uno.Exception;
import com.sun.star.uno.XInterface;

boolean initUCB() {

/////////////////////////////////////////////////////////////////////
// Obtain Process Service Manager.
/////////////////////////////////////////////////////////////////////

XMultiServiceFactory xServiceFactory = ...

/////////////////////////////////////////////////////////////////////
// Create UCB. This needs to be done only once per process.
/////////////////////////////////////////////////////////////////////

XInterface xUCB;
try {
// Supply configuration to use for this UCB instance...
String[] keys = new String[2];
keys[ 0 ] = "Local";
keys[ 1 ] = "Office";

xUCB = xServiceFactory.createInstanceWithArguments(
"com.sun.star.ucb.UniversalContentBroker", keys );
}
catch (com.sun.star.uno.Exception e) {
}

if (xUCB == null)
return false;

return true;
}
</source>
For information about other configurations, refer to [[Documentation/DevGuide/UCB/Configuration|Configuration]].

{{PDL1}}

[[Category:Documentation/Developer's Guide/Universal Content Broker]]

DomainDeveloper

2008-07-14T13:59:40Z

Dtardon: /* Developers */

A mapping of names to OOo accounts.

Abbrev.:

* PL : Project Lead
* CL : Project Co-Lead
* CC : Community Council Member
* ESC : Engineering Steering Committee Member
* CVS : has write access to the OOo CVS repository

----

=== Developers ===

{| class="prettytable sortable"
|-
! Name || CVS || @openoffice.org || [[IRC Communication]] || Notes || Affiliation
|-
| Volker Ahrendt|| X || va||||||Sun Microsystems
|-
| Kai Ahrens|| X || ka || Kai_Ahrens ||PL Graphic Applications||Sun Microsystems
|-
| Gene Anaya|| || ganaya||||||
|-
| Joost Andrae|| X || ja||ja||CL qa, release testing en-US builds and releasing builds||Sun Microsystems
|-
| Eric Bachard|| X || ericb||ericb2|| CL Education, Mac OSX/Linux PPC port ||Education project
|-
| Kai Backman|| || kaib ||KaiB||||
|-
| Sascha Ballach|| X || sab||||||
|-
| Jayant Balraj Madavi|| || jayant_madavi||aZEN_JM||Connectivity / Database||Novell, Inc.
|-
| Jörg Barfurth|| X || jb||JoergB||Configuration Util||Sun Microsystems
|-
| Omer Bar-or|| X || cremlae||cremlae||Mac porting||Google Summer of Code
|-
| Mathias Bauer|| X || mba||||PL Writer, CL Framework, XML||Sun Microsystems
|-
| Thorsten Behrens|| X || thb||thorsten||vcl/impress/toolkit visionary||Sun Microsystems
|-
| Thomas Benisch|| X || tbe||||Scripting framework||Sun Microsystems
|-
| Stephan Bergmann|| X || sb||||CL UDK||Sun Microsystems
|-
| Andreas Bille|| X || abi||||||Sun Microsystems
|-
| Éric Bischoff|| X || ebischoff||ebischoff||KDE A/B driver||Bureau Cornavin
|-
| Nick Blievers|| X || nick||||IRIX||
|-
| Daniel Boelzle|| X || dbo||||UNO core/bridges/packages||Sun Microsystems
|-
| Oliver Bolte|| X || obo||||RE||Sun Microsystems
|-
| Rafaella Braconi|| || coni||Rafaella ||PL l10n, Globalization Program Manager||Sun Microsystems
|-
| Michael Brauer|| X || mib||||PL XML||Sun Microsystems
|-
| Oliver Braun|| X || obr||obr||System Integration/Accessibility Hacker||Sun Microsystems
|-
| Andreas Bregas|| X || ab||||StarBasic||Sun Microsystems
|-
| Jörg Brunsmann|| || jbrunsmann||||UDK||
|-
| Jörg Budischewski|| || jbu||PyUNO hacker||||Sun Microsystems
|-
| Peter Burow|| X || pb||plumbumm||UI||Sun Microsystems
|-
| Aidan Butler|| || aidan||||XML filters||
|-
| Giuseppe Castagno || X || beppec56 || beppec56_ or beppe_c || PDF output
|-
| [[User:ScottCarr|Scott Carr]] || X || kcarr||kcarr||PL Documentation||Progbits
|-
| Colin Charles|| || drbyte||bytee||Malaysian native-lang project||bytebot.net
|-
| Jinhong Chen || || chainchen || || || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Xiuzhi Cheng|| X || xzcheng || xiuzhi|| ESC,Xml,ODF|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Behrend Cornelius|| X || bc||||Wizards||Sun Microsystems
|-
| Michael Cziebalski|| || mci||||||
|-
| [[User:pdefilippis|Pierre de Filippis]]|| X || pdefilippis||aliscafo||Mac OSX native porting||
|-
| Andrew Dent|| X ||ace_dent||ace_dent||ui/custom_images||
|-
| Naren Devaiah|| || ||ndev||Performance||Intel Corporation
|-
| Quangang Dong|| || donqg || dongqg || Layout || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Nitin Dongre|| || ||nitin_BITS||||Novell, Inc.(intern)
|-
| Radek Doulik|| || radekdoulik||rodo_||Canvas hacker||Novell, Inc.
|-
| Carsten Driesner|| X || cd|| cd_oo ||PL Framework||Sun Microsystems
|-
| Yunfen Du || X || duyunfen|| dyf|| Base ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-

| Herbert Duerr|| X || hdu||hdu_hh||GSL||Sun Microsystems
|-
| Oliver Düsterhoff|| X || od||Writer||||Sun Microsystems
|-
| Bernd Eilers|| X || bei||rfc821||EIS||Sun Microsystems
|-
| René Engelhard|| X || rene||_rene_||config_office, Debian packager||Debian
|-
| [[User:Pereriksson|Per Eriksson]] || || pereriksson || || CL, MarCon Sweden ||
|-
| Yaqiong Fang || X || fangyq || fangyq|| Graphics|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Hubert Figuière|| X || hub || hub || PPTX || Novell, Inc.
|-
| Andre Fischer|| X || af||||Impress||Sun Microsystems
|-
| Uwe Fischer || X || ufi || ufiooo || Application Help || Sun Microsystems
|-
| Ken Foskey|| || waratah||waratah||config_office/dmake man||slug.org.au
|-
| Duncan Foster|| || dfoster||||||
|-
| David Fraser|| || davidfraser||davidfraser||South African translations, multilingual builds||translate.org.za
|-
| [[User:Nf|Nils Fuhrmann]]|| || nf||SunNF||||Sun Microsystems
|-
| Martin Gallwey|| X || mtg||marty_||XML/Writer/packaging||
|-
| Pierre-Andre Galmes || || pagalmes || pagalmes || Chart2 ||StarXpert
|-
| Tony Galmiche|| X || tonygalmiche||||CL FR native-lang project||
|-
| Sunil Gandhi|| || ||tyro||||NOSIP
|-
| Peng Gao || || Gao Peng|| Gao Peng || writer|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Zemin Gao || || gaozemin|| gaozm || Calc || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Sophie Gautier|| X || sgauti|| sophi ||PL FR native-lang project, CC ||.
|-
| Vladimir Glazounov|| X || vg||||RE||Sun Microsystems
|-
| Laurent Godard || X || laurentgodard || lgodard || CC, PL Extensions, Fr Native-lang Project || inDesko/Nuxeo
|-
| Jody Goldberg|| X || jodygoldberg||jody||[[Calc]] spreadsheet-ness||Novell, Inc.
|-
| Dirk Grobler|| X || dg||||Database Access||Sun Microsystems
|-
| [[User:Sg|Steffen Grund]]|| X || sg|| || NetBeans Integration ||Sun Microsystems
|-
| Bettina Haberer|| || bh||||RFEOwner||Sun Microsystems
|-
| Ingrid Halama|| X || iha||||Chart||Sun Microsystems
|-
| Chris Halls|| X || haggai||haggai||Debian packager&misc. hacker||Credativ Ltd., Debian
|-
| Gregor Hartmann|| X || gh|| Lachs ||Testtool, gsicheck, buildbot||Sun Microsystems
|-
| Bustamam Harun|| || bustamam||||Malaysian stuff||
|-
| Kevin Hendricks|| X || khendricks||||PL Lingucomponent, PowerPC||
|-
| Con Hennessy|| || cphennessy||cph2 or cph_||hacker & former council person||OpenApp
|-
| Ivo Hinkelmann|| X || ihi||ivo||l10n tooling/general/RE||Sun Microsystems
|-
| Eric Hoch|| X || maveric||mav_eric||Mac Porting||
|-
| [[User:Lutz_Hoeger|Lutz Hoeger]]|| X || lh ||lutzh||PL [http://ux.openoffice.org User Experience]||Sun Microsystems
|-
| Jan Holešovský|| X || kendy||kendy||KDE integration||Novell, Inc.
|-
| Martin Hollmichel|| X || mh||Ratte/Nesshof||Build Maestro, PL External, Tools, Porting, CC||Sun Microsystems
|-
| Karl Hong|| X || khong||||i18n, CJK expert||Sun Microsystems
|-
| Matthias Huetsch|| X || mhu||||Performance/strategy, PL UCB, CC, ESC||Sun Microsystems
|-
| Michael Hönnig|| X || mi||||PL API||
|-
| [[User:icobgr|Hristo Hristov]] || || icobgr || icobgr || PL Bulgarian native-lang project ||
|-
| Sven Jacobi|| X || sj||||Escherwizard||Sun Microsystems
|-
| Jörg Jahnke|| || jj||||tooling||Sun Microsystems
|-
| Christian Jansen|| || cj ||||Menu and Toolbar?||Sun Microsystems
|-
| Ocke Janssen|| X || oj||Base||||Sun Microsystems
|-
| Pavel Janík|| X || pjanik||paveljanik||PL Czech native-lang project, CL l10n, CC, ESC, l10n builds||
|-
| Berry Jia|| X || berryjia||||||Sun Microsystems
|-
| Chuang Jiang || || jiangc || || || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Jingchuan Kang|| || kangjingchuan || jingchuan || Surrogates in Unicode || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Pascal Junck|| || pjunck||||||Sun Microsystems
|-
| [[User:pj@openoffice.org|Peter Junge]]|| X || pj|| peter13j|| OOo community contact for my Chinese Employer, QA||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Christian Junker|| || Cyb||christianju||API||Trees For Life
|-
| Etsushi Kato || X || ekato || || Mac OS X Port || Independent
|-
| Hirano Kazunari|| || khirano||||Japanese||
|-
| Dhananjay Keskar|| X || dkeskar ||dkeskar||Performance,Buildbot,cat-herder||Intel Corporation
|-
| Robert Kinsella|| || rkinsella||||||Sun Microsystems
|-
| Volodymyr Khrystynych|| || volody||||XML Filter||
|-
| Matthias Klose|| || doko||doko||Ubuntu, gcc, python packager||Canonical, Inc.
|-
| Laszlo Kovacs|| || lkovacs||||Documentation||
|-
| Tobias Krause|| X || tkr||||ucb||Sun Microsystems
|-
| Martin Kretzschmar|| X || mkretzschmar||martink||Gnome / Debian||Student
|-
| Will Lachance|| || wlach||wlach_||Word Perfect File Filters||Net Integration Technologies, Inc.
|-
| Thomas Lange|| X || tl||tl13||||Sun Microsystems
|-
| Lars Langhans|| X || lla||||||Sun Microsystems
|-
| Hans-Joachim Lankenau|| X || hjs||ause||dmake makefile expert, RE||Sun Microsystems
|-
| Németh László|| X || nemeth||||PL lingucomponent||
|-
| Jakob Lechner|| X || jakob_lechner||||Writer||Fabalabs
|-
| Michael Leibowitz|| X || mikeleib ||mikeleib||performance||Intel Corporation
|-
| Wind Li|| X || windly||||Address books||
|-
|Jian Li || || lijian || lijian|| Writer|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Yuan Li || || liyuan || || PyUNO, Async dialogs || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Weike Liang || || liangweike || liangweike || Graphics || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Ping Liao|| || pliao||||||
|-
| Tor Lillqvist|| X || tml||tml_||||Novell, Inc.
|-
| Joachim Lingner|| X || jl||||Java, CLI||Sun Microsystems
|-
| Christian Lippka|| X || cl || cl ||Graphic Applications||Sun Microsystems
|-
| Mindy Liu|| || mindyliu||||||
|-
|Jianli Liu || || liujl|| liujianli || Graphics|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|[[User:liutao | LiuTao]] || X || liutao || liutao || PyUNO, Async dialogs,slideshow,modularization in SW || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|YU Liu || X || ch2000liuy || LiuYU || Swriter || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Yuhua Liu || || liuyuhua|| yuhua|| ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| [[User:Dl|Dieter Loeschky]]|| X || dl ||||PL: ODF Toolkit||Sun Microsystems
|-
| Philipp Lohmann|| X || pl||PhilippL||VCL/X11 (GSL) hacker||Sun Microsystems
|-
| Michel Loiseleur|| || mloiseleur|| coren`|| Bugfixes ||Linagora
|-
| Jackson Low|| X || xxjack12xx||||Porting||
|-
| Patrick Luby|| || pluby||||Mac||
|-
|Jingrong Luo || || Luo Jingrong|| Luo Jingrong|| ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Xugang Lv || || lvxg || lvxg || XML Writer || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Prasad Madhav || X || pmadhav || pmadhav || Buildbot || Intern@Intel
|-
| Babak Mahbod|| || bmahbod||||||
|-
| Martin Maher|| || mmaher||||Writer & Filter chap||
|-
| Nakata Maho|| X || maho||_maho_||PL QA, PL JA, FreeBSD guy||Independent
|-
|Yonggang Mao || X || maoyonggang|| maoyg|| Calc ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Yue Lv || || lvyue || lvyue || Calc ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| John Marmion|| X || jmarmion||||||
|-
| Andreas Martens|| X || ama||||PL Writer||Sun Microsystems
|-
|-|
| Shane M Mathews|| X || smmathews|| smmathews ||[[Impress:_OpenGL_rendered_transitions]]||student
|-
| Frank Mau|| X || fma||||tooling||Sun Microsystems
|-
| [[User:smsm1|Shaun McDonald]] || X || smsm1 || shaunmcdonald || Mac Port, buildbot MacPort1 || Graduate
|-
| Caolán McNamara|| X || cmc||caolan||CL Writer & Filter man||RedHat, Inc.
|-
| Michael Meeks|| X || mmeeks||michael_||ugly hack-er, ESC||Novell, Inc.
|-
| Frank Meies|| X || fme||||Writer||Sun Microsystems
|-
| Federico Mena-Quintero|| || federicomena||federico||perfectionist||Novell, Inc.
|-
| Ismael Merzaq|| X || isma87||ismael_||Mac OSX native porting||Student
|-
| Michael Mi|| || mmi||||||
|-
| Björn Michaelsen|| X || b_michaelsen ||Sweetshark|| ||Sun Microsystems
|-
| Björn Milcke|| X || bm||bm_||Chart||Sun Microsystems
|-
| Petr Mladek|| || pmladek||pmladek||SUSE RPMs, ooo-build releases||Novell, Inc.
|-
| Cyrille Moureaux|| X || cyrillem||Cyrille||||Sun Microsystems
|-
| [[User:Mmp|Matthias Müller-Prove]]|| X || mmp|| mprove|| [[User Experience]], http://ux.openoffice.org || Sun Microsystems
|-
| Takashi Nakamoto|| || bluedwarf|| || ||
|-
| Jan Navrátil || X || jnavrati || jnavrati || || RedHat, Inc.
|-
| Niklas Nebel|| X || nn||||PL [[Calc]]||Sun Microsystems
|-
| Christoph Neumann|| X || cn||||[[UnoApiTest]]||Sun Microsystems
|-
| Frank Neumann|| X || fne||||MacPort||Sun Microsystems
|-
| NicelKM|| X || mnicel||nicel||||Novell, Inc.
|-
| Jan Nieuwenhuizen|| X || jcn||janneke||Layout code, hacker ||Novell, Inc.
|-
| Bertram Nolte|| || bnolte||||||
|-
| Tomas O'Connor|| || toconnor||||Scripting Framework||
|-
| Maximilian Odendahl|| X || mod||mod||[[Notes2]]|| Student / SEPT-Solutions
|-
| Lars Oppermann|| X || lo||||||Sun Microsystems
|-
| Rodrigo Parra Novo|| X || rodarvus||rodarvus||Gnumeric/Abiword OpenDocument Format support and port to Maemo||INdT (Instituto Nokia de Tecnologia)
|-
| Edward Peterlin|| X || OPENSTEP||||Mac||
|-
| [[User:Fpe|Frank Peters]]|| X || fpe||||CL Documentation||Sun Microsystems
|-
| Christof Pintaske|| X || cp||||||Sun Microsystems
|-
| Ron Piterman|| || rpiterman||||||
|-
| Sebastien Plisson|| X || plipli||plipli||Developer on Aqua port||OO Aqua Port
|-
| Noel Power|| || npower||noelp||VBA Interop, Scripting||Novell, Inc.
|-
| Nikolai Pretzell|| X || np || ||Autodoc, code quality||Sun Microsystems
|-
| Jonathan Pryor|| || jpryor || jonp || || Novell, Inc.
|-
| Canghua Qu|| || quch || Canghua || AutoTest, Graphics || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Volker Quetschke|| X || vq||vq||W32-tcsh/bash build environment and dmake Hacker, ESC||Gravity Waves
|-
| Tino Rachui|| X || tra||tinor||GSL/Unix Hacker||Sun Microsystems
|-
| [[User:Kr|Kay Ramme]]|| X || kr||||PL UDK||Sun Microsystems
|-
| [[User:ErAck|Eike Rathke]]|| X || er||erAck||CL [[Calc]], engine; CL i18n; stricken with number formatter||Sun Microsystems
|-
| Michael Rauch|| X || mrauch||||NetBSD||
|-
| Jens-Heiner Rechtien|| X || hr||blauwal||RE; OOo SCM (CVS, CWS tooling); Porting; Compilers||Sun Microsystems
|-
| Daniel Rentz|| X || dr|| drr ||[[Calc]] Excel filter, UI||Sun Microsystems
|-
| Florian Reuter|| X || flr||||Writer filters||Novell, Inc.
|-
| Georg Richter|| X || grichter||georg||Base, native MySQL driver||MySQL AB
|-
| G. Roderick Singleton|| || grsingleton||grsingleton||Documentation||pathtech.org
|-
| Hennes Rohling|| X || hro||||GSL & Util||Sun Microsystems
|-
| Bibek Sahu|| || Bibek||bibek||Impress pieces||Trees For Life
|-
| Andreas Schlüns|| X || as||||Framework||Sun Microsystems
|-
| Ingo Schmidt|| X || is||||(Native) Installation||Sun Microsystems
|-
| [[User:Jsc|Jürgen Schmidt]]|| X || jsc||jsc||PL API, CL Extensions, UNO, SDK||Sun Microsystems
|-
| Stephan Schäfer|| X || ssa||ssa||VCL||Sun Microsystems
|-
| Frank Schönheit|| X || fs||FrankS||Database Access, Forms||Sun Microsystems
|-
| Stella Schulze|| X || sts||||Visual Design||Sun Microsystems
|-
| Julian Seward || || sewardj || || valgrind ||
|-
| Darragh Sherwin|| || dsherwin||darragh||E-Legislation / E-GovSystems||Propylon
|-
|Lei shi || || shilei|| sl || Graphics|| [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Zhoubo Shi || || shizhoubo || || || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Raul Siddhartha|| || rsiddhartha||raul||GTK File Selector||Novell, Inc.
|-
| Sarah Smith|| || ssmith||||||
|-
| [[User:mox|Mox Soini]] || X || mox || Moxed || Mac Porting ||
|-
| Rajesh Sola|| || rajeshsola||sola||misc.||NOSIP
|-
| Kai Sommerfeld|| X || kso||||manager & hacker||Sun Microsystems
|-
| Oliver Specht|| X || os||||PL UI||Sun Microsystems
|-
| Jörg Spindler|| || jspindler||||||
|-
| Fridrich Štrba|| X || fridrich_strba||Fridrich||Word Perfect Hacker||Novell, Inc.
|-
| Keith Stribley|| X || kstribley||||Graphite fonts, Myanmar l10n||
|-
| Ulf Stroehler|| || us||||||Sun Microsystems
|-
| [[User:Muthusuba|Muthu Subramanian]]|| X || muthusuba||muthusuba||misc.||
|-
| Louis Suárez-Potts|| || louis||louis||Community Manager||Collab.net
|-
| Claus Sørensen|| || cs||c26n,cHBs,chbs||Danish Localization and Project Management Tool(oopm)||ProFOSS
|-
|Quanfa Tang || || tqfa|| tangquanfa|| Calc || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| David Tardon || X || dtardon || dtardon || || [[Red Hat Inc.]]
|-
| Stefan Taxhet|| X || st||stx12||CC, interpersonal problem fixer||Sun Microsystems
|-
| Armin Theissen|| || armin||||||
|-
| Caio Tiago Oliveira|| X || asrail||asrail||CL QA, release testing pt-BR builds||BrOffice.org
|-
| Jan Tietjens|| || tietjens||||||
|-
| Rüdiger Timm|| X || rt|| rtimm ||RE||Sun Microsystems
|-
| [[User:mt|Malte Timmermann]]|| X || mt|| Malte || Accessibility, Security, Performance||Sun Microsystems
|-
| Gerhard Tonn|| || tonn||||s390||
|-
| Willem van Dorp|| || willem.vandorp||||||
|-
| Tom Verbeek|| X || tv||||Wizards, Art team||Sun Microsystems
|-
| Sander Vesik|| || svesik||||||
|-
| Daniel Vogelheim|| X || dvo||||XML||
|-
| Mikhail Voitenko|| X || mav||mav||Framework||Sun Microsystems
|-
| Robert Vojta|| X || rvojta||rvojta||VBA Interop||
|-
| Dirk Völzke|| X || dv||||Installation||Sun Microsystems
|-
| [[User:Sparcmoz|Jim Watson]]|| X || sparcmoz|| sparcmoz||GNU Linux sparc porter||clug.org.au
|-
| [[User:Weiz |Zhao Wei ]] || || weiz || weiz || chart, AODL || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Armin Weiss|| X || aw||||||Sun Microsystems
|-
| Gerd Weiss|| X || gm||||RE||Sun Microsystems
|-
| Dan Williams|| X || fa||dcbw||Mac et. al. hacker||RedHat, Inc.
|-
|[[User:wuy|Yan Wu]] || X || wuy || ||Framework || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Stephan Wunderlich|| X || sw||||||
|-
|Dehua Xu || || xudehua || xudh || Release || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Kohei Yoshida|| X || kohei||kohei_||[[Calc]] hacker, Calc optimization solver developer||Novell, Inc.
|-
| George Zahopoulos|| X || georgez||||||
|-
| Kurt Zenker|| X || kz||smoketester||RE||Sun Microsystems
|-
|Huajun Zhang || || zhanghuajun|| zhanghj|| SW ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|[[User:Zhangxiaofei|Xiaofei Zhang]]|| || Zhangxiaofei || zhangxiaofei/FelixZ || [[Framework]] ||[[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
|Jianwei Zhao || || zhaojianwei || zhaojianwei || Swriter || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Sheng zhao|| X || jacky23 || ||OdfToolKit_odf4j || [[Beijing Redflag Chinese 2000 Software Co., Ltd.|Beijing Redflag CH2000]]
|-
| Claudio F Filho|| || filhocf||filhocf||Brazilian portuguese Localization||BrOffice.org
|-
| Xiaoyang Yu|| || || ||Disk block reordering||Intel Corporation
|-
| Antonio Xu|| X || antoxu || antoxu || Async dialogs, PRC improvements || Intel Corporation
|-
| Rail Aliev || X || rail || rail || Ru and Tr NL Co-lead || Infra-Resource
|-
| Jeremy Zheng|| X || zhiming || Jeremy || Async dialogs, PRC improvements || Intel Corporation
|-
| [[User:Schmidtm|Matthias Schmidt]] || || schmidtm || schmidtm || Mac OSX Aqua Port || Sun Microsystems
|-
| Yuri Dario || || ydario || Paperino || OS/2 Port || Serenity Systems intl
|-
| Fong Lin || X || pflin || Fong || CJK Enhancement/ Filter || Novell, Inc.
|-
| [[User:jza|Alexandro Colorado]]|| X || jza || jza|| CL [[OOoES|ES]] ||
|-
| Sunil Amitkumar Janki || || sjanki || sjanki || GNU Linux mipsel porter ||
|-
| [[User:Rescue|Joey Stanford]] || || Rescue/k0fcc || Rinchen || CL [http://eo.openoffice.org/ Esperanto native-lang project] || [http://canonical.com Canonical] ||
|-
| Mingfei Jia || X || jiamingfei || || Lotus Smart Suite filter || IBM Corp.
|-
| Xing Li || X || lixxing || || Accessibility || IBM Corp.
|-
| Wei Guo SHI || X || shiwg || || Accessibility and Smart Suite filter || IBM Corp.
|-
| Takashi Ono || X || tono || || MinGW port || Independent
|-
|}

=== QA Engineers ===

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;"
|-
! Name ||CVS||@openoffice.org || [[IRC Communication]] || Interested modules || Notes || Affiliation
|-
| Stefan Baltzer||||sba||||writer||||Sun Microsystems
|-
| Thorsten Bosbach||X||tbo||||framework, qa/qatesttool||QA Framework / Automation||Sun Microsystems
|-
| Oliver Craemer||X||oc||||[[Calc]]||QA Calc / Automation||Sun Microsystems
|-
| Helge Delfs||X||hde||||writer, qa/qatesttool||QA Writer / Automation||Sun Microsystems
|-
| Fredrik Haegg||X||fha||||draw, impress, qa/qatesttool||QA Graphics / Automation||Sun Microsystems
|-
| Hasan Ilter||||hi||||writer, printing, pdf export||||Sun Microsystems
|-
| Michael Rüß||||mru||||writer, word im/export||||Sun Microsystems
|-
| Éric Savary||||es||||writer, accessibility||||Sun Microsystems
|-
| [[User:jsi|Joerg Sievers]]||X||jsi||jogi||qa/qatesttool, [[Calc]]||Automation / QA Calc||Sun Microsystems
|-
| Joerg Skottke||X||jsk||skotti||framework, qa/qatesttool||QA Framework / Automation||Sun Microsystems
|-
| Marc Neumann||X||msc||||database, qa/qatesttool||QA Base / Automation||Sun Microsystems
|-
| Chris Lukasiak||||clu||||database||||Sun Microsystems
|-
| Frank Stecher||||fst||||[[Calc]]||||Sun Microsystems
|-
| Jack Warchold|||| jw||||writer, import/export filters||||Sun Microsystems
|-
| Uwe Luebbers||||ul||||framework||||Sun Microsystems
|-
| Thorsten Martens||||tm||||framework||||Sun Microsystems
|-
| Olaf Felka|||| of||||framework, installation||||Sun Microsystems
|-
| Thomas Klarhoefer||||kla||||chart||||Sun Microsystems
|-
| Wolfram Garten|||| wg||||draw, impress||||Sun Microsystems
|-
| Christian Guenther||||cgu||||draw, impress||||Sun Microsystems
|-
| [[User:Thorsten_Ziehm|Thorsten Ziehm]]||||| thorstenziehm||||||QA lead||Sun Microsystems
|-
|}

We are tracking pending JCAs in the document [[Pending JCAs]].

== Related Pages ==
* [[Commit Rights]]
* [[Contributing Patches]]
* [[User Experience Community]]
* A map of OOo developers around the world is available at http://www.frappr.com/ooodev, please add yourself to the map if you're involved in OOo development. It's just fun to see who's where :-)

[[Category:Development]]
[[Category:Alpha Centauri]]

Writing warning-free code

2008-07-10T06:21:07Z

Dtardon:

We are currently on the way towards a completely warning-free OOo C/C++ code base. And once we have reached that, we want to keep the code clean!

We reached a first milestone by integrating CWS [http://eis.services.openoffice.org/EIS2/servlet/cws.showCWS?Id=2903&Path=SRC680%2Fwarnings01 warnings01] into SRC680m173. Since then, and at least on the <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code> platforms, the C/C++ compilers are used with rather aggressive warning levels, and in most CVS modules warnings are treated as errors that break the build. Some CVS modules have not yet been made warning-free.

==What changed?==

Since SRC680m173, any new or modified C/C++ code that produces warnings will break the build. Ideally, to be sure that integrating a CWS will not break the build, the CWS should now be built on every warning-free platform (i.e., at least <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code>), with all supported compiler versions, in both product and non-product variants, and with and without the <code>debug=x</code> build switch before nominating it for integration. Practically, a reasonable subset of these will have to suffice.

For <code>unxlngi6</code>, we concentrated on GCC 3.4.1, GCC 4.0.2/4.0.3, and GCC 4.1.1, while other GCC versions probably produce slightly different warnings (that could break the build now on those GCC versions).

Porters are encouraged to make additional platforms warning-free. Since most ports are using GCC, there should not be too many surprises. Any necessary changes to the platform-specific <code>.mk</code> file in <code>solenv/inc</code> can be modelled after <code>solenv/inc/unxlngi6.mk</code>. In short, you need a bunch of <code>CFLAGSxxx</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=758 interface-announce C/C++ compiler warnings]) and <code>MODULES_WITH_WARNINGS</code> or <code>COMPILER_WARN_ERRORS</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=942 interface-announce MODULES_WITH_WARNINGS]).

The <code>wall=x</code> build switch no longer has any effect on the warning-free platforms. Once all platforms are warning-free, we can remove it completely.

==The missing modules==

If your job is to clean up a given CVS module, here are some practical guidelines:
* Remove the module from the <code>MODULES_WITH_WARNINGS</code> list in the platform-specific <code>.mk</code> files in <code>solenv/inc</code>.
* Make sure your module builds and delivers successfully with <code>build && deliver</code> (and all the variants mentioned above).
* If your module contains external code which we do not want to clean up, set <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> at the beginning of the corresponding <code>makefile.mk</code>, so that warnings do not lead to errors there.
* In any case, for any header file delivered from your module, make sure that <code>testhxx</code> on the delivered header file is successful. (Note that <code>testhxx</code> only works for headers delivered to the solver, not for local headers within a CVS module, as it calls the compiler with only a fixed set of include directories.)
* If you encounter a warning that cannot reasonably be worked around, discuss that problem on <code>dev@openoffice.org</code>. One outcome of that discussion can be that we globally disable that particular warning. To see which warnings are already globally disabled on a given platform, look at the settings for <code>CFLAGSWARNCC</code>, <code>CFLAGSWARNCXX</code>, <code>CFLAGSWALLCC</code>, and/or <code>CFLAGSWALLCXX</code> in the platform-specific <code>.mk</code> file in <code>solenv/inc</code> (<code>unxlngi6.mk</code>, <code>unxsoli4.mk</code>, <code>unxsols4.mk</code>, and <code>wntmsci10.mk</code>).

See the current [[Warning-free_code_status|warning-free code status]].

==Tips for Warning-free code==

The following is a list of issues you might come across when making existing
code warning-free, or when writing new, warning-free code:

===Integral conversions===

Sometimes, a cast between integral types is needed to avoid a warning. In such a case, use <code>sal::static_int_cast</code> (C++) or <code>SAL_INT_CAST</code> (C) to make that cast stick out—it will need to be adapted when the type of any of the involved expressions changes later on:
<source lang="cpp">
sal_Int32 n;
std::vector<char> v;
if (n >= 0 && sal::static_int_cast<sal_uInt32>(n) == v.size()) ...
</source>

Note that you might get the warning C4244 (possible loss of data) on Windows also for the following situation:
<source lang="cpp">
short a = 0, b = 0;
a += b; // warning C4244 on Windows
</source>
This is because <code>a</code> and <code>b</code> are converted to <code>int</code>, then added and the result is then again cast back to <code>short</code>. This is especially nasty, as it also happens when you use <code>xub_StrLen</code>, but only if it is a typedf to <code>USHORT</code> and not to <code>sal_uInt32</code>, i.e. only as long as <code>STRING32</code> is not defined in solar.h.
The warning does not occur when you use <code>operator+</code> instead of <code>operator+=</code>.
<source lang="cpp">
short a = 0, b = 0;
a = a + b;
</source>

===Invalid enum case values===

Code like
<source lang="cpp">
enum E { A=1, B=2, C=4 } e;
switch (e) {
case A: ...
case B|C: ...
}
</source>
will cause <code>wntmsci11</code> to complain with <code>warning C4063: case '6' is not a valid value for switch of enum 'E'</code>. This can be worked around by promoting <code>e</code> to is underlying integral type:
<source lang="cpp">
...
switch (+e) {
...
</source>

----

I think the compiler warning is perfectly valid there (although a little misleading). There is a simple reason for it: because of C++ computing rules for operator|, the second case statement (B|C) has type int and value 6, whilst compiler expects it to have type E. There is not automatic conversion from int to enumeration type; even if there were one, no enumerator from E has value 6. So, in the "work around", the second case statement is actually ''unreachable'' (well, suppose there are no explicit casts in assignment to e)!

What the author probably wanted is
<source lang="cpp">
switch (e) {
case A: ...
case B: // No code, falls through to the next statement
case C: ... // The code of the original B|C branch
}
</source>

-- dt

===Casting between pointer and integer types===

====C++====

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to unsigned integral type <code>U</code>:
<source lang="cpp">
P p;
U u = sal::static_int_cast(reinterpret_cast<sal_uIntPtr>(p));
</source>

* From unsigned integral type <code>U</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
U u;
P p = reinterpret_cast(sal::static_int_cast<sal_uIntPtr>(u));
</source>

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to signed integral type <code>S</code>:
<source lang="cpp">
P p;
S s = sal::static_int_cast<S>(reinterpret_cast<sal_IntPtr>(p));
</source>

* From signed integral type <code>S</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = reinterpret_cast(sal::static_int_cast<sal_IntPtr>(s));
</source>

====C====

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to unsigned integer type <code>U</code>:
<source lang="c">
P p;
U u = SAL_INT_CAST(U, (sal_uIntPtr) p);
</source>

* From unsigned integer type <code>U</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="c">
U u;
P p = (P) SAL_INT_CAST(sal_uIntPtr, u);
</source>

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to signed integer type <code>S</code>:
<source lang="cpp">
P p;
S s = SAL_INT_CAST(S, (sal_IntPtr) p);
</source>

* From signed integer type <code>S</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = (P) SAL_INT_CAST(sal_IntPtr, s);
</source>

===Pointer to function===

A pointer to function is not compatible with a pointer to object, so code like
<source lang="cpp">
void * osl::Module::getSymbol(rtl::OUString const &);
typedef void (* MyFunc)();
MyFunc f = module.getSymbol("myFunc");
</source>
will not compile. The only places were converting between pointer to function and pointer to object (typically <code>void *</code>) should be necessary are <code>osl::Module::getSymbol</code> and <code>osl::Module::getUrlFromAddress</code>, and in both cases there are additional functions (<code>osl::Module::getFunctionSymbol</code> and an overload with <code>oslGenericFunction</code> of <code>osl::Module::getUrlFromAddress</code>) that handle the problem internally. Use them!

===Name hiding===

In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
<source lang="cpp">
class Base {
public:
virtual void f(int);
virtual void f(double);
};
class Derived: public Base {
public:
using Base::f;
virtual void f(int);
};
</source>

Make sure to apply the correct access control to the <code>using</code> declaration:
<source lang="cpp">
class Base {
protected:
void f();
};
class Derived: public Base {
public:
void f(int);
protected:
using Base::f;
};
</source>

If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.

===Unused parameters===

There are three cases where a parameter of a function is not actually used in the definition of the function:

* The function has to have a certain signature (it is a virtual function, shall be used with a certain function pointer type, or is part of a stable API that cannot be changed). In those cases, leave out the paramter name in the function definition (C++) or use
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body (C).

* The function is created by the Macro IMPL_LINK( Class, Method, ArgType, ArgName ) from tools/inc/link.hxx or similar. Use EMPTYARG as Parametername as in
<source lang="cpp">
IMPL_LINK( Class, Method, ArgType, EMPTYARG )
</source>
EMPTYARG is defined empty, so this will result in leaving out the parameter name as suggested above.

* The function uses the paramter only in an <code>#ifdef</code>-block, or only in <code>OSL_ASSERT</code> etc. debug code. If the first case occurs in C++ code, fix it by using the same <code>#ifdef</code> around the parameter name in the function header. In all other cases, fix it by using
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body.

* The function once used the parameter, but does no longer do so. In that case, clean up the function declaration and all uses of the function.

===When all else fails===

There are cases where the only sensible solution is to suppress warnings for a given chunk of code:

* As explained above, in external code which we do not want to clean up, use <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> so that warnings do not lead to errors there.

* Header files included directly from the system, or header files delivered from external code included in the OOo code base but which we cannot reasonably make <code>testhxx</code>-clean: Surround that code (e.g., the <code>#include</code>-directives for those headers) by
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
and
<source lang="cpp">
#if defined __SUNPRO_CC
#pragma enable_warn
#elif defined _MSC_VER
#pragma warning(pop)
#endif
</source>
(probably together with an explanatory comment). Due to the nature of the GCC solution, this does not work directly within the compilation unit's main (<code>.c</code>, <code>.cxx</code>) file, only within a (<code>.h</code>, <code>.hxx</code>) file included directly or indirectly. Even more important, because the <code>system_header</code> pragma affects the ''rest of the current header'', the entire warnings guard mechanism should be separated into a ''header file on its own'', including just the file in question. From the original file then include that wrapper file.

* Code generated by <code>flex</code> or <code>bison</code>: The solution here is similar to the solution in the previous item—disable all warnings in the generated code. However, this has two implications: For one, it means that also all warnings from our client code integrated into the <code>flex</code>/<code>bison</code> output are suppressed; this is not really that large an issue, given the relatively small number of <code>flex</code>/<code>bison</code> files we use. For another, due to the nature of the GCC solution, it means that you need to introduce a wrapper file. The individual steps for a given <code>flex</code>/<code>bison</code> file named <code>example.ly</code>, translated to <code>$(MISC)$/example.cxx</code>, are as follows: First, change <code>example.ly</code> by adding
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
(probably together with an explanatory comment) at the very end of the initial <code>%{...%}</code> section (for <code>_MSC_VER</code>, <code>#pragma warning(push, 1)</code> might not disable all the warnings that occur; in that case, add <code>#pragma warning(disable: NNN1 NNN2 ...)</code> after it to disable specific warnings <code>NNN1</code>, <code>NNN2</code>, etc.). Second, create a new file named <code>wrap_example.cxx</code> in the same source directory as <code>exmaple.ly</code>, containing
<source lang="cpp">
#include "example.cxx"
</source>
Third, change the corresponding <code>makefile.mk</code> by adding
<code>[]
INCPRE=$(MISC)
</code>
to the top, by changing occurences of <code>example.obj</code> to <code>wrap_example.obj</code>, and by adding
<code>[]
$(OBJ)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
and/or
<code>[]
$(SLO)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
at the bottom.

[[Category:Development]]

[[Category:Education]]

Writing warning-free code

2008-07-10T06:03:18Z

Dtardon: Comment to validity of the "switch" example

We are currently on the way towards a completely warning-free OOo C/C++ code base. And once we have reached that, we want to keep the code clean!

We reached a first milestone by integrating CWS [http://eis.services.openoffice.org/EIS2/servlet/cws.showCWS?Id=2903&Path=SRC680%2Fwarnings01 warnings01] into SRC680m173. Since then, and at least on the <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code> platforms, the C/C++ compilers are used with rather aggressive warning levels, and in most CVS modules warnings are treated as errors that break the build. Some CVS modules have not yet been made warning-free.

==What changed?==

Since SRC680m173, any new or modified C/C++ code that produces warnings will break the build. Ideally, to be sure that integrating a CWS will not break the build, the CWS should now be built on every warning-free platform (i.e., at least <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code>), with all supported compiler versions, in both product and non-product variants, and with and without the <code>debug=x</code> build switch before nominating it for integration. Practically, a reasonable subset of these will have to suffice.

For <code>unxlngi6</code>, we concentrated on GCC 3.4.1, GCC 4.0.2/4.0.3, and GCC 4.1.1, while other GCC versions probably produce slightly different warnings (that could break the build now on those GCC versions).

Porters are encouraged to make additional platforms warning-free. Since most ports are using GCC, there should not be too many surprises. Any necessary changes to the platform-specific <code>.mk</code> file in <code>solenv/inc</code> can be modelled after <code>solenv/inc/unxlngi6.mk</code>. In short, you need a bunch of <code>CFLAGSxxx</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=758 interface-announce C/C++ compiler warnings]) and <code>MODULES_WITH_WARNINGS</code> or <code>COMPILER_WARN_ERRORS</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=942 interface-announce MODULES_WITH_WARNINGS]).

The <code>wall=x</code> build switch no longer has any effect on the warning-free platforms. Once all platforms are warning-free, we can remove it completely.

==The missing modules==

If your job is to clean up a given CVS module, here are some practical guidelines:
* Remove the module from the <code>MODULES_WITH_WARNINGS</code> list in the platform-specific <code>.mk</code> files in <code>solenv/inc</code>.
* Make sure your module builds and delivers successfully with <code>build && deliver</code> (and all the variants mentioned above).
* If your module contains external code which we do not want to clean up, set <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> at the beginning of the corresponding <code>makefile.mk</code>, so that warnings do not lead to errors there.
* In any case, for any header file delivered from your module, make sure that <code>testhxx</code> on the delivered header file is successful. (Note that <code>testhxx</code> only works for headers delivered to the solver, not for local headers within a CVS module, as it calls the compiler with only a fixed set of include directories.)
* If you encounter a warning that cannot reasonably be worked around, discuss that problem on <code>dev@openoffice.org</code>. One outcome of that discussion can be that we globally disable that particular warning. To see which warnings are already globally disabled on a given platform, look at the settings for <code>CFLAGSWARNCC</code>, <code>CFLAGSWARNCXX</code>, <code>CFLAGSWALLCC</code>, and/or <code>CFLAGSWALLCXX</code> in the platform-specific <code>.mk</code> file in <code>solenv/inc</code> (<code>unxlngi6.mk</code>, <code>unxsoli4.mk</code>, <code>unxsols4.mk</code>, and <code>wntmsci10.mk</code>).

See the current [[Warning-free_code_status|warning-free code status]].

==Tips for Warning-free code==

The following is a list of issues you might come across when making existing
code warning-free, or when writing new, warning-free code:

===Integral conversions===

Sometimes, a cast between integral types is needed to avoid a warning. In such a case, use <code>sal::static_int_cast</code> (C++) or <code>SAL_INT_CAST</code> (C) to make that cast stick out—it will need to be adapted when the type of any of the involved expressions changes later on:
<source lang="cpp">
sal_Int32 n;
std::vector<char> v;
if (n >= 0 && sal::static_int_cast<sal_uInt32>(n) == v.size()) ...
</source>

Note that you might get the warning C4244 (possible loss of data) on Windows also for the following situation:
<source lang="cpp">
short a = 0, b = 0;
a += b; // warning C4244 on Windows
</source>
This is because <code>a</code> and <code>b</code> are converted to <code>int</code>, then added and the result is then again cast back to <code>short</code>. This is especially nasty, as it also happens when you use <code>xub_StrLen</code>, but only if it is a typedf to <code>USHORT</code> and not to <code>sal_uInt32</code>, i.e. only as long as <code>STRING32</code> is not defined in solar.h.
The warning does not occur when you use <code>operator+</code> instead of <code>operator+=</code>.
<source lang="cpp">
short a = 0, b = 0;
a = a + b;
</source>

===Invalid enum case values===

Code like
<source lang="cpp">
enum E { A=1, B=2, C=4 } e;
switch (e) {
case A: ...
case B|C: ...
}
</source>
will cause <code>wntmsci11</code> to complain with <code>warning C4063: case '6' is not a valid value for switch of enum 'E'</code>. This can be worked around by promoting <code>e</code> to is underlying integral type:
<source lang="cpp">
...
switch (+e) {
...
</source>

----

I think the compiler warning is perfectly valid there (although a little misleading). There is a simple reason for it: because of C++ computing rules for operator|, the second case statement (B|C) has type int and value 6, whilst compiler expects it to have type E. There is not automatical conversion from int to enumeration type; even if there were one, no enumerator from E has value 6. So, in the "work around", the case is actually ''unreachable'' (well, suppose there are no explicit casts in assignment to e)!

What the author probably wanted is
<source lang="cpp">
switch (e) {
case A: ...
case B: // No code, falls through to the next statement
case C: ... // The code of the original B|C branch
}
</source>

-- dt

===Casting between pointer and integer types===

====C++====

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to unsigned integral type <code>U</code>:
<source lang="cpp">
P p;
U u = sal::static_int_cast(reinterpret_cast<sal_uIntPtr>(p));
</source>

* From unsigned integral type <code>U</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
U u;
P p = reinterpret_cast(sal::static_int_cast<sal_uIntPtr>(u));
</source>

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to signed integral type <code>S</code>:
<source lang="cpp">
P p;
S s = sal::static_int_cast<S>(reinterpret_cast<sal_IntPtr>(p));
</source>

* From signed integral type <code>S</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = reinterpret_cast(sal::static_int_cast<sal_IntPtr>(s));
</source>

====C====

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to unsigned integer type <code>U</code>:
<source lang="c">
P p;
U u = SAL_INT_CAST(U, (sal_uIntPtr) p);
</source>

* From unsigned integer type <code>U</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="c">
U u;
P p = (P) SAL_INT_CAST(sal_uIntPtr, u);
</source>

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to signed integer type <code>S</code>:
<source lang="cpp">
P p;
S s = SAL_INT_CAST(S, (sal_IntPtr) p);
</source>

* From signed integer type <code>S</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = (P) SAL_INT_CAST(sal_IntPtr, s);
</source>

===Pointer to function===

A pointer to function is not compatible with a pointer to object, so code like
<source lang="cpp">
void * osl::Module::getSymbol(rtl::OUString const &);
typedef void (* MyFunc)();
MyFunc f = module.getSymbol("myFunc");
</source>
will not compile. The only places were converting between pointer to function and pointer to object (typically <code>void *</code>) should be necessary are <code>osl::Module::getSymbol</code> and <code>osl::Module::getUrlFromAddress</code>, and in both cases there are additional functions (<code>osl::Module::getFunctionSymbol</code> and an overload with <code>oslGenericFunction</code> of <code>osl::Module::getUrlFromAddress</code>) that handle the problem internally. Use them!

===Name hiding===

In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
<source lang="cpp">
class Base {
public:
virtual void f(int);
virtual void f(double);
};
class Derived: public Base {
public:
using Base::f;
virtual void f(int);
};
</source>

Make sure to apply the correct access control to the <code>using</code> declaration:
<source lang="cpp">
class Base {
protected:
void f();
};
class Derived: public Base {
public:
void f(int);
protected:
using Base::f;
};
</source>

If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.

===Unused parameters===

There are three cases where a parameter of a function is not actually used in the definition of the function:

* The function has to have a certain signature (it is a virtual function, shall be used with a certain function pointer type, or is part of a stable API that cannot be changed). In those cases, leave out the paramter name in the function definition (C++) or use
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body (C).

* The function is created by the Macro IMPL_LINK( Class, Method, ArgType, ArgName ) from tools/inc/link.hxx or similar. Use EMPTYARG as Parametername as in
<source lang="cpp">
IMPL_LINK( Class, Method, ArgType, EMPTYARG )
</source>
EMPTYARG is defined empty, so this will result in leaving out the parameter name as suggested above.

* The function uses the paramter only in an <code>#ifdef</code>-block, or only in <code>OSL_ASSERT</code> etc. debug code. If the first case occurs in C++ code, fix it by using the same <code>#ifdef</code> around the parameter name in the function header. In all other cases, fix it by using
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body.

* The function once used the parameter, but does no longer do so. In that case, clean up the function declaration and all uses of the function.

===When all else fails===

There are cases where the only sensible solution is to suppress warnings for a given chunk of code:

* As explained above, in external code which we do not want to clean up, use <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> so that warnings do not lead to errors there.

* Header files included directly from the system, or header files delivered from external code included in the OOo code base but which we cannot reasonably make <code>testhxx</code>-clean: Surround that code (e.g., the <code>#include</code>-directives for those headers) by
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
and
<source lang="cpp">
#if defined __SUNPRO_CC
#pragma enable_warn
#elif defined _MSC_VER
#pragma warning(pop)
#endif
</source>
(probably together with an explanatory comment). Due to the nature of the GCC solution, this does not work directly within the compilation unit's main (<code>.c</code>, <code>.cxx</code>) file, only within a (<code>.h</code>, <code>.hxx</code>) file included directly or indirectly. Even more important, because the <code>system_header</code> pragma affects the ''rest of the current header'', the entire warnings guard mechanism should be separated into a ''header file on its own'', including just the file in question. From the original file then include that wrapper file.

* Code generated by <code>flex</code> or <code>bison</code>: The solution here is similar to the solution in the previous item—disable all warnings in the generated code. However, this has two implications: For one, it means that also all warnings from our client code integrated into the <code>flex</code>/<code>bison</code> output are suppressed; this is not really that large an issue, given the relatively small number of <code>flex</code>/<code>bison</code> files we use. For another, due to the nature of the GCC solution, it means that you need to introduce a wrapper file. The individual steps for a given <code>flex</code>/<code>bison</code> file named <code>example.ly</code>, translated to <code>$(MISC)$/example.cxx</code>, are as follows: First, change <code>example.ly</code> by adding
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
(probably together with an explanatory comment) at the very end of the initial <code>%{...%}</code> section (for <code>_MSC_VER</code>, <code>#pragma warning(push, 1)</code> might not disable all the warnings that occur; in that case, add <code>#pragma warning(disable: NNN1 NNN2 ...)</code> after it to disable specific warnings <code>NNN1</code>, <code>NNN2</code>, etc.). Second, create a new file named <code>wrap_example.cxx</code> in the same source directory as <code>exmaple.ly</code>, containing
<source lang="cpp">
#include "example.cxx"
</source>
Third, change the corresponding <code>makefile.mk</code> by adding
<code>[]
INCPRE=$(MISC)
</code>
to the top, by changing occurences of <code>example.obj</code> to <code>wrap_example.obj</code>, and by adding
<code>[]
$(OBJ)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
and/or
<code>[]
$(SLO)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
at the bottom.

[[Category:Development]]

[[Category:Education]]