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