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_HELPER_OFRAMES_HXX_ 25 #define __FRAMEWORK_HELPER_OFRAMES_HXX_ 26 27 //_________________________________________________________________________________________________________________ 28 // my own includes 29 //_________________________________________________________________________________________________________________ 30 31 #include <classes/framecontainer.hxx> 32 #include <threadhelp/threadhelpbase.hxx> 33 #include <macros/generic.hxx> 34 #include <macros/xinterface.hxx> 35 #include <macros/xtypeprovider.hxx> 36 #include <macros/debug.hxx> 37 #include <general.h> 38 39 //_________________________________________________________________________________________________________________ 40 // interface includes 41 //_________________________________________________________________________________________________________________ 42 #include <com/sun/star/lang/XMultiServiceFactory.hpp> 43 #include <com/sun/star/frame/XFrames.hpp> 44 #include <com/sun/star/frame/XFrame.hpp> 45 46 //_________________________________________________________________________________________________________________ 47 // other includes 48 //_________________________________________________________________________________________________________________ 49 #include <cppuhelper/implbase1.hxx> 50 #include <cppuhelper/weakref.hxx> 51 52 //_________________________________________________________________________________________________________________ 53 // namespace 54 //_________________________________________________________________________________________________________________ 55 56 namespace framework{ 57 58 //_________________________________________________________________________________________________________________ 59 // exported const 60 //_________________________________________________________________________________________________________________ 61 62 //_________________________________________________________________________________________________________________ 63 // exported definitions 64 //_________________________________________________________________________________________________________________ 65 66 /*-************************************************************************************************************//** 67 @short implement XFrames, XIndexAccess and XElementAccess interfaces as helper for services 68 @descr Use this class as helper for these interfaces. We share mutex and framecontainer with ouer owner. 69 The framecontainer is a member of it from type "FrameContainer". That means; 70 we have the same information as ouer owner. In current implementation we use mutex and lock-mechanism 71 to prevent against compete access. In future we plan support of semaphore! 72 73 @devstatus deprecated 74 @implements XInterface 75 XFrames 76 XIndexAccess 77 XElementAccess 78 @base OWeakObject 79 80 @ATTENTION Don't use this class as direct member - use it dynamicly. Do not derive from this class. 81 We hold a weakreference to ouer owner not to ouer superclass. 82 83 @devstatus deprecated 84 *//*-*************************************************************************************************************/ 85 86 class OFrames : private ThreadHelpBase , // Must be the first of baseclasses - Is neccessary for right initialization of objects! 87 public ::cppu::WeakImplHelper1< ::com::sun::star::frame::XFrames > 88 { 89 //------------------------------------------------------------------------------------------------------------- 90 // public methods 91 //------------------------------------------------------------------------------------------------------------- 92 93 public: 94 95 //--------------------------------------------------------------------------------------------------------- 96 // constructor / destructor 97 //--------------------------------------------------------------------------------------------------------- 98 99 /*-****************************************************************************************************//** 100 @short standard ctor 101 @descr These initialize a new instance of this class with all needed informations for work. 102 We share framecontainer with owner implementation! It's a threadsafe container. 103 104 @seealso - 105 106 @param "xFactory" , reference to factory which has created ouer owner(!). We can use these to create new uno-services. 107 @param "xOwner" , reference to ouer owner. We hold a wekreference to prevent us against cross-references! 108 @param "pFrameContainer" , pointer to shared framecontainer of owner. It's valid only, if weakreference is valid! 109 @return - 110 111 @onerror - 112 *//*-*****************************************************************************************************/ 113 114 OFrames( const css::uno::Reference< css::lang::XMultiServiceFactory >& xFactory , 115 const css::uno::Reference< css::frame::XFrame >& xOwner , 116 FrameContainer* pFrameContainer ); 117 118 //--------------------------------------------------------------------------------------------------------- 119 // XFrames 120 //--------------------------------------------------------------------------------------------------------- 121 122 /*-****************************************************************************************************//** 123 @short append frame to container 124 @descr We share the container with ouer owner. We can do this only, if no lock is set on container. 125 Valid references are accepted only! 126 127 @seealso class FrameContainer 128 129 @param "xFrame", reference to an existing frame to append. 130 @return - 131 132 @onerror We do nothing in release or throw an assert in debug version. 133 *//*-*****************************************************************************************************/ 134 135 virtual void SAL_CALL append( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException ); 136 137 /*-****************************************************************************************************//** 138 @short remove frame from container 139 @descr This is the companion to append(). We only accept valid references and don't work, if 140 a lock is set. 141 142 @seealso class FrameContainer 143 144 @param "xFrame", reference to an existing frame to remove. 145 @return - 146 147 @onerror We do nothing in release or throw an assert in debug version. 148 *//*-*****************************************************************************************************/ 149 150 virtual void SAL_CALL remove( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException ); 151 152 /*-****************************************************************************************************//** 153 @short return list of all applicable frames for given flags 154 @descr Call these to get a list of all frames, which are match with given search flags. 155 156 @seealso - 157 158 @param "nSearchFlag", flags to search right frames. 159 @return A list of founded frames. 160 161 @onerror An empty list is returned. 162 *//*-*****************************************************************************************************/ 163 164 virtual css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > SAL_CALL queryFrames( sal_Int32 nSearchFlags ) throw( css::uno::RuntimeException ); 165 166 //--------------------------------------------------------------------------------------------------------- 167 // XIndexAccess 168 //--------------------------------------------------------------------------------------------------------- 169 170 /*-****************************************************************************************************//** 171 @short get count of all current frames in container 172 @descr This is the beginning of full index-access. With a count you can step over all items in container. 173 Next call shuo�d be getByIndex(). But these mechanism works only, if no lock in container is set! 174 175 @seealso class FrameContainer 176 @seealso method getByIndex() 177 178 @param - 179 @return Count of current items in container. 180 181 @onerror If a lock is set, we return 0 for prevent further access! 182 *//*-*****************************************************************************************************/ 183 184 virtual sal_Int32 SAL_CALL getCount() throw( css::uno::RuntimeException ); 185 186 /*-****************************************************************************************************//** 187 @short get specified container item by index 188 @descr If you called getCount() successful - this method return the specified element as an Any. 189 You must observe the range from 0 to count-1! Otherwise an IndexOutOfBoundsException is thrown. 190 191 @seealso class FrameContainer 192 @seealso method getCount() 193 194 @param "nIndex", valid index to get container item. 195 @return A container item (specified by index) wrapped in an Any. 196 197 @onerror If a lock is set, we return an empty Any! 198 @onerror If index out of range, an IndexOutOfBoundsException is thrown. 199 *//*-*****************************************************************************************************/ 200 201 virtual css::uno::Any SAL_CALL getByIndex( sal_Int32 nIndex ) throw( css::lang::IndexOutOfBoundsException , 202 css::lang::WrappedTargetException , 203 css::uno::RuntimeException ); 204 205 //--------------------------------------------------------------------------------------------------------- 206 // XElementAccess 207 //--------------------------------------------------------------------------------------------------------- 208 209 /*-****************************************************************************************************//** 210 @short get uno-type of all container items 211 @descr In current implementation type is fixed to XFrame! 212 (container-lock is ignored) 213 214 @seealso - 215 216 @param - 217 @return A uno-type descriptor. 218 219 @onerror - 220 *//*-*****************************************************************************************************/ 221 222 virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException ); 223 224 /*-****************************************************************************************************//** 225 @short get fill state of current container 226 @descr Call these to get information about, if items exist in container or not. 227 (container-lock is ignored) 228 229 @seealso - 230 231 @param - 232 @return sal_True, if container contains some items. 233 @return sal_False, otherwise. 234 235 @onerror We return sal_False. 236 *//*-*****************************************************************************************************/ 237 238 virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException ); 239 240 //------------------------------------------------------------------------------------------------------------- 241 // protected methods 242 //------------------------------------------------------------------------------------------------------------- 243 244 protected: 245 246 /*-****************************************************************************************************//** 247 @short standard destructor 248 @descr This method destruct an instance of this class and clear some member. 249 This method is protected, because its not allowed to use this class as a member! 250 You MUST use a dynamical instance (pointer). That's the reason for a protected dtor. 251 252 @seealso - 253 254 @param - 255 @return - 256 257 @onerror - 258 *//*-*****************************************************************************************************/ 259 260 virtual ~OFrames(); 261 262 /*-****************************************************************************************************//** 263 @short reset instance to default values 264 @descr There are two ways to delete an instance of this class.<BR> 265 1) delete with destructor<BR> 266 2) dispose from parent or factory ore ...<BR> 267 This method do the same for both ways! It free used memory and release references ... 268 269 @seealso method dispose() (if it exist!) 270 @seealso destructor ~TaskEnumeration() 271 272 @param - 273 274 @return - 275 276 @onerror - 277 *//*-*****************************************************************************************************/ 278 279 virtual void impl_resetObject(); 280 281 //------------------------------------------------------------------------------------------------------------- 282 // private methods 283 //------------------------------------------------------------------------------------------------------------- 284 285 private: 286 287 /*-****************************************************************************************************//** 288 @short append one sequence to another 289 @descr There is no operation to add to sequences! Use this helper-method to do this. 290 291 @seealso class Sequence 292 293 @param "seqDestination", reference to sequence on which operation will append the other sequence. 294 @param "seqSource" , reference to sequence for append. 295 @return "seqDestination" is parameter AND return value at the same time. 296 297 @onerror - 298 *//*-*****************************************************************************************************/ 299 300 void impl_appendSequence( css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >& seqDestination , 301 const css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >& seqSource ); 302 303 //------------------------------------------------------------------------------------------------------------- 304 // debug methods 305 // (should be private everyway!) 306 //------------------------------------------------------------------------------------------------------------- 307 308 /*-****************************************************************************************************//** 309 @short debug-method to check incoming parameter of some other mehods of this class 310 @descr The following methods are used to check parameters for other methods 311 of this class. The return value is used directly for an ASSERT(...). 312 313 @seealso ASSERTs in implementation! 314 315 @param references to checking variables 316 @return sal_False ,on invalid parameter 317 @return sal_True ,otherwise 318 319 @onerror - 320 *//*-*****************************************************************************************************/ 321 322 #ifdef ENABLE_ASSERTIONS 323 324 private: 325 326 static sal_Bool impldbg_checkParameter_OFramesCtor ( const css::uno::Reference< css::lang::XMultiServiceFactory >& xFactory , 327 const css::uno::Reference< css::frame::XFrame >& xOwner , 328 FrameContainer* pFrameContainer ); 329 static sal_Bool impldbg_checkParameter_append ( const css::uno::Reference< css::frame::XFrame >& xFrame ); 330 static sal_Bool impldbg_checkParameter_remove ( const css::uno::Reference< css::frame::XFrame >& xFrame ); 331 static sal_Bool impldbg_checkParameter_queryFrames ( sal_Int32 nSearchFlags ); 332 333 #endif // #ifdef ENABLE_ASSERTIONS 334 335 //------------------------------------------------------------------------------------------------------------- 336 // variables 337 // (should be private everyway!) 338 //------------------------------------------------------------------------------------------------------------- 339 340 private: 341 342 css::uno::Reference< css::lang::XMultiServiceFactory > m_xFactory ; /// reference to global servicemanager 343 css::uno::WeakReference< css::frame::XFrame > m_xOwner ; /// reference to owner of this instance (Hold no hard reference!) 344 FrameContainer* m_pFrameContainer ; /// with owner shared list to hold all direct childs of an XFramesSupplier 345 sal_Bool m_bRecursiveSearchProtection ; /// flag to protect against recursive searches of frames at parents 346 347 }; // class OFrames 348 349 } // namespace framework 350 351 #endif // #ifndef __FRAMEWORK_HELPER_OFRAMES_HXX_ 352