Version 5.2.6.1, tag libreoffice-5.2.6.1
[LibreOffice.git] / include / sfx2 / shell.hxx
blob58440b2fdb559e36869645fbb8d45a03bb359911
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
19 #ifndef INCLUDED_SFX2_SHELL_HXX
20 #define INCLUDED_SFX2_SHELL_HXX
22 #include <com/sun/star/embed/VerbDescriptor.hpp>
23 #include <rtl/ustring.hxx>
24 #include <sal/config.h>
25 #include <sal/types.h>
26 #include <sfx2/dllapi.h>
27 #include <sfx2/sfxuno.hxx>
28 #include <svl/SfxBroadcaster.hxx>
30 class ResMgr;
31 namespace vcl { class Window; }
32 class ToolBox;
33 class SfxItemPool;
34 class SfxPoolItem;
35 class SfxRequest;
36 class SfxItemSet;
37 struct SfxFormalArgument;
38 class StatusBar;
39 class SfxInterface;
40 class SfxViewShell;
41 class SfxObjectShell;
42 class SfxSlotPool;
43 class SvGlobalName;
45 class SfxShellObject;
46 class SfxShell;
47 struct SfxShell_Impl;
48 class SfxShellObject;
49 class SfxDispatcher;
50 class SfxViewFrame;
51 class SfxSlot;
52 class SfxRepeatTarget;
53 class SbxVariable;
54 class SbxBase;
55 class SfxBindings;
57 namespace svl
59 class IUndoManager;
62 /**
63 Id for <SfxInterface>s, gives a quasi-static access to the interface
64 through an array to <SfxApplication>.
66 enum SfxInterfaceId
68 SFX_INTERFACE_NONE,
69 SFX_INTERFACE_SFXAPP,
70 SFX_INTERFACE_SFXDOCSH,
71 SFX_INTERFACE_SFXIPFRM,
72 SFX_INTERFACE_SFXVIEWSH,
73 SFX_INTERFACE_SFXVIEWFRM,
74 SFX_INTERFACE_SFXPLUGINFRM,
75 SFX_INTERFACE_SFXPLUGINOBJ,
76 SFX_INTERFACE_SFXPLUGINVIEWSH,
77 SFX_INTERFACE_SFXFRAMESETOBJ,
78 SFX_INTERFACE_SFXFRAMESETVIEWSH,
79 SFX_INTERFACE_SFXINTERNALFRM,
80 SFX_INTERFACE_SFXCOMPONENTDOCSH,
81 SFX_INTERFACE_SFXGENERICOBJ,
82 SFX_INTERFACE_SFXGENERICVIEWSH,
83 SFX_INTERFACE_SFXEXPLOBJ,
84 SFX_INTERFACE_SFXEXPLVIEWSH,
85 SFX_INTERFACE_SFXPLUGINVIEWSHDYNAMIC,
86 SFX_INTERFACE_SFXEXTERNALVIEWFRM,
87 SFX_INTERFACE_SFXMODULE,
88 SFX_INTERFACE_SFXFRAMESETVIEW,
89 SFX_INTERFACE_SFXFRAMESETSOURCEVIEW,
90 SFX_INTERFACE_SFXHELP_DOCSH,
91 SFX_INTERFACE_SFXHELP_VIEWSH,
92 SFX_INTERFACE_SFXTASK,
93 SFX_INTERFACE_OFA_START = 100,
94 SFX_INTERFACE_OFA_END = 100,
95 SFX_INTERFACE_SC_START = 150,
96 SFX_INTERFACE_SC_END = 199,
97 SFX_INTERFACE_SD_START = 200,
98 SFX_INTERFACE_SD_END = 249,
99 SFX_INTERFACE_SW_START = 250,
100 SFX_INTERFACE_SW_END = 299,
101 SFX_INTERFACE_SIM_START = 300,
102 SFX_INTERFACE_SIM_END = 319,
103 SFX_INTERFACE_SCH_START = 320,
104 SFX_INTERFACE_SCH_END = 339,
105 SFX_INTERFACE_SMA_START = 340,
106 SFX_INTERFACE_SMA_END = 359,
107 SFX_INTERFACE_SBA_START = 360,
108 SFX_INTERFACE_SBA_END = 399,
109 SFX_INTERFACE_IDE_START = 400,
110 SFX_INTERFACE_IDE_END = 409,
111 //-if one is still needed
112 SFX_INTERFACE_APP = SFX_INTERFACE_SW_START,
113 SFX_INTERFACE_LIB = 450
117 typedef void (*SfxExecFunc)(SfxShell *, SfxRequest &rReq);
118 typedef void (*SfxStateFunc)(SfxShell *, SfxItemSet &rSet);
121 The class SfxShell is the base class for all classes, which provide
122 the functionality of the form <Slot>s.
124 Each instance has a reference to an interface description, which is
125 obtainable through <SfxShell::GetInterface()const>. This interface
126 provides the connection to specific methods and contains some other
127 descriptive data for controllers like menus and toolboxes, but also
128 for the various APIs. The main part of the interface description is in
129 the form of a <Type-Library>, which is generated from an IDL-file by
130 the <SVIDL-Compiler>. For each SfxShell Subclass-File there is one
131 such IDL-file to write.
133 class SFX2_DLLPUBLIC SfxShell: public SfxBroadcaster
135 friend class SfxObjectItem;
137 std::unique_ptr< SfxShell_Impl > pImpl;
138 SfxItemPool* pPool;
139 ::svl::IUndoManager* pUndoMgr;
141 private:
142 SfxShell( const SfxShell & ) = delete;
143 SfxShell& operator = ( const SfxShell & ) = delete;
145 protected:
147 The constructor of the SfxShell class initializes only simple types,
148 the corresponding SbxObject is only created on-demand. Therefore,
149 the application of a SfxShell instance is very cheap.
151 SfxShell();
154 The constructor of the SfxShell class initializes only simple types,
155 the corresponding SbxObject is only created on-demand. Therefore,
156 the application of a SfxShell instance is very cheap.
158 SfxShell( SfxViewShell *pViewSh );
160 void SetViewShell_Impl( SfxViewShell* pView );
161 SAL_DLLPRIVATE void Invalidate_Impl( SfxBindings& rBindings, sal_uInt16 nId );
162 static void HandleOpenXmlFilterSettings(SfxRequest &);
164 public:
167 The connection to a possible corresponding SbxObject is dissolved.
168 The SbxObject may continue to exist, but can not any longer perform
169 any functions and can not provide any properties.
171 virtual ~SfxShell();
174 With this virtual method, which is automatically overridden by each subclass
175 with its own slots through the macro <SFX_DECL_INTERFACE>, one can access
176 each of the <SfxInterface> instance belonging to the subclass.
178 The class SfxShell itself has no own SfxInterface (no slots), therefore a
179 NULL-pointer is returned.
181 virtual SfxInterface* GetInterface() const;
182 static SfxInterface* GetStaticInterface() { return nullptr; }
185 Sets the name of the Shell object. With this name, the SfxShell instance
186 of BASIC can be expressed.
188 void SetName( const OUString &rName );
191 Returns the name of the Shell object. With this name, the SfxShell instance
192 of BASIC can be expressed.
194 const OUString& GetName() const;
197 Returns the SfxViewShell in which they are located in the subshells.
198 Otherwise, and if not specified by the App developer, this method
199 returns NULL.
201 SfxViewShell* GetViewShell() const;
203 void CallExec( SfxExecFunc pFunc, SfxRequest &rReq )
204 { (*pFunc)(this, rReq); }
205 void CallState( SfxStateFunc pFunc, SfxItemSet &rSet )
206 { (*pFunc)(this, rSet); }
208 static void EmptyExecStub(SfxShell *pShell, SfxRequest &);
209 static void EmptyStateStub(SfxShell *pShell, SfxItemSet &);
212 This method returns the status of the slot with the specified slot ID
213 on the specified interface.
215 If the slot is disabled or in this SfxShell (and their parent shells) are
216 not known, a Null-pointer is returned.
218 If the slot does not have a Status, a SfxVoidItem is returned.
220 The status is set directly in this Set when pStateSet != 0 , so that
221 overridden Slots of the <SfxShell> Subclasses and also in the Status
222 method of the base implementation can be called.
224 [Example]
226 In a derived class of SfxViewShell the SID_PRINTDOCDIRECT will be
227 intercepted. Under certain circumstances a query should appear before
228 you print, and the request will be aborted if necessary.
230 Also in the IDL of this subclass of the above slot is entered. The status
231 method will contain in outline:
233 void SubViewShell::PrintState( SfxItemSet &rState )
235 if ( rState.GetItemState( SID_PRINTDOCDIRECT ) != SfxItemState::UNKNOWN )
236 GetSlotState( SID_PRINTDOCDIRECT, SfxViewShell::GetInterface(),
237 &rState );
241 [Cross-reference]
243 <SfxShell::ExecuteSlot(SfxRequest&)>
245 const SfxPoolItem* GetSlotState( sal_uInt16 nSlotId, const SfxInterface *pIF = nullptr, SfxItemSet *pStateSet = nullptr );
248 This method allows you to forward a <SfxRequest> to the specified
249 base <SfxShell>.
251 [Example]
253 In a derived class of SfxViewShell the SID_PRINTDOCDIRECT will be
254 intercepted. Under certain circumstances a query should appear before
255 you print, and the request will be aborted if necessary.
257 Also in the IDL of this subclass of the above slot is entered. The status
258 method will contain in outline:
260 void SubViewShell::Exec( SfxRequest &rReq )
262 if ( rReq.GetSlot() == SID_PRINTDOCDIRECT )
264 'dialog'
265 if ( 'condition' )
266 ExecuteSlot( rReq, SfxViewShell::GetInterface() );
270 It usually takes no rReq.Done() to be called as that is already completed
271 in implementation of the SfxViewShell, for instance it has been canceled.
273 [Cross-reference]
275 <SfxShell::GetSlotState(sal_uInt16,const SfxInterface*,SfxItemSet*)>
277 const SfxPoolItem* ExecuteSlot( SfxRequest &rReq, const SfxInterface *pIF = nullptr );
280 Asynchronous ExecuteSlot for the RELOAD
282 void ExecuteSlot( SfxRequest &rReq, bool bAsync );
284 inline SfxItemPool& GetPool() const;
285 inline void SetPool( SfxItemPool *pNewPool ) ;
288 Each Subclass of SfxShell can have a <SfxUndoManager>. This can be set in
289 the derived class with <SfxShell:SetUndoManager()>.
291 The class SfxShell itself does not have a SfxUndoManager, a NULL-pointer
292 is therefore returned.
294 virtual ::svl::IUndoManager* GetUndoManager();
297 Sets a <SfxUndoManager> for this <SfxShell> Instance. For the undo
298 is only the undo-manager used for SfxShell at the top of the stack of each
299 <SfxDispatcher>.
301 On the given <SfxUndoManager> is automatically the current
302 Max-Undo-Action-Count setting set form the options.
304 'pNewUndoMgr' must exist until the Destuctor of SfxShell instance is called
305 or until the next 'SetUndoManager()'.
307 void SetUndoManager( ::svl::IUndoManager *pNewUndoMgr );
310 Returns a pointer to the <SfxRepeatTarget> instance that is used in
311 SID_REPEAT as repeat target when it is addressed from the <SfxUndoManager>
312 supplied by this SfxShell. The return value can be NULL.
314 [Note]
316 A derivation of <SfxShell> or one of its subclasses of <SfxRepeatTarget>
317 is not recommended, as compiler errors are provoked.
318 (due to Call-to-Pointer-to-Member-Function to the subclass).
320 SfxRepeatTarget* GetRepeatTarget() const;
323 Sets the <SfxRepeatTarget> instance that is used in SID_REPEAT as
324 RepeatTarget, when the current supplied by this <SfxUndoManager> is
325 addressed. By 'pTarget==0' the SID_REPEAT is disabled for this SfxShell.
326 The instance '*pTarget' must live as long as it is registered.
328 [Note]
330 A derivation of <SfxShell> or one of its subclasses of <SfxRepeatTarget>
331 is not recommended, as compiler errors are provoked.
332 (due to Call-to-Pointer-to-Member-Function to the subclass).
334 void SetRepeatTarget( SfxRepeatTarget *pTarget );
337 With this method can the slots of the subclasses be invalidated through the
338 slot Id or alternatively through the Which ID. Slot IDs, which are
339 inherited by the subclass are also invalidert.
341 [Cross-reference]
343 <SfxBindings::Invalidate(sal_uInt16)>
344 <SfxBindings::InvalidateAll(sal_Bool)>
346 virtual void Invalidate(sal_uInt16 nId = 0);
348 virtual bool IsDesignMode() const { return false; };
350 bool IsActive() const;
353 Virtual method that is called when enabling the SfxShell instance,
354 in order to give the Subclasses the opportunity to respond to the
355 to the enabling.
357 [Cross-reference]
359 StarView SystemWindow::Activate(bool)
361 virtual void Activate(bool bMDI);
364 Virtual method that is called when disabling the SfxShell instance,
365 to give the Subclasses the opportunity to respond to the disabling.
367 [Cross-reference]
369 StarView SystemWindow::Deactivate(bool)
371 virtual void Deactivate(bool bMDI);
374 This method returns a pointer to the <SfxDispatcher>, when the SfxShell
375 is currently <UI-active> or a NULL-pointer if it is not UI-active.
377 The returned pointer is only valid in the immediate context of the method
378 call.
380 SfxDispatcher* GetDispatcher() const;
383 This method returns a pointer to the <SfxViewFrame> to which this SfxShell
384 instance is associated or in which they currently is <UI-active>.
385 A NULL pointer is returned if this SfxShell instance is not UI-active at
386 the moment and also no SfxViewFrame is permanently assigned.
388 The returned pointer is only valid in the immediate context of the method
389 call.
391 [Note]
393 Only instances of a subclass of SfxApplication and SfxObjectShell
394 should here provide a NULL-pointer. Otherwise, there is an error in the
395 application program (wrong constructor was called from SfxShell).
397 [Cross-reference]
399 <SfxViewShell::GetViewFrame()const>
401 SfxViewFrame* GetFrame() const;
403 virtual bool HasUIFeature( sal_uInt32 nFeature );
404 void UIFeatureChanged();
406 // Items
408 With this method any objects of <SfxPoolItemu> subclasses can be accessed.
409 This exchange method is needed if, for example special <SfxToolBoxControl>
410 subclasses need access to certain data such as the <SfxObjectShell>.
412 The returned instance belongs to the particular SfxShell and may be
413 used only in the immediate context of the method call.
415 [Cross-reference]
417 <SfxShell::PutItem(const SfxPoolItem&)>
418 <SfxShell::RemoveItem(sal_uInt16)>
420 const SfxPoolItem* GetItem( sal_uInt16 nSlotId ) const;
423 With this method, any objects of subclasses of <SfxPoolItem> can be made
424 available. This exchange technology is needed if, for example, special
425 <SfxToolBoxControl> Subclasses need access to certain data such as the
426 <SfxObjectShell>
428 If a SfxPoolItem exists with the same slot ID, it is deleted automatically.
430 [Cross-reference]
432 <SfxShell::RemoveItem(sal_uInt16)>
433 <SfxShell::GetItem(sal_uInt16)>
435 void PutItem( const SfxPoolItem& rItem );
437 // TODO/CLEANUP: still needed?!
438 void SetVerbs(const css::uno::Sequence < css::embed::VerbDescriptor >& aVerbs);
439 const css::uno::Sequence < css::embed::VerbDescriptor >& GetVerbs() const;
440 void VerbExec (SfxRequest&);
441 static void VerbState (SfxItemSet&);
442 SAL_DLLPRIVATE const SfxSlot* GetVerbSlot_Impl(sal_uInt16 nId) const;
444 void SetHelpId(sal_uIntPtr nId);
445 sal_uIntPtr GetHelpId() const;
446 virtual SfxObjectShell* GetObjectShell();
447 void SetDisableFlags( sal_uIntPtr nFlags );
448 sal_uIntPtr GetDisableFlags() const;
450 virtual SfxItemSet* CreateItemSet( sal_uInt16 nId );
451 virtual void ApplyItemSet( sal_uInt16 nId, const SfxItemSet& rSet );
453 /** Set the name of the sidebar context that is broadcast on calls
454 to Activation().
456 void SetContextName (const ::rtl::OUString& rsContextName);
458 /** Broadcast a sidebar context change.
459 This method is typically called from Activate() or
460 Deactivate().
461 @param bIsActivated
462 When <TRUE/> then broadcast the context name that was
463 defined with an earlier call to SetContextName().
464 When <FALSE/> then broadcast the 'default' context.
466 void BroadcastContextForActivation (const bool bIsActivated);
468 /** Enabled or disable the context broadcaster. Returns the old state.
470 bool SetContextBroadcasterEnabled (const bool bIsEnabled);
474 This method determines by calling the status function whether 'rSlot'
475 can be executed currently.
477 SAL_DLLPRIVATE bool CanExecuteSlot_Impl( const SfxSlot &rSlot );
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.
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.
489 SAL_DLLPRIVATE void DoActivate_Impl( SfxViewFrame *pFrame, bool bMDI);
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.
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)>.
500 SAL_DLLPRIVATE void DoDeactivate_Impl( SfxViewFrame *pFrame, bool bMDI);
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.
509 The SfxShell class itself does not have any SfxItemPool, therefore a
510 null-pointer is returned.
512 SfxItemPool& SfxShell::GetPool() const
514 assert(pPool && "no pool");
515 return *pPool;
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).
525 inline void SfxShell::SetPool
527 SfxItemPool* pNewPool // Pointer to the new Pool or null
530 pPool = pNewPool;
533 #define SFX_DECL_INTERFACE(nId) \
534 static SfxInterface* pInterface; \
535 static SfxInterface* GetStaticInterface(); \
536 static SfxInterfaceId GetInterfaceId() {return SfxInterfaceId(nId);} \
537 static void RegisterInterface(SfxModule* pMod=nullptr); \
538 virtual SfxInterface* GetInterface() const override;
540 #define SFX_TMPL_INTERFACE(Class,SuperClass,Abstract) \
542 SfxInterface* Class::pInterface = nullptr; \
543 SfxInterface* Class::GetStaticInterface() \
545 if ( !pInterface ) \
547 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(); \
555 return pInterface; \
558 SfxInterface* Class::GetInterface() const \
560 return GetStaticInterface(); \
563 void Class::RegisterInterface(SfxModule* pMod) \
565 GetStaticInterface()->Register(pMod); \
568 #define SFX_IMPL_INTERFACE(Class,SuperClass) \
569 SFX_TMPL_INTERFACE(Class,SuperClass,false) \
571 #define SFX_IMPL_SUPERCLASS_INTERFACE(Class,SuperClass) \
572 SFX_TMPL_INTERFACE(Class,SuperClass,true) \
574 #define SFX_POSITION_MASK 0x000F
575 #define SFX_VISIBILITY_MASK 0xFFF0
576 #define SFX_VISIBILITY_UNVISIBLE 0x0000 // Never visible
577 #define SFX_VISIBILITY_VIEWER 0x0040
578 #define SFX_VISIBILITY_READONLYDOC 0x0400
579 #define SFX_VISIBILITY_DESKTOP 0x0800
580 #define SFX_VISIBILITY_STANDARD 0x1000
581 #define SFX_VISIBILITY_FULLSCREEN 0x2000
582 #define SFX_VISIBILITY_CLIENT 0x4000
583 #define SFX_VISIBILITY_SERVER 0x8000
585 #endif
587 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */