Difference between revisions of "Framework/Tutorial/Context Menu Interception"
Line 169: | Line 169: | ||
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. | ||
+ | |||
+ | === Writing an Interceptor === | ||
+ | |||
+ | ==== Implementing the notification part ==== | ||
+ | |||
+ | A context menu interceptor implements the com.sun.star.ui.XContextMenuInterceptor interface. This interface has one function that is called by the responsible controller whenever a context menu is about to be executed. |
Revision as of 23:19, 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.
Contents
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.
UNO interfaces, services, structs and constants
com::sun::star::ui::XContextMenuInterceptor
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); }; }; }; }; };
com::sun::star::ui::XContextMenuInterception
module com { module sun { module star { module ui { //============================================================================= /** This interface enables the object to get interceptors registered that change context menu or prevent them from being executed. */ published interface XContextMenuInterception : ::com::sun::star::uno::XInterface { //------------------------------------------------------------------------- /** registers am XContextMenuInterceptor, which will become the first interceptor in the chain of registered interceptors. @param Interceptor an interceptor which should be added at the start of the interceptor chain. */ void registerContextMenuInterceptor([in] XContextMenuInterceptor Interceptor); //------------------------------------------------------------------------- /** removes an XContextMenuInterceptor which was previously registered using XContextMenuInterception::registerContextMenuInterceptor. The order of removals is arbitrary. It's not necessary to remove the last registered interceptor first. @param Interceptor an interceptor which should be removed from the interceptor chain. */ void releaseContextMenuInterceptor([in] XContextMenuInterceptor Interceptor); }; }; }; }; };
com::sun::star::ui::ContextMenuInterceptorAction
module com { module sun { module star { module ui { //============================================================================= /** This interface enables the object to get interceptors registered that change context menu or prevent them from being executed. */ published enum ContextMenuInterceptorAction { /** the XContextMenuInterceptor has ignored the call. The next registered interceptor should be notified. */ IGNORED, /** the context menu must not be executed. The next registered interceptor should not be notified. */ CANCELLED, /** the menu has been modified and should be executed without notifying the next registered interceptor. */ EXECUTE_MODIFIED, /** the menu has been modified and the next registered interceptor should be notified. */ CONTINUE_MODIFIED }; }; }; }; };
com::sun::star::ui::ContextMenuExecuteEvent
module com { module sun { module star { module ui { //============================================================================= /** This interface enables the object to get interceptors registered that change context menu or prevent them from being executed. */ published struct ContextMenuExecuteEvent { /** contains the window where the context menu has been requested, */ ::com::sun::star::awt::XWindow SourceWindow; /** contains the position where the context menu should be displayed. */ ::com::sun::star::awt::Point ExecutePosition; /** enables access to the menu content. The implementing object has to support service com::sun::star::ui::ActionTriggerContainer */ ::com::sun::star::container::XIndexContainer ActionTriggerContainer; /** provides the current selection inside the source window. */ ::com::sun::star::view::XSelectionSupplier Selection; }; }; }; }; };
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.
Writing an Interceptor
Implementing the notification part
A context menu interceptor implements the com.sun.star.ui.XContextMenuInterceptor interface. This interface has one function that is called by the responsible controller whenever a context menu is about to be executed.