framework/inc/dispatch/helpagentdispatcher.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: helpagentdispatcher.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_
  32 #define __FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_
  33
  34 #include <threadhelp/threadhelpbase.hxx>
  35 #include <macros/xinterface.hxx>
  36 #include <macros/xtypeprovider.hxx>
  37 #include <com/sun/star/frame/XDispatch.hpp>
  38 #include <com/sun/star/frame/XFrame.hpp>
  39 #include <com/sun/star/awt/XWindowListener.hpp>
  40 #include <com/sun/star/awt/XWindow.hpp>
  41 #include <svtools/helpagentwindow.hxx>
  42 #include <vcl/timer.hxx>
  43 #include <vcl/evntpost.hxx>
  44 #include <cppuhelper/weak.hxx>
  45
  46 //........................................................................
  47 namespace framework
  48 {
  49
  50 // define css alias ... and undefine it at the end of this file !!!
  51 #ifdef css
  52     #error "I tried to use css as namespace define inside non exported header ... but it was already defined by somwhere else. .-)"
  53 #else
  54     #define css ::com::sun::star
  55 #endif
  56
  57 //........................................................................
  58
  59 class HelpAgentDispatcher : public  css::lang::XTypeProvider
  60                           , public  css::frame::XDispatch
  61                           , public  css::awt::XWindowListener // => css::lang::XEventListener
  62                           , public  ::svt::IHelpAgentCallback
  63                           , private ThreadHelpBase
  64                           , public  ::cppu::OWeakObject
  65 {
  66     private:
  67
  68         //---------------------------------------
  69         /// @short  represent the current active help URL, which must be used to show the right help page
  70         ::rtl::OUString m_sCurrentURL;
  71
  72         //---------------------------------------
  73         /// @short  parent of the agent window.
  74         css::uno::Reference< css::awt::XWindow > m_xContainerWindow;
  75
  76         //---------------------------------------
  77         /// @short  the agent window itself (implemented in svtools)
  78         css::uno::Reference< css::awt::XWindow > m_xAgentWindow;
  79
  80         //---------------------------------------
  81         /// @short  the timer for showing the agent window
  82         Timer m_aTimer;
  83
  84         //---------------------------------------
  85         /** @short  hold this dispatcher alive till the timer was killed or expired!
  86             @descr      Because the vcl timer knows us by using a pointer ... and our instance is used
  87                     ref counted normaly it can happen that our reference goes down to 0 ... and the timer
  88                     runs into some trouble. So we hold us self alive till the timer could be stopped or expired.
  89         */
  90         css::uno::Reference< css::uno::XInterface > m_xSelfHold;
  91
  92     public:
  93
  94         HelpAgentDispatcher(const css::uno::Reference< css::frame::XFrame >& xParentFrame);
  95
  96         FWK_DECLARE_XINTERFACE
  97         FWK_DECLARE_XTYPEPROVIDER
  98
  99         // css::frame::XDispatch
 100         virtual void SAL_CALL dispatch(const css::util::URL&                                                              sURL ,
 101                                        const css::uno::Sequence< css::beans::PropertyValue >& lArgs)
 102             throw(css::uno::RuntimeException);
 103         virtual void SAL_CALL addStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener,
 104                                                 const css::util::URL&                                                                     aURL     )
 105             throw(css::uno::RuntimeException);
 106         virtual void SAL_CALL removeStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener,
 107                                                    const css::util::URL&                                                                         aURL     )
 108             throw(css::uno::RuntimeException);
 109
 110         // css::awt::XWindowListener
 111         virtual void SAL_CALL windowResized(const css::awt::WindowEvent& aSource)
 112             throw(css::uno::RuntimeException);
 113         virtual void SAL_CALL windowMoved(const css::awt::WindowEvent& aSource)
 114             throw(css::uno::RuntimeException);
 115         virtual void SAL_CALL windowShown(const css::lang::EventObject& aSource)
 116             throw(css::uno::RuntimeException);
 117         virtual void SAL_CALL windowHidden(const css::lang::EventObject& aSource)
 118             throw(css::uno::RuntimeException);
 119
 120         // css::lang::XEventListener
 121         virtual void SAL_CALL disposing(const css::lang::EventObject& aSource)
 122             throw(css::uno::RuntimeException);
 123
 124     protected:
 125
 126         ~HelpAgentDispatcher();
 127
 128     protected:
 129
 130         /// IHelpAgentCallback overridables
 131         virtual void helpRequested();
 132         virtual void closeAgent();
 133
 134     private:
 135
 136         //---------------------------------------
 137         /** @short  mark the current set URL as "accepted by user" and show the right help window
 138          */
 139         void implts_acceptCurrentURL();
 140
 141         //---------------------------------------
 142         /** @short  mark the current set URL as "ignored by user"
 143          */
 144         void implts_ignoreCurrentURL();
 145
 146         //---------------------------------------
 147         /** @short      ensures that the agent's window exists
 148             @descr      We create the agent window on demand. But afterwards we hold it alive till
 149                     this helpagent dispatcher dies. The agent window will be made visible/hidden
 150                     in case a new dispatch occures or in case the timer expired.
 151
 152             @return     [sal_Bool]
 153                     TRUE in case the member m_xAgentWindow is a valid reference;
 154                     FALSE otherwise.
 155         */
 156         css::uno::Reference< css::awt::XWindow > implts_ensureAgentWindow();
 157
 158         //---------------------------------------
 159         /** @short  show the agent window.
 160             @descr      If the agent window does not exists, it will be created on demand.
 161                     (see implts_ensureAgentWindow). Further it's checked if the parent container
 162                     window is currently visible or not. Only if its visible the agent window will
 163                     be shown too.
 164          */
 165         void implts_showAgentWindow();
 166
 167         //---------------------------------------
 168         /** @short  hide the agent window.
 169          */
 170         void implts_hideAgentWindow();
 171
 172         //---------------------------------------
 173         /** @short  set the new position and size of the agent window.
 174             @descr      If the agent window does not exists, it will be created on demand.
 175                     (see implts_ensureAgentWindow).
 176                     If the agent window exists, its position and size will be calculated
 177                     and set.
 178          */
 179         void implts_positionAgentWindow();
 180
 181         //---------------------------------------
 182         /** @short  starts the timer for showing the agent window.
 183             @descr      The timer wont be started twice ... this method checks the current running state .-)
 184          */
 185         void implts_startTimer();
 186
 187         //---------------------------------------
 188         /** @short  stop the timer.
 189             @descr      The timer wont be stopped twice ... this method checks the current running state .-)
 190                     Further this method marks the current help URL (m_xCurrentURL) as "ignorable".
 191                     Cause the user ignored it !
 192          */
 193         void implts_stopTimer();
 194
 195         //---------------------------------------
 196         /** @short  callback of our internal timer.
 197          */
 198         DECL_LINK(implts_timerExpired, void*);
 199 };
 200
 201 #undef css
 202
 203 //........................................................................
 204 }       // namespace framework
 205 //........................................................................
 206
 207 #endif // _FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_
 208