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