framework/inc/helper/oframes.hxx

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