Framework/Tutorial/Context Menu Interception

This tutorial will give you a detailed step-by-step insight into a very flexible way to add a context menu interceptor into OpenOffice.org 2.x/3.0. A Context menu interceptor must be implemented via UNO supporting the com.sun.star.ui.XContextMenuInterceptor interface. This tutorial will be split into small chapters which describe different aspects of context menu interception. Everybody is invited to participate. May be someone wants to translate the extension to a different language (e.g. Java or Python) or wants to have more information about a specific topic. You can set a link to this page, if you think that this page adds valuable information.

The reader of this tutorial should know the following

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

A context menu is displayed when an object is right clicked. Typically, a context menu has context dependent functions to manipulate the selected object, such as cut, copy and paste. Developers can intercept context menus before they are displayed to cancel the execution of a context menu, add, delete, or modify the menu by replacing context menu entries or complete sub menus. It is possible to provide new customized context menus.

General abstract of the context menu interception concept

Context menu interception architecture

Context menu interception is implemented by the observer pattern. This pattern defines a one-to-many dependency between objects, so that when an object changes state, all its dependents are notified. The implementation supports more than one interceptor which are chained in a queue. The root access point for intercepting context menus is a com.sun.star.frame.Controller object. The controller implements the interface com.sun.star.ui.XContextMenuInterception to support context menu interception. A context menu interceptor must support the com.sun.star.ui.XContextMenuInterceptor interface. It's used by the interception implementation to notify an interceptor whenever a context menu is going to be shown.

module com { module sun { module star { module ui {
 
//============================================================================= 
 
/** This interface enables the object to be registered as an interceptor
    to change context menus or prevent them from being executed.
*/
 
published interface XContextMenuInterceptor : ::com::sun::star::uno::XInterface
{
    //-------------------------------------------------------------------------
    /** notifies the interceptor about the request to execute a context menu.
        The interceptor has to decide whether the menu should be executed with
        or without being modified or may ignore the call.
 
        @param aEvent
            provides information about the current context menu and other
            related data like mouse position, window and selection.
 
        @return 
            action which determines how the interception implementation should 
            proceed.
    */
    ContextMenuInterceptorAction notifyContextMenuExecute([in] ContextMenuExecuteEvent aEvent);
};
 
}; }; }; };

Register and Remove an Interceptor

The com.sun.star.ui.XContextMenuInterception interface enables the developer to register and remove an interceptor. When an interceptor is registered, it is notified whenever a context menu is about to be executed. Registering an interceptor adds it to the front of the interceptor chain, so that it is called first. The order of removals is arbitrary. It is not necessary to remove the interceptor that registered last.