framework/source/classes/framecontainer.cxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: framecontainer.cxx,v $
  10  * $Revision: 1.24.82.1 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 // MARKER(update_precomp.py): autogen include statement, do not remove
  32 #include "precompiled_framework.hxx"
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #ifndef __FRAMEWORK_FRAMECONTAINER_HXX_
  39 #include <classes/framecontainer.hxx>
  40 #endif
  41 #include <threadhelp/writeguard.hxx>
  42 #include <threadhelp/readguard.hxx>
  43
  44 #ifndef __FRAMEWORK_COMMANDS_HXX_
  45 #include <commands.h>
  46 #endif
  47
  48 //_________________________________________________________________________________________________________________
  49 //      interface includes
  50 //_________________________________________________________________________________________________________________
  51
  52 #ifndef _COM_SUN_STAR_FRAME_FRAMESEARCH_FLAG_HPP_
  53 #include <com/sun/star/frame/FrameSearchFlag.hpp>
  54 #endif
  55
  56 //_________________________________________________________________________________________________________________
  57 //      includes of other projects
  58 //_________________________________________________________________________________________________________________
  59 #include <vcl/svapp.hxx>
  60
  61 //_________________________________________________________________________________________________________________
  62 //      namespace
  63 //_________________________________________________________________________________________________________________
  64
  65 namespace framework{
  66
  67 //_________________________________________________________________________________________________________________
  68 //      non exported const
  69 //_________________________________________________________________________________________________________________
  70
  71 //_________________________________________________________________________________________________________________
  72 //      non exported definitions
  73 //_________________________________________________________________________________________________________________
  74
  75 //_________________________________________________________________________________________________________________
  76 //      declarations
  77 //_________________________________________________________________________________________________________________
  78
  79 /**-***************************************************************************************************************
  80     @short      initialize an empty container
  81     @descr      The container will be empty then - special features (e.g. the async quit mechanism) are disabled.
  82
  83     @threadsafe not neccessary - its not a singleton
  84     @modified   01.07.2002 14:42,as96863
  85  *****************************************************************************************************************/
  86 FrameContainer::FrameContainer()
  87         // initialize base classes first.
  88         // Order is neccessary for right initilization of his and OUR member ... m_aLock
  89         : ThreadHelpBase ( &Application::GetSolarMutex()                  )
  90 /*DEPRECATEME
  91         , m_bAsyncQuit   ( sal_False                                      ) // default must be "disabled"!
  92         , m_aAsyncCall   ( LINK( this, FrameContainer, implts_asyncQuit ) )
  93 */
  94 {
  95 }
  96
  97 /**-***************************************************************************************************************
  98     @short      deinitialize may a filled container
  99     @descr      Special features (if the currently are running) will be dsiabled and we free all used other ressources.
 100
 101     @threadsafe not neccessary - its not a singleton
 102     @modified   01.07.2002 14:43,as96863
 103  *****************************************************************************************************************/
 104 FrameContainer::~FrameContainer()
 105 {
 106     // Don't forget to free memory!
 107     m_aContainer.clear();
 108     m_xActiveFrame.clear();
 109 }
 110
 111 /**-***************************************************************************************************************
 112     @short      append a new frame to the container
 113     @descr      We accept the incoming frame only, if it is a valid reference and dosnt exist already.
 114
 115     @param      xFrame
 116                     frame, which should be added to this container
 117                     Must be a valid reference.
 118
 119     @threadsafe yes
 120     @modified   01.07.2002 14:44,as96863
 121  *****************************************************************************************************************/
 122 void FrameContainer::append( const css::uno::Reference< css::frame::XFrame >& xFrame )
 123 {
 124     if (xFrame.is() && ! exist(xFrame))
 125     {
 126         /* SAFE { */
 127         WriteGuard aWriteLock( m_aLock );
 128         m_aContainer.push_back( xFrame );
 129         aWriteLock.unlock();
 130         /* } SAFE */
 131     }
 132 }
 133
 134 /**-***************************************************************************************************************
 135     @short      remove a frame from the container
 136     @descr      In case we remove the last frame and our internal special feature (the async quit mechanism)
 137                 was enabled by the desktop instance, we start it.
 138
 139     @param      xFrame
 140                     frame, which should be deleted from this container
 141                     Must be a valid reference.
 142
 143     @threadsafe yes
 144     @modified   01.07.2002 14:52,as96863
 145  *****************************************************************************************************************/
 146 void FrameContainer::remove( const css::uno::Reference< css::frame::XFrame >& xFrame )
 147 {
 148     /* SAFE { */
 149     // write lock neccessary for follwing erase()!
 150     WriteGuard aWriteLock( m_aLock );
 151
 152     TFrameIterator aSearchedItem = ::std::find( m_aContainer.begin(), m_aContainer.end(), xFrame );
 153     if (aSearchedItem!=m_aContainer.end())
 154     {
 155         m_aContainer.erase( aSearchedItem );
 156
 157         // If removed frame was the current active frame - reset state variable.
 158         if (m_xActiveFrame==xFrame)
 159             m_xActiveFrame = css::uno::Reference< css::frame::XFrame >();
 160
 161         // We don't need the write lock any longer ...
 162         // downgrade to read access.
 163         aWriteLock.downgrade();
 164 /*DEPRECATEME
 165         // If last frame was removed and special quit mode is enabled by the desktop
 166         // we must terminate the application by using this asynchronous callback!
 167         if (m_aContainer.size()<1 && m_bAsyncQuit)
 168             m_aAsyncCall.Post(0);
 169 */
 170     }
 171
 172     aWriteLock.unlock();
 173     // } SAFE
 174 }
 175
 176 /**-***************************************************************************************************************
 177     @short      check if the given frame currently exist inside the container
 178     @descr      -
 179
 180     @param      xFrame
 181                     reference to the queried frame
 182
 183     @return     <TRUE/> if frame is oart of this container
 184                 <FALSE/> otherwhise
 185
 186     @threadsafe yes
 187     @modified   01.07.2002 14:55,as96863
 188  *****************************************************************************************************************/
 189 sal_Bool FrameContainer::exist( const css::uno::Reference< css::frame::XFrame >& xFrame ) const
 190 {
 191     /* SAFE { */
 192     ReadGuard aReadLock( m_aLock );
 193     return( ::std::find( m_aContainer.begin(), m_aContainer.end(), xFrame ) != m_aContainer.end() );
 194     /* } SAFE */
 195 }
 196
 197 /**-***************************************************************************************************************
 198     @short      delete all existing items of the container
 199     @descr      -
 200
 201     @threadsafe yes
 202     @modified   01.07.2002 15:00,as96863
 203  *****************************************************************************************************************/
 204 void FrameContainer::clear()
 205 {
 206     // SAFE {
 207     WriteGuard aWriteLock( m_aLock );
 208
 209     // Clear the container ...
 210     m_aContainer.clear();
 211     // ... and don't forget to reset the active frame.
 212     // Its an reference to a valid container-item.
 213     // But no container item => no active frame!
 214     m_xActiveFrame = css::uno::Reference< css::frame::XFrame >();
 215 /*DEPRECATEME
 216     // If special quit mode is used - we must terminate the desktop.
 217     // He is the owner of this container and can't work without any visible tasks/frames!
 218     if (m_bAsyncQuit)
 219         m_aAsyncCall.Post(0);
 220 */
 221
 222     aWriteLock.unlock();
 223     // } SAFE
 224 }
 225
 226 /**-***************************************************************************************************************
 227     @short      returns count of all current existing frames
 228     @descr      -
 229
 230     @deprecated This value can't be guaranteed for multithreading environments.
 231                 So it will be marked as deprecated and should be replaced by "getAllElements()".
 232
 233     @return     the count of existing container items
 234
 235     @threadsafe yes
 236     @modified   01.07.2002 15:00,as96863
 237  *****************************************************************************************************************/
 238 sal_uInt32 FrameContainer::getCount() const
 239 {
 240     /* SAFE { */
 241     ReadGuard aReadLock( m_aLock );
 242     return( (sal_uInt32)m_aContainer.size() );
 243     /* } SAFE */
 244 }
 245
 246 /**-***************************************************************************************************************
 247     @short      returns one item of this container
 248     @descr      -
 249
 250     @deprecated This value can't be guaranteed for multithreading environments.
 251                 So it will be marked as deprecated and should be replaced by "getAllElements()".
 252
 253     @param      nIndex
 254                     a valud between 0 and (getCount()-1) to adress one container item
 255
 256     @return     a reference to a frame inside the container, which match with given index
 257
 258     @threadsafe yes
 259     @modified   01.07.2002 15:03,as96863
 260  *****************************************************************************************************************/
 261 css::uno::Reference< css::frame::XFrame > FrameContainer::operator[]( sal_uInt32 nIndex ) const
 262 {
 263
 264     css::uno::Reference< css::frame::XFrame > xFrame;
 265     try
 266     {
 267         // Get element form container WITH automatic test of ranges!
 268         // If index not valid, a out_of_range exception is thrown.
 269         /* SAFE { */
 270         ReadGuard aReadLock( m_aLock );
 271         xFrame = m_aContainer.at( nIndex );
 272         aReadLock.unlock();
 273         /* } SAFE */
 274     }
 275     catch( std::out_of_range& )
 276     {
 277         // The index is not valid for current container-content - we must handle this case!
 278         // We can return the default value ...
 279         LOG_EXCEPTION( "FrameContainer::operator[]", "Exception catched ...", DECLARE_ASCII("::std::out_of_range") )
 280     }
 281     return xFrame;
 282 }
 283
 284 /**-***************************************************************************************************************
 285     @short      returns a snapshot of all currently existing frames inside this container
 286     @descr      Should be used to replace the deprecated functions getCount()/operator[]!
 287
 288     @return     a list of all frame refrences inside this container
 289
 290     @threadsafe yes
 291     @modified   01.07.2002 15:09,as96863
 292  *****************************************************************************************************************/
 293 css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > FrameContainer::getAllElements() const
 294 {
 295     /* SAFE { */
 296     ReadGuard aReadLock( m_aLock );
 297
 298     sal_Int32                                                       nPosition = 0;
 299     css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > lElements ( (sal_uInt32)m_aContainer.size() );
 300     for (TConstFrameIterator pItem=m_aContainer.begin(); pItem!=m_aContainer.end(); ++pItem)
 301         lElements[nPosition++] = *pItem;
 302
 303     aReadLock.unlock();
 304     /* } SAFE */
 305
 306     return lElements;
 307 }
 308
 309 /**-***************************************************************************************************************
 310     @short      set the given frame as  the new active one inside this container
 311     @descr      We accept this frame only, if it's already a part of this container.
 312
 313     @param      xFrame
 314                     reference to the new active frame
 315                     Must be a valid reference and already part of this container.
 316
 317     @threadsafe yes
 318     @modified   01.07.2002 15:11,as96863
 319  *****************************************************************************************************************/
 320 void FrameContainer::setActive( const css::uno::Reference< css::frame::XFrame >& xFrame )
 321 {
 322     if ( !xFrame.is() || exist(xFrame) )
 323     {
 324         /* SAFE { */
 325         WriteGuard aWriteLock( m_aLock );
 326         m_xActiveFrame = xFrame;
 327         aWriteLock.unlock();
 328         /* } SAFE */
 329     }
 330 }
 331
 332 /**-***************************************************************************************************************
 333     @short      return sthe current active frame of this container
 334     @descr      Value can be null in case the frame was removed from the container and nobody
 335                 from outside decide which of all others should be the new one ...
 336
 337     @return     a reference to the current active frame
 338                 Value can be NULL!
 339
 340     @threadsafe yes
 341     @modified   01.07.2002 15:11,as96863
 342  *****************************************************************************************************************/
 343 css::uno::Reference< css::frame::XFrame > FrameContainer::getActive() const
 344 {
 345     /* SAFE { */
 346     ReadGuard aReadLock( m_aLock );
 347     return m_xActiveFrame;
 348     /* } SAFE */
 349 }
 350
 351 /**-***************************************************************************************************************
 352     @short      implements a simple search based on current container items
 353     @descr      It can be used for findFrame() and implements a deep down search.
 354
 355     @param      sName
 356                     target name, which is searched
 357
 358     @return     reference to the found frame or NULL if not.
 359
 360     @threadsafe yes
 361     @modified   01.07.2002 15:22,as96863
 362  *****************************************************************************************************************/
 363 css::uno::Reference< css::frame::XFrame > FrameContainer::searchOnAllChildrens( const ::rtl::OUString& sName ) const
 364 {
 365     /* SAFE { */
 366     ReadGuard aReadLock( m_aLock );
 367
 368     // Step over all child frames. But if direct child isn't the right one search on his children first - before
 369     // you go to next direct child of this container!
 370     css::uno::Reference< css::frame::XFrame > xSearchedFrame;
 371     for( TConstFrameIterator pIterator=m_aContainer.begin(); pIterator!=m_aContainer.end(); ++pIterator )
 372     {
 373         if ((*pIterator)->getName()==sName)
 374         {
 375             xSearchedFrame = *pIterator;
 376             break;
 377         }
 378         else
 379         {
 380             xSearchedFrame = (*pIterator)->findFrame( sName, css::frame::FrameSearchFlag::CHILDREN );
 381             if (xSearchedFrame.is())
 382                 break;
 383         }
 384     }
 385     aReadLock.unlock();
 386     /* } SAFE */
 387     return xSearchedFrame;
 388 }
 389
 390 /**-***************************************************************************************************************
 391     @short      implements a simple search based on current container items
 392     @descr      It can be used for findFrame() and search on members of this container only!
 393
 394     @param      sName
 395                     target name, which is searched
 396
 397     @return     reference to the found frame or NULL if not.
 398
 399     @threadsafe yes
 400     @modified   01.07.2002 15:22,as96863
 401  *****************************************************************************************************************/
 402 css::uno::Reference< css::frame::XFrame > FrameContainer::searchOnDirectChildrens( const ::rtl::OUString& sName ) const
 403 {
 404     /* SAFE { */
 405     ReadGuard aReadLock( m_aLock );
 406
 407     css::uno::Reference< css::frame::XFrame > xSearchedFrame;
 408     for( TConstFrameIterator pIterator=m_aContainer.begin(); pIterator!=m_aContainer.end(); ++pIterator )
 409     {
 410         if ((*pIterator)->getName()==sName)
 411         {
 412             xSearchedFrame = *pIterator;
 413             break;
 414         }
 415     }
 416     aReadLock.unlock();
 417     /* } SAFE */
 418     return xSearchedFrame;
 419 }
 420
 421 } //  namespace framework