framework/inc/helper/oframes.hxx

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