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 our owner. 69 The framecontainer is a member of it from type "FrameContainer". That means; 70 we have the same information as our 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 dynamically. Do not derive from this class. 81 We hold a weakreference to our owner not to our superclass. 82 83 @devstatus deprecated 84 *//*-*************************************************************************************************************/ 85 86 class OFrames : private ThreadHelpBase , // Must be the first of baseclasses - Is necessary 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 our owner(!). We can use these to create new uno-services. 107 @param "xOwner" , reference to our 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 our 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 ); 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 ); 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 ); 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 should 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(); 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 ); 202 203 //--------------------------------------------------------------------------------------------------------- 204 // XElementAccess 205 //--------------------------------------------------------------------------------------------------------- 206 207 /*-****************************************************************************************************//** 208 @short get uno-type of all container items 209 @descr In current implementation type is fixed to XFrame! 210 (container-lock is ignored) 211 212 @seealso - 213 214 @param - 215 @return A uno-type descriptor. 216 217 @onerror - 218 *//*-*****************************************************************************************************/ 219 220 virtual css::uno::Type SAL_CALL getElementType(); 221 222 /*-****************************************************************************************************//** 223 @short get fill state of current container 224 @descr Call these to get information about, if items exist in container or not. 225 (container-lock is ignored) 226 227 @seealso - 228 229 @param - 230 @return sal_True, if container contains some items. 231 @return sal_False, otherwise. 232 233 @onerror We return sal_False. 234 *//*-*****************************************************************************************************/ 235 236 virtual sal_Bool SAL_CALL hasElements(); 237 238 //------------------------------------------------------------------------------------------------------------- 239 // protected methods 240 //------------------------------------------------------------------------------------------------------------- 241 242 protected: 243 244 /*-****************************************************************************************************//** 245 @short standard destructor 246 @descr This method destruct an instance of this class and clear some member. 247 This method is protected, because its not allowed to use this class as a member! 248 You MUST use a dynamical instance (pointer). That's the reason for a protected dtor. 249 250 @seealso - 251 252 @param - 253 @return - 254 255 @onerror - 256 *//*-*****************************************************************************************************/ 257 258 virtual ~OFrames(); 259 260 /*-****************************************************************************************************//** 261 @short reset instance to default values 262 @descr There are two ways to delete an instance of this class.<BR> 263 1) delete with destructor<BR> 264 2) dispose from parent or factory ore ...<BR> 265 This method do the same for both ways! It free used memory and release references ... 266 267 @seealso method dispose() (if it exist!) 268 @seealso destructor ~TaskEnumeration() 269 270 @param - 271 272 @return - 273 274 @onerror - 275 *//*-*****************************************************************************************************/ 276 277 virtual void impl_resetObject(); 278 279 //------------------------------------------------------------------------------------------------------------- 280 // private methods 281 //------------------------------------------------------------------------------------------------------------- 282 283 private: 284 285 /*-****************************************************************************************************//** 286 @short append one sequence to another 287 @descr There is no operation to add to sequences! Use this helper-method to do this. 288 289 @seealso class Sequence 290 291 @param "seqDestination", reference to sequence on which operation will append the other sequence. 292 @param "seqSource" , reference to sequence for append. 293 @return "seqDestination" is parameter AND return value at the same time. 294 295 @onerror - 296 *//*-*****************************************************************************************************/ 297 298 void impl_appendSequence( css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >& seqDestination , 299 const css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >& seqSource ); 300 301 //------------------------------------------------------------------------------------------------------------- 302 // debug methods 303 // (should be private everyway!) 304 //------------------------------------------------------------------------------------------------------------- 305 306 /*-****************************************************************************************************//** 307 @short debug-method to check incoming parameter of some other methods of this class 308 @descr The following methods are used to check parameters for other methods 309 of this class. The return value is used directly for an ASSERT(...). 310 311 @seealso ASSERTs in implementation! 312 313 @param references to checking variables 314 @return sal_False ,on invalid parameter 315 @return sal_True ,otherwise 316 317 @onerror - 318 *//*-*****************************************************************************************************/ 319 320 #ifdef ENABLE_ASSERTIONS 321 322 private: 323 324 static sal_Bool impldbg_checkParameter_OFramesCtor ( const css::uno::Reference< css::lang::XMultiServiceFactory >& xFactory , 325 const css::uno::Reference< css::frame::XFrame >& xOwner , 326 FrameContainer* pFrameContainer ); 327 static sal_Bool impldbg_checkParameter_append ( const css::uno::Reference< css::frame::XFrame >& xFrame ); 328 static sal_Bool impldbg_checkParameter_remove ( const css::uno::Reference< css::frame::XFrame >& xFrame ); 329 static sal_Bool impldbg_checkParameter_queryFrames ( sal_Int32 nSearchFlags ); 330 331 #endif // #ifdef ENABLE_ASSERTIONS 332 333 //------------------------------------------------------------------------------------------------------------- 334 // variables 335 // (should be private everyway!) 336 //------------------------------------------------------------------------------------------------------------- 337 338 private: 339 340 css::uno::Reference< css::lang::XMultiServiceFactory > m_xFactory ; /// reference to global servicemanager 341 css::uno::WeakReference< css::frame::XFrame > m_xOwner ; /// reference to owner of this instance (Hold no hard reference!) 342 FrameContainer* m_pFrameContainer ; /// with owner shared list to hold all direct childs of an XFramesSupplier 343 sal_Bool m_bRecursiveSearchProtection ; /// flag to protect against recursive searches of frames at parents 344 345 }; // class OFrames 346 347 } // namespace framework 348 349 #endif // #ifndef __FRAMEWORK_HELPER_OFRAMES_HXX_ 350