include/sfx2/shell.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_SFX2_SHELL_HXX
  20 #define INCLUDED_SFX2_SHELL_HXX
  21
  22 #include <memory>
  23 #include <rtl/ustring.hxx>
  24 #include <sal/config.h>
  25 #include <sal/types.h>
  26 #include <svl/typedwhich.hxx>
  27 #include <sfx2/dllapi.h>
  28 #include <svl/SfxBroadcaster.hxx>
  29 #include <o3tl/typed_flags_set.hxx>
  30 #include <o3tl/strong_int.hxx>
  31 #include <optional>
  32
  33 namespace com::sun::star::embed { struct VerbDescriptor; }
  34 namespace com::sun::star::uno { template <class E> class Sequence; }
  35
  36 class SfxItemPool;
  37 class SfxPoolItem;
  38 class SfxRequest;
  39 class SfxItemSet;
  40 class SfxInterface;
  41 class SfxViewShell;
  42 class SfxObjectShell;
  43
  44 class SfxShell;
  45 struct SfxShell_Impl;
  46 class SfxDispatcher;
  47 class SfxViewFrame;
  48 class SfxSlot;
  49 class SfxRepeatTarget;
  50 class SfxBindings;
  51 class SfxModule;
  52 class SfxUndoManager;
  53
  54 /**
  55     Id for <SfxInterface>s, gives a quasi-static access to the interface
  56     through an array to <SfxApplication>.
  57 */
  58 typedef o3tl::strong_int<sal_uInt16, struct SfxInterfaceIdTag> SfxInterfaceId;
  59
  60 constexpr auto SFX_INTERFACE_NONE         = SfxInterfaceId(0);
  61 constexpr auto SFX_INTERFACE_SFXAPP       = SfxInterfaceId(1);
  62 constexpr auto SFX_INTERFACE_SFXDOCSH     = SfxInterfaceId(2);
  63 constexpr auto SFX_INTERFACE_SFXVIEWSH    = SfxInterfaceId(3);
  64 constexpr auto SFX_INTERFACE_SFXVIEWFRM   = SfxInterfaceId(4);
  65 constexpr auto SFX_INTERFACE_SFXMODULE    = SfxInterfaceId(5);
  66 constexpr auto SFX_INTERFACE_SC_START     = SfxInterfaceId(150);
  67 constexpr auto SFX_INTERFACE_SD_START     = SfxInterfaceId(200);
  68 constexpr auto SFX_INTERFACE_SW_START     = SfxInterfaceId(250);
  69 constexpr auto SFX_INTERFACE_SMA_START    = SfxInterfaceId(340);
  70 constexpr auto SFX_INTERFACE_IDE_START    = SfxInterfaceId(400);
  71 constexpr auto SFX_INTERFACE_IDE_END      = SfxInterfaceId(409);
  72
  73 enum class SfxShellFeature
  74 {
  75     NONE                    = 0x0000,
  76     // Writer only, class SwView
  77     SwChildWindowLabel      = 0x0001,
  78     // Basic only, class Shell
  79     BasicShowBrowser        = 0x0004,
  80     // Forms only, class FmFormShell
  81     FormShowDatabaseBar     = 0x0008,
  82     FormShowField           = 0x0010,
  83     FormShowProperties      = 0x0020,
  84     FormShowExplorer        = 0x0040,
  85     FormShowFilterBar       = 0x0080,
  86     FormShowFilterNavigator = 0x0100,
  87     FormShowTextControlBar  = 0x0200,
  88     FormTBControls          = 0x0400,
  89     FormTBDesign            = 0x1000,
  90     FormShowDataNavigator   = 0x2000,
  91     // masks to make sure modules don't use flags from another
  92     SwMask                  = 0x0001,
  93     BasicMask               = 0x0004,
  94     FormMask                = 0x3ff8
  95 };
  96 namespace o3tl
  97 {
  98     template<> struct typed_flags<SfxShellFeature> : is_typed_flags<SfxShellFeature, 0x37fd> {};
  99 }
 100
 101 /* Flags that are being used in the slot definitions for the disable-features */
 102 enum class SfxDisableFlags {
 103     NONE,
 104     SwOnProtectedCursor = 0x0001,
 105     SwOnMailboxEditor   = 0x0002,
 106 };
 107 namespace o3tl {
 108     template<> struct typed_flags<SfxDisableFlags> : is_typed_flags<SfxDisableFlags, 0x0003> {};
 109 }
 110
 111 typedef void (*SfxExecFunc)(SfxShell *, SfxRequest &rReq);
 112 typedef void (*SfxStateFunc)(SfxShell *, SfxItemSet &rSet);
 113
 114 /**
 115     The class SfxShell is the base class for all classes, which provide
 116     the functionality of the form <Slot>s.
 117
 118     Each instance has a reference to an interface description, which is
 119     obtainable through <SfxShell::GetInterface()const>. This interface
 120     provides the connection to specific methods and contains some other
 121     descriptive data for controllers like menus and toolboxes, but also
 122     for the various APIs. The main part of the interface description is in
 123     the form of a <Type-Library>, which is generated from an IDL-file by
 124     the <SVIDL-Compiler>. For each SfxShell Subclass-File there is one
 125     such IDL-file to write.
 126 */
 127 class SFX2_DLLPUBLIC SfxShell: public SfxBroadcaster
 128 {
 129     friend class SfxObjectItem;
 130
 131     std::unique_ptr< SfxShell_Impl >              pImpl;
 132     SfxItemPool*                pPool;
 133     SfxUndoManager*             pUndoMgr;
 134
 135 private:
 136                                 SfxShell( const SfxShell & ) = delete;
 137     SfxShell&                                   operator = ( const SfxShell & ) = delete;
 138
 139 protected:
 140     /**
 141         The constructor of the SfxShell class initializes only simple types,
 142         the corresponding SbxObject is only created on-demand. Therefore,
 143         the application of a SfxShell instance is very cheap.
 144         */
 145     SfxShell();
 146
 147     /**
 148         The constructor of the SfxShell class initializes only simple types,
 149         the corresponding SbxObject is only created on-demand. Therefore,
 150         the application of a SfxShell instance is very cheap.
 151         */
 152     SfxShell( SfxViewShell *pViewSh );
 153
 154     void SetViewShell_Impl( SfxViewShell* pView );
 155     SAL_DLLPRIVATE void Invalidate_Impl( SfxBindings& rBindings, sal_uInt16 nId );
 156     static void HandleOpenXmlFilterSettings(SfxRequest &);
 157
 158 public:
 159
 160     /**
 161         The connection to a possible corresponding SbxObject is dissolved.
 162         The SbxObject may continue to exist, but can not any longer perform
 163         any functions and can not provide any properties.
 164         */
 165     virtual                     ~SfxShell() override;
 166
 167     /**
 168         With this virtual method, which is automatically overridden by each subclass
 169         with its own slots through the macro <SFX_DECL_INTERFACE>, one can access
 170         each of the <SfxInterface> instance belonging to the subclass.
 171
 172         The class SfxShell itself has no own SfxInterface (no slots), therefore a
 173         NULL-pointer is returned.
 174         */
 175     virtual SfxInterface*       GetInterface() const;
 176     static SfxInterface*        GetStaticInterface() { return nullptr; }
 177
 178     /**
 179         Sets the name of the Shell object. With this name, the SfxShell instance
 180         of BASIC can be expressed.
 181         */
 182     void                        SetName( const OUString &rName );
 183
 184     /**
 185         Returns the name of the Shell object. With this name, the SfxShell instance
 186         of BASIC can be expressed.
 187         */
 188     const OUString&             GetName() const;
 189
 190     /**
 191         Returns the SfxViewShell in which they are located in the subshells.
 192         Otherwise, and if not specified by the App developer, this method
 193         returns NULL.
 194         */
 195     SfxViewShell*               GetViewShell() const;
 196
 197     static void                 EmptyExecStub(SfxShell *pShell, SfxRequest &);
 198     static void                 EmptyStateStub(SfxShell *pShell, SfxItemSet &);
 199
 200     /**
 201         This method returns the status of the slot with the specified slot ID
 202         on the specified interface.
 203
 204         If the slot is disabled or in this SfxShell (and their parent shells) are
 205         not known, a Null-pointer is returned.
 206
 207         If the slot does not have a Status, a SfxVoidItem is returned.
 208
 209         The status is set directly in this Set when pStateSet != 0 , so that
 210         overridden Slots of the <SfxShell> Subclasses and also in the Status
 211         method of the base implementation can be called.
 212
 213         [Example]
 214
 215         In a derived class of SfxViewShell the SID_PRINTDOCDIRECT will be
 216         intercepted. Under certain circumstances a query should appear before
 217         you print, and the request will be aborted if necessary.
 218
 219         Also in the IDL of this subclass of the above slot is entered. The status
 220         method will contain in outline:
 221
 222         void SubViewShell::PrintState( SfxItemSet &rState )
 223         {
 224         if ( rState.GetItemState( SID_PRINTDOCDIRECT ) != SfxItemState::UNKNOWN )
 225         GetSlotState( SID_PRINTDOCDIRECT, SfxViewShell::GetInterface(),
 226         &rState );
 227         ...
 228         }
 229
 230         [Cross-reference]
 231
 232         <SfxShell::ExecuteSlot(SfxRequest&)>
 233         */
 234     const SfxPoolItem*          GetSlotState( sal_uInt16 nSlotId, const SfxInterface *pIF = nullptr, SfxItemSet *pStateSet = nullptr );
 235
 236     /**
 237         This method allows you to forward a <SfxRequest> to the specified
 238         base <SfxShell>.
 239
 240         [Example]
 241
 242         In a derived class of SfxViewShell the SID_PRINTDOCDIRECT will be
 243         intercepted. Under certain circumstances a query should appear before
 244         you print, and the request will be aborted if necessary.
 245
 246         Also in the IDL of this subclass of the above slot is entered. The status
 247         method will contain in outline:
 248
 249         void SubViewShell::Exec( SfxRequest &rReq )
 250         {
 251         if ( rReq.GetSlot() == SID_PRINTDOCDIRECT )
 252         {
 253         'dialog'
 254         if ( 'condition' )
 255         ExecuteSlot( rReq, SfxViewShell::GetInterface() );
 256         }
 257         }
 258
 259         It usually takes no rReq.Done() to be called as that is already completed
 260         in implementation of the SfxViewShell, for instance it has been canceled.
 261
 262         [Cross-reference]
 263
 264         <SfxShell::GetSlotState(sal_uInt16,const SfxInterface*,SfxItemSet*)>
 265         */
 266     const SfxPoolItem*          ExecuteSlot( SfxRequest &rReq, const SfxInterface *pIF = nullptr );
 267
 268     /**
 269         Asynchronous ExecuteSlot for the RELOAD
 270         */
 271     void                        ExecuteSlot( SfxRequest &rReq, bool bAsync );
 272
 273     inline SfxItemPool&         GetPool() const;
 274     inline void                 SetPool( SfxItemPool *pNewPool ) ;
 275
 276     /**
 277         Each Subclass of SfxShell can have a <SfxUndoManager>. This can be set in
 278         the derived class with <SfxShell:SetUndoManager()>.
 279
 280         The class SfxShell itself does not have a SfxUndoManager, a NULL-pointer
 281         is therefore returned.
 282         */
 283     virtual SfxUndoManager*     GetUndoManager();
 284
 285     /**
 286         Sets a <SfxUndoManager> for this <SfxShell> Instance. For the undo
 287         is only the undo-manager used for SfxShell at the top of the stack of each
 288         <SfxDispatcher>.
 289
 290         On the given <SfxUndoManager> is automatically the current
 291         Max-Undo-Action-Count setting set from the options.
 292
 293         'pNewUndoMgr' must exist until the Destructor of SfxShell instance is called
 294         or until the next 'SetUndoManager()'.
 295         */
 296     void                        SetUndoManager( SfxUndoManager *pNewUndoMgr );
 297
 298     /**
 299         Returns a pointer to the <SfxRepeatTarget> instance that is used in
 300         SID_REPEAT as repeat target when it is addressed from the <SfxUndoManager>
 301         supplied by this SfxShell. The return value can be NULL.
 302
 303         [Note]
 304
 305         A derivation of <SfxShell> or one of its subclasses of <SfxRepeatTarget>
 306         is not recommended, as compiler errors are provoked.
 307         (due to Call-to-Pointer-to-Member-Function to the subclass).
 308         */
 309     SfxRepeatTarget*            GetRepeatTarget() const;
 310
 311     /**
 312         Sets the <SfxRepeatTarget> instance that is used in SID_REPEAT as
 313         RepeatTarget, when the current supplied by this <SfxUndoManager> is
 314         addressed. By 'pTarget==0' the SID_REPEAT is disabled for this SfxShell.
 315         The instance '*pTarget' must live as long as it is registered.
 316
 317         [Note]
 318
 319         A derivation of <SfxShell> or one of its subclasses of <SfxRepeatTarget>
 320         is not recommended, as compiler errors are provoked.
 321         (due to Call-to-Pointer-to-Member-Function to the subclass).
 322         */
 323     void                        SetRepeatTarget( SfxRepeatTarget *pTarget );
 324
 325     /**
 326         With this method can the slots of the subclasses be invalidated through the
 327         slot Id or alternatively through the Which ID. Slot IDs, which are
 328         inherited by the subclass are also invalidated.
 329
 330         [Cross-reference]
 331
 332         <SfxBindings::Invalidate(sal_uInt16)>
 333         <SfxBindings::InvalidateAll(sal_Bool)>
 334         */
 335     virtual void                Invalidate(sal_uInt16 nId = 0);
 336
 337     virtual bool                IsDesignMode() const { return false; };
 338
 339     bool                        IsActive() const;
 340
 341     /**
 342         Virtual method that is called when enabling the SfxShell instance,
 343         in order to give the Subclasses the opportunity to respond to the
 344         to the enabling.
 345
 346         [Cross-reference]
 347
 348         StarView SystemWindow::Activate(bool)
 349         */
 350     virtual void                Activate(bool bMDI);
 351
 352     /**
 353         Virtual method that is called when disabling the SfxShell instance,
 354         to give the Subclasses the opportunity to respond to the disabling.
 355
 356         [Cross-reference]
 357
 358         StarView SystemWindow::Deactivate(bool)
 359         */
 360     virtual void                Deactivate(bool bMDI);
 361
 362     /**
 363         This method returns a pointer to the <SfxDispatcher>, when the SfxShell
 364         is currently <UI-active> or a NULL-pointer if it is not UI-active.
 365
 366         The returned pointer is only valid in the immediate context of the method
 367         call.
 368         */
 369     SfxDispatcher*              GetDispatcher() const;
 370
 371     /**
 372         This method returns a pointer to the <SfxViewFrame> to which this SfxShell
 373         instance is associated or in which they currently is <UI-active>.
 374         A NULL pointer is returned if this SfxShell instance is not UI-active at
 375         the moment and also no SfxViewFrame is permanently assigned.
 376
 377         The returned pointer is only valid in the immediate context of the method
 378         call.
 379
 380         [Note]
 381
 382         Only instances of a subclass of SfxApplication and SfxObjectShell
 383         should here provide a NULL-pointer. Otherwise, there is an error in the
 384         application program (wrong constructor was called from SfxShell).
 385
 386         [Cross-reference]
 387
 388         <SfxViewShell::GetViewFrame()const>
 389         */
 390     SfxViewFrame*               GetFrame() const;
 391
 392     virtual bool                HasUIFeature(SfxShellFeature nFeature) const;
 393     void                        UIFeatureChanged();
 394
 395     // Items
 396     /**
 397         With this method any objects of <SfxPoolItemu> subclasses can be accessed.
 398         This exchange method is needed if, for example special <SfxToolBoxControl>
 399         subclasses need access to certain data such as the <SfxObjectShell>.
 400
 401         The returned instance belongs to the particular SfxShell and may be
 402         used only in the immediate context of the method call.
 403
 404         [Cross-reference]
 405
 406         <SfxShell::PutItem(const SfxPoolItem&)>
 407         <SfxShell::RemoveItem(sal_uInt16)>
 408         */
 409     const SfxPoolItem*          GetItem( sal_uInt16 nSlotId ) const;
 410     template<class T> const T*  GetItem( TypedWhichId<T> nWhich ) const
 411     {
 412         return static_cast<const T*>(GetItem(sal_uInt16(nWhich)));
 413     }
 414
 415     /**
 416         With this method, any objects of subclasses of <SfxPoolItem> can be made
 417         available. This exchange technology is needed if, for example, special
 418         <SfxToolBoxControl> Subclasses need access to certain data such as the
 419         <SfxObjectShell>
 420
 421         If a SfxPoolItem exists with the same slot ID, it is deleted automatically.
 422
 423         [Cross-reference]
 424
 425         <SfxShell::RemoveItem(sal_uInt16)>
 426         <SfxShell::GetItem(sal_uInt16)>
 427         */
 428     void                        PutItem( const SfxPoolItem& rItem );
 429
 430     // TODO/CLEANUP: still needed?!
 431     void SetVerbs(const css::uno::Sequence < css::embed::VerbDescriptor >& aVerbs);
 432     const css::uno::Sequence < css::embed::VerbDescriptor >& GetVerbs() const;
 433     void                        VerbExec (SfxRequest&);
 434     static void                 VerbState (SfxItemSet&);
 435     SAL_DLLPRIVATE const SfxSlot* GetVerbSlot_Impl(sal_uInt16 nId) const;
 436
 437     virtual SfxObjectShell*     GetObjectShell();
 438     void                        SetDisableFlags( SfxDisableFlags nFlags );
 439     SfxDisableFlags             GetDisableFlags() const;
 440
 441     virtual std::optional<SfxItemSet> CreateItemSet( sal_uInt16 nId );
 442     virtual void                ApplyItemSet( sal_uInt16 nId, const SfxItemSet& rSet );
 443
 444     /** Set the name of the sidebar context that is broadcast on calls
 445         to Activation().
 446     */
 447     void SetContextName (const OUString& rsContextName);
 448
 449     /** Broadcast a sidebar context change.
 450         This method is typically called from Activate() or
 451         Deactivate().
 452         @param bIsActivated
 453             When <TRUE/> then broadcast the context name that was
 454             defined with an earlier call to SetContextName().
 455             When <FALSE/> then broadcast the 'default' context.
 456     */
 457     void BroadcastContextForActivation (const bool bIsActivated);
 458
 459     /** Enabled or disable the context broadcaster.  Returns the old state.
 460     */
 461     bool SetContextBroadcasterEnabled (const bool bIsEnabled);
 462
 463     /**
 464
 465         This method determines by calling the status function whether 'rSlot'
 466         can be executed currently.
 467         */
 468     SAL_DLLPRIVATE bool CanExecuteSlot_Impl( const SfxSlot &rSlot );
 469
 470     /**
 471
 472         This method determines whether we need to execute without checking
 473         the disabled state of the slot. This is used for dynamic conditions
 474         while you can use SfxSlotMode::FASTCALL for a specific slotid in general.
 475         */
 476     virtual bool IsConditionalFastCall( const SfxRequest &rReq );
 477
 478     /**
 479
 480         This method controls the activation of SfxShell instance. First, by calling
 481         the virtual method <SfxShell::Activate(sal_Bool)> which gives the subclass the
 482         opportunity to respond to the event.
 483
 484         When bMDI == TRUE, the associated SbxObject is being 'armed', so that
 485         unqualified methods of the object (without the name of the object)
 486         from BASIC are found.
 487         */
 488     SAL_DLLPRIVATE void DoActivate_Impl( SfxViewFrame *pFrame, bool bMDI);
 489
 490     /**
 491
 492         This method controls the deactivation of the SfxShell instance. When
 493         bMDI == TRUE the SbxObject is first set to a status that only qualified
 494         BASIC methods can be called.
 495
 496         Then the subclass gets the opportunity in every case to respond to the
 497         event by calling the virtual method <SfxShell::Deactivate(sal_Bool)>.
 498         */
 499     SAL_DLLPRIVATE void DoDeactivate_Impl( SfxViewFrame const *pFrame, bool bMDI);
 500 };
 501
 502 /**
 503     Each Subclass of SfxShell must reference a pool. This is partly set by
 504     SFx's own set of subclasses (eg <SfxViewShell>). In particular however
 505     this must be set directly from one derived SfxShell class and ny
 506     derivatives of SfxObjectShell.
 507
 508     The SfxShell class itself does not have any SfxItemPool, therefore a
 509     null-pointer is returned.
 510 */
 511 SfxItemPool& SfxShell::GetPool() const
 512 {
 513     assert(pPool && "no pool");
 514     return *pPool;
 515 }
 516
 517 /**
 518     With this method, the subclasses register their special <SfxItemPool>
 519     in the SfxShell. Each SfxShell instance must have access to a SfxItemPool.
 520     Usually this is the SfxItemPool of the SfxDocumentShell. The SfxShell
 521     subclass does not take ownership of the orphaned pool. Before it is
 522     deleted it has to be deregistered with SetPool(0).
 523 */
 524 inline void SfxShell::SetPool
 525 (
 526     SfxItemPool*        pNewPool        // Pointer to the new Pool or null
 527 )
 528 {
 529     pPool = pNewPool;
 530 }
 531
 532 #define SFX_DECL_INTERFACE(nId)                                  \
 533             static SfxInterface*     s_pInterface;                 \
 534             static SfxInterface*     GetStaticInterface();       \
 535             static SfxInterfaceId    GetInterfaceId() {return nId;} \
 536             static void              RegisterInterface(const SfxModule* pMod=nullptr); \
 537             virtual SfxInterface*    GetInterface() const override;
 538
 539 #define SFX_TMPL_INTERFACE(Class,SuperClass,Abstract)                       \
 540                                                                             \
 541     SfxInterface* Class::s_pInterface = nullptr;                              \
 542     SfxInterface* Class::GetStaticInterface()                               \
 543     {                                                                       \
 544         if ( !s_pInterface )                                                  \
 545         {                                                                   \
 546             s_pInterface =                                                    \
 547                 new SfxInterface(                                           \
 548             #Class, Abstract, GetInterfaceId(),                             \
 549             SuperClass::GetStaticInterface(),                               \
 550             a##Class##Slots_Impl[0],                                        \
 551             sal_uInt16(sizeof(a##Class##Slots_Impl) / sizeof(SfxSlot) ) );   \
 552             InitInterface_Impl();                                           \
 553         }                                                                   \
 554         return s_pInterface;                                                  \
 555     }                                                                       \
 556                                                                             \
 557     SfxInterface* Class::GetInterface() const                               \
 558     {                                                                       \
 559         return GetStaticInterface();                                        \
 560     }                                                                       \
 561                                                                             \
 562     void Class::RegisterInterface(const SfxModule* pMod)                    \
 563     {                                                                       \
 564         GetStaticInterface()->Register(pMod);                               \
 565     }
 566
 567 #define SFX_IMPL_INTERFACE(Class,SuperClass)                                \
 568 SFX_TMPL_INTERFACE(Class,SuperClass,false)                                  \
 569
 570 #define SFX_IMPL_SUPERCLASS_INTERFACE(Class,SuperClass)                     \
 571 SFX_TMPL_INTERFACE(Class,SuperClass,true)                                   \
 572
 573 enum class SfxVisibilityFlags {
 574     Invisible        = 0x0000, // Never visible
 575     Viewer           = 0x0040,
 576     ReadonlyDoc      = 0x0400,
 577     Standard         = 0x1000,
 578     FullScreen       = 0x2000,
 579     Client           = 0x4000,
 580     Server           = 0x8000,
 581 };
 582 namespace o3tl {
 583     template<> struct typed_flags<SfxVisibilityFlags> : is_typed_flags<SfxVisibilityFlags, 0xf440> {};
 584 }
 585 #endif
 586
 587 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */