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 normaly 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 throw(css::uno::RuntimeException); 96 virtual void SAL_CALL addStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener, 97 const css::util::URL& aURL ) 98 throw(css::uno::RuntimeException); 99 virtual void SAL_CALL removeStatusListener(const css::uno::Reference< css::frame::XStatusListener >& xListener, 100 const css::util::URL& aURL ) 101 throw(css::uno::RuntimeException); 102 103 // css::awt::XWindowListener 104 virtual void SAL_CALL windowResized(const css::awt::WindowEvent& aSource) 105 throw(css::uno::RuntimeException); 106 virtual void SAL_CALL windowMoved(const css::awt::WindowEvent& aSource) 107 throw(css::uno::RuntimeException); 108 virtual void SAL_CALL windowShown(const css::lang::EventObject& aSource) 109 throw(css::uno::RuntimeException); 110 virtual void SAL_CALL windowHidden(const css::lang::EventObject& aSource) 111 throw(css::uno::RuntimeException); 112 113 // css::lang::XEventListener 114 virtual void SAL_CALL disposing(const css::lang::EventObject& aSource) 115 throw(css::uno::RuntimeException); 116 117 protected: 118 119 ~HelpAgentDispatcher(); 120 121 protected: 122 123 /// IHelpAgentCallback overridables 124 virtual void helpRequested(); 125 virtual void closeAgent(); 126 127 private: 128 129 //--------------------------------------- 130 /** @short mark the current set URL as "accepted by user" and show the right help window 131 */ 132 void implts_acceptCurrentURL(); 133 134 //--------------------------------------- 135 /** @short mark the current set URL as "ignored by user" 136 */ 137 void implts_ignoreCurrentURL(); 138 139 //--------------------------------------- 140 /** @short ensures that the agent's window exists 141 @descr We create the agent window on demand. But afterwards we hold it alive till 142 this helpagent dispatcher dies. The agent window will be made visible/hidden 143 in case a new dispatch occurs or in case the timer expired. 144 145 @return [sal_Bool] 146 sal_True in case the member m_xAgentWindow is a valid reference; 147 sal_False otherwise. 148 */ 149 css::uno::Reference< css::awt::XWindow > implts_ensureAgentWindow(); 150 151 //--------------------------------------- 152 /** @short show the agent window. 153 @descr If the agent window does not exists, it will be created on demand. 154 (see implts_ensureAgentWindow). Further it's checked if the parent container 155 window is currently visible or not. Only if its visible the agent window will 156 be shown too. 157 */ 158 void implts_showAgentWindow(); 159 160 //--------------------------------------- 161 /** @short hide the agent window. 162 */ 163 void implts_hideAgentWindow(); 164 165 //--------------------------------------- 166 /** @short set the new position and size of the agent window. 167 @descr If the agent window does not exists, it will be created on demand. 168 (see implts_ensureAgentWindow). 169 If the agent window exists, its position and size will be calculated 170 and set. 171 */ 172 void implts_positionAgentWindow(); 173 174 //--------------------------------------- 175 /** @short starts the timer for showing the agent window. 176 @descr The timer wont be started twice ... this method checks the current running state .-) 177 */ 178 void implts_startTimer(); 179 180 //--------------------------------------- 181 /** @short stop the timer. 182 @descr The timer wont be stopped twice ... this method checks the current running state .-) 183 Further this method marks the current help URL (m_xCurrentURL) as "ignorable". 184 Cause the user ignored it ! 185 */ 186 void implts_stopTimer(); 187 188 //--------------------------------------- 189 /** @short callback of our internal timer. 190 */ 191 DECL_LINK(implts_timerExpired, void*); 192 }; 193 194 #undef css 195 196 //........................................................................ 197 } // namespace framework 198 //........................................................................ 199 200 #endif // _FRAMEWORK_DISPATCH_HELPAGENTDISPATCHER_HXX_ 201 202