Difference between revisions of "Framework/Tutorial/Context Menu Interception"
(→Context menu interception architecture) |
|||
Line 16: | Line 16: | ||
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. | 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. | ||
+ | |||
+ | <source lang="idl"> | ||
+ | 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); | ||
+ | }; | ||
+ | |||
+ | }; }; }; }; | ||
+ | </source> | ||
+ | |||
=== Register and Remove an Interceptor === | === 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. | 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. |
Revision as of 14:24, 1 November 2008
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.
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.