1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef SD_FRAMEWORK_FRAMEWORK_HELPER_HXX 29 #define SD_FRAMEWORK_FRAMEWORK_HELPER_HXX 30 31 #include "ViewShell.hxx" 32 33 #include "tools/SdGlobalResourceContainer.hxx" 34 35 #include <com/sun/star/drawing/framework/XConfigurationController.hpp> 36 #include <com/sun/star/drawing/framework/XView.hpp> 37 #include <com/sun/star/lang/XEventListener.hpp> 38 39 #include <boost/scoped_ptr.hpp> 40 #include <boost/shared_ptr.hpp> 41 #include <boost/enable_shared_from_this.hpp> 42 #include <boost/function.hpp> 43 #include <map> 44 45 namespace sd { 46 class ViewShell; 47 class ViewShellBase; 48 } 49 50 namespace rtl { 51 class OUString; 52 } 53 54 namespace css = ::com::sun::star; 55 56 namespace sd { namespace framework { 57 58 /** The FrameworkHelper is a convenience class that simplifies the 59 access to the drawing framework. 60 It has three main tasks: 61 1. Provide frequently used strings of resource URLs and event names. 62 2. Provide shortcuts for accessing the sd framework. 63 3. Easy the migration to the drawing framwork. 64 65 Note that a FrameworkHelper disposes itself when one of the resource 66 controllers called by it throw a DisposedException. 67 */ 68 class FrameworkHelper 69 : public ::boost::enable_shared_from_this<FrameworkHelper>, 70 public SdGlobalResource 71 { 72 public: 73 // URLs of frequently used panes. 74 static const ::rtl::OUString msPaneURLPrefix; 75 static const ::rtl::OUString msCenterPaneURL; 76 static const ::rtl::OUString msFullScreenPaneURL; 77 static const ::rtl::OUString msLeftImpressPaneURL; 78 static const ::rtl::OUString msLeftDrawPaneURL; 79 static const ::rtl::OUString msRightPaneURL; 80 81 // URLs of frequently used views. 82 static const ::rtl::OUString msViewURLPrefix; 83 static const ::rtl::OUString msImpressViewURL; 84 static const ::rtl::OUString msDrawViewURL; 85 static const ::rtl::OUString msOutlineViewURL; 86 static const ::rtl::OUString msNotesViewURL; 87 static const ::rtl::OUString msHandoutViewURL; 88 static const ::rtl::OUString msSlideSorterURL; 89 static const ::rtl::OUString msPresentationViewURL; 90 static const ::rtl::OUString msTaskPaneURL; 91 92 // URLs of frequently used tool bars. 93 static const ::rtl::OUString msToolBarURLPrefix; 94 static const ::rtl::OUString msViewTabBarURL; 95 96 // URLs of task panels. 97 static const ::rtl::OUString msTaskPanelURLPrefix; 98 static const ::rtl::OUString msMasterPagesTaskPanelURL; 99 static const ::rtl::OUString msLayoutTaskPanelURL; 100 static const ::rtl::OUString msTableDesignPanelURL; 101 static const ::rtl::OUString msCustomAnimationTaskPanelURL; 102 static const ::rtl::OUString msSlideTransitionTaskPanelURL; 103 104 // Names of frequently used events. 105 static const ::rtl::OUString msResourceActivationRequestEvent; 106 static const ::rtl::OUString msResourceDeactivationRequestEvent; 107 static const ::rtl::OUString msResourceActivationEvent; 108 static const ::rtl::OUString msResourceDeactivationEvent; 109 static const ::rtl::OUString msConfigurationUpdateStartEvent; 110 static const ::rtl::OUString msConfigurationUpdateEndEvent; 111 112 // Service names of the common controllers. 113 static const ::rtl::OUString msModuleControllerService; 114 static const ::rtl::OUString msConfigurationControllerService; 115 116 /** Return the FrameworkHelper object that is associated with the given 117 ViewShellBase. If such an object does not yet exist, a new one is 118 created. 119 */ 120 static ::boost::shared_ptr<FrameworkHelper> Instance (ViewShellBase& rBase); 121 122 static ::boost::shared_ptr<FrameworkHelper> Instance ( 123 const css::uno::Reference<css::frame::XController>& rxController); 124 125 /** Mark the FrameworkHelper object for the given ViewShellBase as 126 disposed. A following ReleaseInstance() call will destroy the 127 FrameworkHelper object. 128 129 Do not call this method. It is an internally used method that can 130 not be made private. 131 */ 132 static void DisposeInstance (ViewShellBase& rBase); 133 134 /** Destroy the FrameworkHelper object for the given ViewShellBase. 135 136 Do not call this method. It is an internally used method that can 137 not be made private. 138 */ 139 static void ReleaseInstance (ViewShellBase& rBase); 140 141 /** Return an identifier for the given view URL. This identifier can be 142 used in a switch statement. See GetViewURL() for a mapping in the 143 opposite direction. 144 */ 145 static ViewShell::ShellType GetViewId (const rtl::OUString& rsViewURL); 146 147 /** Return a view URL for the given identifier. See GetViewId() for a 148 mapping in the opposite direction. 149 */ 150 static ::rtl::OUString GetViewURL (ViewShell::ShellType eType); 151 152 /** Return a ViewShell pointer for the given XView reference. This 153 assumes that the given reference is implemented by the 154 ViewShellWrapper class that supports the XTunnel interface. 155 @return 156 When the ViewShell pointer can not be inferred from the given 157 reference then an empty pointer is returned. 158 */ 159 static ::boost::shared_ptr<ViewShell> GetViewShell ( 160 const css::uno::Reference<css::drawing::framework::XView>& rxView); 161 162 ~FrameworkHelper (void); 163 164 typedef ::boost::function<bool(const css::drawing::framework::ConfigurationChangeEvent&)> 165 ConfigurationChangeEventFilter; 166 typedef ::boost::function<void(bool bEventSeen)> Callback; 167 typedef ::boost::function< 168 void( 169 const css::uno::Reference< 170 css::drawing::framework::XResourceId>&) 171 > ResourceFunctor; 172 173 /** Test whether the called FrameworkHelper object is valid. 174 @return 175 When the object has already been disposed then <FALSE/> is returned. 176 */ 177 bool IsValid (void); 178 179 /** Return a pointer to the view shell that is displayed in the 180 specified pane. See GetView() for a variant that returns a 181 reference to XView instead of a ViewShell pointer. 182 @return 183 An empty pointer is returned when for example the specified pane 184 does not exist or is not visible or does not show a view or one 185 of the involved objects does not support XUnoTunnel (where 186 necessary). 187 */ 188 ::boost::shared_ptr<ViewShell> GetViewShell (const ::rtl::OUString& rsPaneURL); 189 190 /** Return a reference to the view that is displayed in the specified 191 pane. See GetViewShell () for a variant that returns a ViewShell 192 pointer instead of a reference to XView. 193 @param rxPaneOrViewId 194 When this ResourceId specifies a view then that view is 195 returned. When it belongs to a pane then one view in that pane 196 is returned. 197 @return 198 An empty reference is returned when for example the specified pane 199 does not exist or is not visible or does not show a view or one 200 of the involved objects does not support XTunnel (where 201 necessary). 202 */ 203 css::uno::Reference<css::drawing::framework::XView> 204 GetView ( 205 const css::uno::Reference< 206 css::drawing::framework::XResourceId>& rxPaneOrViewId); 207 208 /** Request the specified view to be displayed in the specified pane. 209 When the pane is not visible its creation is also requested. The 210 update that creates the actual view object is done asynchronously. 211 @param rsResourceURL 212 The resource URL of the view to show. 213 @param rsAnchorURL 214 The URL of the pane in which to show the view. 215 @return 216 The resource id of the requested view is returned. With that 217 the caller can, for example, call RunOnResourceActivation() to 218 do some initialization after the requested view becomes active. 219 */ 220 css::uno::Reference<css::drawing::framework::XResourceId> RequestView ( 221 const ::rtl::OUString& rsResourceURL, 222 const ::rtl::OUString& rsAnchorURL); 223 224 /** Request the activation of the specified task panel in the standard 225 task pane. 226 @param rsTaskPanelURL 227 The panel that is to be activated. 228 @param bEnsureTaskPaneIsVisible 229 When this is <TRUE/> then the task pane is activated when not 230 yet active. 231 When this flag is <FALSE/> then the requested panel 232 is activated only when the task pane is already active. When it 233 is not active then this call is silently ignored. 234 */ 235 void RequestTaskPanel ( 236 const ::rtl::OUString& rsTaskPanelURL, 237 const bool bEnsureTaskPaneIsVisible = true); 238 239 /** Process a slot call that requests a view shell change. 240 */ 241 void HandleModeChangeSlot ( 242 sal_uLong nSlotId, 243 SfxRequest& rRequest); 244 245 /** Run the given callback when the specified event is notified by the 246 ConfigurationManager. When there are no pending requests and 247 therefore no events would be notified (in the foreseeable future) 248 then the callback is called immediately. 249 The callback is called with a flag that tells the callback whether 250 the event it waits for has been sent. 251 */ 252 void RunOnConfigurationEvent( 253 const ::rtl::OUString& rsEventType, 254 const Callback& rCallback); 255 256 /** Run the given callback when the specified resource has been 257 activated. When the resource is active already when this method is 258 called then rCallback is called before this method returns. 259 @param rxResourceId 260 Wait for the activation of this resource before calling 261 rCallback. 262 @param rCallback 263 The callback to be called when the resource is activated. 264 265 */ 266 void RunOnResourceActivation( 267 const css::uno::Reference<css::drawing::framework::XResourceId>& rxResourceId, 268 const Callback& rCallback); 269 270 /** Normally the requested changes of the configuration are executed 271 asynchronously. However, there is at least one situation (searching 272 with the Outliner) where the surrounding code does not cope with 273 this. So, instead of calling Reschedule until the global event loop 274 executes the configuration update, this method does (almost) the 275 same without the reschedules. 276 277 Do not use this method until there is absolutely no other way. 278 */ 279 void RequestSynchronousUpdate (void); 280 281 /** Block until the specified event is notified by the configuration 282 controller. When the configuration controller is not processing any 283 requests the method returns immediately. 284 */ 285 void WaitForEvent (const ::rtl::OUString& rsEventName) const; 286 287 /** This is a short cut for WaitForEvent(msConfigurationUpdateEndEvent). 288 Call this method to execute the pending requests. 289 */ 290 void WaitForUpdate (void) const; 291 292 /** Explicit request for an update of the current configuration. Call 293 this method when one of the resources managed by the sd framework 294 has been activated or deactivated from the outside, i.e. not by the 295 framework itself. An example for this is a click on the closer 296 button of one of the side panes. 297 */ 298 void UpdateConfiguration (void); 299 300 /** Return a string representation of the given XResourceId object. 301 */ 302 static ::rtl::OUString ResourceIdToString ( 303 const css::uno::Reference< 304 css::drawing::framework::XResourceId>& rxResourceId); 305 306 /** Create a new XResourceId object for the given resource URL. 307 */ 308 static css::uno::Reference< 309 css::drawing::framework::XResourceId> 310 CreateResourceId ( 311 const ::rtl::OUString& rsResourceURL); 312 313 /** Create a new XResourceId object for the given resource URL and a 314 single anchor URL. 315 */ 316 static css::uno::Reference< 317 css::drawing::framework::XResourceId> 318 CreateResourceId ( 319 const ::rtl::OUString& rsResourceURL, 320 const ::rtl::OUString& rsAnchorURL); 321 322 /** Create a new XResourceId object for the given resource URL and the 323 two given anchor URLs. 324 */ 325 static css::uno::Reference< 326 css::drawing::framework::XResourceId> 327 CreateResourceId ( 328 const ::rtl::OUString& rsResourceURL, 329 const ::rtl::OUString& rsFirstAnchorURL, 330 const ::rtl::OUString& rsSecondAnchorURL); 331 332 /** Create a new XResourceId object for the given resource URL. 333 */ 334 static css::uno::Reference< 335 css::drawing::framework::XResourceId> 336 CreateResourceId ( 337 const ::rtl::OUString& rsResourceURL, 338 const css::uno::Reference< 339 css::drawing::framework::XResourceId>& rxAnchor); 340 341 css::uno::Reference<css::drawing::framework::XConfigurationController> 342 GetConfigurationController (void) const; 343 344 345 private: 346 typedef ::std::map< 347 ViewShellBase*, 348 ::boost::shared_ptr<FrameworkHelper> > InstanceMap; 349 /** The instance map holds (at least) one FrameworkHelper instance for 350 every ViewShellBase object. 351 */ 352 static InstanceMap maInstanceMap; 353 class ViewURLMap; 354 static ::boost::scoped_ptr<ViewURLMap> mpViewURLMap; 355 356 ViewShellBase& mrBase; 357 css::uno::Reference<css::drawing::framework::XConfigurationController> 358 mxConfigurationController; 359 360 class DisposeListener; 361 friend class DisposeListener; 362 css::uno::Reference<css::lang::XComponent> 363 mxDisposeListener; 364 365 FrameworkHelper (ViewShellBase& rBase); 366 FrameworkHelper (const FrameworkHelper& rHelper); // Not implemented. 367 FrameworkHelper& operator= (const FrameworkHelper& rHelper); // Not implemented. 368 369 void Initialize (void); 370 371 void Dispose (void); 372 373 /** Run the given callback when an event of the specified type is 374 received from the ConfigurationController or when the 375 ConfigurationController has no pending change requests. 376 @param rsEventType 377 Run rCallback only on this event. 378 @param rFilter 379 This filter has to return <TRUE/> in order for rCallback to be 380 called. 381 @param rCallback 382 The callback functor to be called. 383 */ 384 void RunOnEvent( 385 const ::rtl::OUString& rsEventType, 386 const ConfigurationChangeEventFilter& rFilter, 387 const Callback& rCallback) const; 388 389 /** This disposing method is forwarded from the inner DisposeListener class. 390 */ 391 void disposing (const css::lang::EventObject& rEventObject); 392 }; 393 394 395 } } // end of namespace sd::framework 396 397 398 399 namespace sd { namespace framework { 400 401 namespace { 402 403 class FrameworkHelperAllPassFilter 404 { 405 public: 406 bool operator() (const css::drawing::framework::ConfigurationChangeEvent&) { return true; } 407 }; 408 409 410 class FrameworkHelperResourceIdFilter 411 { 412 public: 413 FrameworkHelperResourceIdFilter ( 414 const css::uno::Reference<css::drawing::framework::XResourceId>& rxResourceId); 415 bool operator() (const css::drawing::framework::ConfigurationChangeEvent& rEvent) 416 { return mxResourceId.is() && rEvent.ResourceId.is() 417 && mxResourceId->compareTo(rEvent.ResourceId) == 0; } 418 private: 419 css::uno::Reference<css::drawing::framework::XResourceId> mxResourceId; 420 }; 421 422 } // end of anonymous namespace 423 424 425 426 427 } } // end of namespace sd::framework 428 429 430 #endif 431