1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef __FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_ 25 #define __FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_ 26 27 #include <threadhelp/threadhelpbase.hxx> 28 #include <macros/xinterface.hxx> 29 #include <macros/xtypeprovider.hxx> 30 #include <com/sun/star/frame/XDispatch.hpp> 31 #include <com/sun/star/frame/XFrame.hpp> 32 #include <com/sun/star/awt/XWindowListener.hpp> 33 #include <com/sun/star/awt/XWindow.hpp> 34 #include <svtools/helpagentwindow.hxx> 35 #include <vcl/timer.hxx> 36 #include <vcl/evntpost.hxx> 37 #include <cppuhelper/weak.hxx> 38 39 //........................................................................ 40 namespace framework 41 { 42 43 // define css alias ... and undefine it at the end of this file !!! 44 #ifdef css 45 #error "I tried to use css as namespace define inside non exported header ... but it was already defined by somewhere else. .-)" 46 #else 47 #define css ::com::sun::star 48 #endif 49 50 //........................................................................ 51 52 class HelpAgentDispatcher : public css::lang::XTypeProvider 53 , public css::frame::XDispatch 54 , public css::awt::XWindowListener // => css::lang::XEventListener 55 , public ::svt::IHelpAgentCallback 56 , private ThreadHelpBase 57 , public ::cppu::OWeakObject 58 { 59 private: 60 61 //--------------------------------------- 62 /// @short represent the current active help URL, which must be used to show the right help page 63 ::rtl::OUString m_sCurrentURL; 64 65 //--------------------------------------- 66 /// @short parent of the agent window. 67 css::uno::Reference< css::awt::XWindow > m_xContainerWindow; 68 69 //--------------------------------------- 70 /// @short the agent window itself (implemented in svtools) 71 css::uno::Reference< css::awt::XWindow > m_xAgentWindow; 72 73 //--------------------------------------- 74 /// @short the timer for showing the agent window 75 Timer m_aTimer; 76 77 //--------------------------------------- 78 /** @short hold this dispatcher alive till the timer was killed or expired! 79 @descr Because the vcl timer knows us by using a pointer ... and our instance is used 80 ref counted normally it can happen that our reference goes down to 0 ... and the timer 81 runs into some trouble. So we hold us self alive till the timer could be stopped or expired. 82 */ 83 css::uno::Reference< css::uno::XInterface > m_xSelfHold; 84 85 public: 86 87 HelpAgentDispatcher(const css::uno::Reference< css::frame::XFrame >& xParentFrame); 88 89 FWK_DECLARE_XINTERFACE 90 FWK_DECLARE_XTYPEPROVIDER 91 92 // css::frame::XDispatch 93 virtual void SAL_CALL dispatch(const css::util::URL& sURL , 94 const css::uno::Sequence< css::beans::PropertyValue >& lArgs); 95 virtual void SAL_CALL addStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener, 96 const css::util::URL& aURL ); 97 virtual void SAL_CALL removeStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener, 98 const css::util::URL& aURL ); 99 100 // css::awt::XWindowListener 101 virtual void SAL_CALL windowResized(const css::awt::WindowEvent& aSource); 102 virtual void SAL_CALL windowMoved(const css::awt::WindowEvent& aSource); 103 virtual void SAL_CALL windowShown(const css::lang::EventObject& aSource); 104 virtual void SAL_CALL windowHidden(const css::lang::EventObject& aSource); 105 106 // css::lang::XEventListener 107 virtual void SAL_CALL disposing(const css::lang::EventObject& aSource); 108 109 protected: 110 111 ~HelpAgentDispatcher(); 112 113 protected: 114 115 /// IHelpAgentCallback overridables 116 virtual void helpRequested(); 117 virtual void closeAgent(); 118 119 private: 120 121 //--------------------------------------- 122 /** @short mark the current set URL as "accepted by user" and show the right help window 123 */ 124 void implts_acceptCurrentURL(); 125 126 //--------------------------------------- 127 /** @short mark the current set URL as "ignored by user" 128 */ 129 void implts_ignoreCurrentURL(); 130 131 //--------------------------------------- 132 /** @short ensures that the agent's window exists 133 @descr We create the agent window on demand. But afterwards we hold it alive till 134 this helpagent dispatcher dies. The agent window will be made visible/hidden 135 in case a new dispatch occurs or in case the timer expired. 136 137 @return [sal_Bool] 138 sal_True in case the member m_xAgentWindow is a valid reference; 139 sal_False otherwise. 140 */ 141 css::uno::Reference< css::awt::XWindow > implts_ensureAgentWindow(); 142 143 //--------------------------------------- 144 /** @short show the agent window. 145 @descr If the agent window does not exists, it will be created on demand. 146 (see implts_ensureAgentWindow). Further it's checked if the parent container 147 window is currently visible or not. Only if its visible the agent window will 148 be shown too. 149 */ 150 void implts_showAgentWindow(); 151 152 //--------------------------------------- 153 /** @short hide the agent window. 154 */ 155 void implts_hideAgentWindow(); 156 157 //--------------------------------------- 158 /** @short set the new position and size of the agent window. 159 @descr If the agent window does not exists, it will be created on demand. 160 (see implts_ensureAgentWindow). 161 If the agent window exists, its position and size will be calculated 162 and set. 163 */ 164 void implts_positionAgentWindow(); 165 166 //--------------------------------------- 167 /** @short starts the timer for showing the agent window. 168 @descr The timer won't be started twice ... this method checks the current running state .-) 169 */ 170 void implts_startTimer(); 171 172 //--------------------------------------- 173 /** @short stop the timer. 174 @descr The timer won't be stopped twice ... this method checks the current running state .-) 175 Further this method marks the current help URL (m_xCurrentURL) as "ignorable". 176 Cause the user ignored it ! 177 */ 178 void implts_stopTimer(); 179 180 //--------------------------------------- 181 /** @short callback of our internal timer. 182 */ 183 DECL_LINK(implts_timerExpired, void*); 184 }; 185 186 #undef css 187 188 //........................................................................ 189 } // namespace framework 190 //........................................................................ 191 192 #endif // _FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_ 193