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 INCLUDED_FRAMEWORK_INC_HELPER_OFRAMES_HXX
  21 #define INCLUDED_FRAMEWORK_INC_HELPER_OFRAMES_HXX
  22
  23 #include <classes/framecontainer.hxx>
  24 #include <macros/generic.hxx>
  25 #include <macros/xinterface.hxx>
  26 #include <macros/xtypeprovider.hxx>
  27 #include <general.h>
  28
  29 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  30 #include <com/sun/star/frame/XFrames.hpp>
  31 #include <com/sun/star/frame/XFrame.hpp>
  32
  33 #include <cppuhelper/implbase1.hxx>
  34 #include <cppuhelper/weakref.hxx>
  35
  36 namespace framework{
  37
  38 /*-************************************************************************************************************
  39     @short          implement XFrames, XIndexAccess and XElementAccess interfaces as helper for services
  40     @descr          Use this class as helper for these interfaces. We share mutex and framecontainer with our owner.
  41                     The framecontainer is a member of it from type "FrameContainer". That means;
  42                     we have the same information as our owner. In current implementation we use mutex and lock-mechanism
  43                     to prevent against compete access. In future we plan support of semaphore!
  44
  45     @devstatus      deprecated
  46     @implements     XInterface
  47                     XFrames
  48                     XIndexAccess
  49                     XElementAccess
  50     @base           OWeakObject
  51
  52     @ATTENTION      Don't use this class as direct member - use it dynamicly. Do not derive from this class.
  53                     We hold a weakreference to our owner not to our superclass.
  54
  55     @devstatus      deprecated
  56 *//*-*************************************************************************************************************/
  57 class OFrames   :   public ::cppu::WeakImplHelper1< ::com::sun::star::frame::XFrames >
  58 {
  59     public:
  60
  61         /*-****************************************************************************************************
  62             @short      standard ctor
  63             @descr      These initialize a new instance of this class with all needed information for work.
  64                         We share framecontainer with owner implementation! It's a threadsafe container.
  65             @param      xOwner            , reference to our owner. We hold a wekreference to prevent us against cross-references!
  66             @param      pFrameContainer   , pointer to shared framecontainer of owner. It's valid only, if weakreference is valid!
  67         *//*-*****************************************************************************************************/
  68          OFrames(   const   css::uno::Reference< css::frame::XFrame >&              xOwner          ,
  69                             FrameContainer*                                         pFrameContainer );
  70
  71         //  XFrames
  72
  73         /*-****************************************************************************************************
  74             @short      append frame to container
  75             @descr      We share the container with our owner. We can do this only, if no lock is set on container.
  76                         Valid references are accepted only!
  77
  78             @seealso    class FrameContainer
  79
  80             @param      "xFrame", reference to an existing frame to append.
  81             @onerror    We do nothing in release or throw an assert in debug version.
  82         *//*-*****************************************************************************************************/
  83         virtual void SAL_CALL append( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
  84
  85         /*-****************************************************************************************************
  86             @short      remove frame from container
  87             @descr      This is the companion to append(). We only accept valid references and don't work, if
  88                         a lock is set.
  89
  90             @seealso    class FrameContainer
  91
  92             @param      "xFrame", reference to an existing frame to remove.
  93             @onerror    We do nothing in release or throw an assert in debug version.
  94         *//*-*****************************************************************************************************/
  95         virtual void SAL_CALL remove( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
  96
  97         /*-****************************************************************************************************
  98             @short      return list of all applicable frames for given flags
  99             @descr      Call these to get a list of all frames, which are match with given search flags.
 100             @param      "nSearchFlag", flags to search right frames.
 101             @return     A list of founded frames.
 102
 103             @onerror    An empty list is returned.
 104         *//*-*****************************************************************************************************/
 105         virtual css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > SAL_CALL queryFrames( sal_Int32 nSearchFlags ) throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 106
 107         //  XIndexAccess
 108
 109         /*-****************************************************************************************************
 110             @short      get count of all current frames in container
 111             @descr      This is the beginning of full index-access. With a count you can step over all items in container.
 112                         Next call should be getByIndex(). But these mechanism works only, if no lock in container is set!
 113
 114             @seealso    class FrameContainer
 115             @seealso    method getByIndex()
 116             @return     Count of current items in container.
 117
 118             @onerror    If a lock is set, we return 0 for prevent further access!
 119         *//*-*****************************************************************************************************/
 120         virtual sal_Int32 SAL_CALL getCount() throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 121
 122         /*-****************************************************************************************************
 123             @short      get specified container item by index
 124             @descr      If you called getCount() successful - this method return the specified element as an Any.
 125                         You must observe the range from 0 to count-1! Otherwise an IndexOutOfBoundsException is thrown.
 126
 127             @seealso    class FrameContainer
 128             @seealso    method getCount()
 129
 130             @param      "nIndex", valid index to get container item.
 131             @return     A container item (specified by index) wrapped in an Any.
 132
 133             @onerror    If a lock is set, we return an empty Any!
 134             @onerror    If index out of range, an IndexOutOfBoundsException is thrown.
 135         *//*-*****************************************************************************************************/
 136         virtual css::uno::Any SAL_CALL getByIndex( sal_Int32 nIndex ) throw(    css::lang::IndexOutOfBoundsException    ,
 137                                                                                 css::lang::WrappedTargetException       ,
 138                                                                                 css::uno::RuntimeException, std::exception              ) SAL_OVERRIDE;
 139
 140         //  XElementAccess
 141
 142         /*-****************************************************************************************************
 143             @short      get uno-type of all container items
 144             @descr      In current implementation type is fixed to XFrame!
 145                         (container-lock is ignored)
 146             @return     A uno-type descriptor.
 147         *//*-*****************************************************************************************************/
 148         virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 149
 150         /*-****************************************************************************************************
 151             @short      get fill state of current container
 152             @descr      Call these to get information about, if items exist in container or not.
 153                         (container-lock is ignored)
 154             @return     sal_True, if container contains some items.
 155             @return     sal_False, otherwise.
 156
 157             @onerror    We return sal_False.
 158         *//*-*****************************************************************************************************/
 159         virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 160
 161     protected:
 162
 163         /*-****************************************************************************************************
 164             @short      standard destructor
 165             @descr      This method destruct an instance of this class and clear some member.
 166                         This method is protected, because its not allowed to use this class as a member!
 167                         You MUST use a dynamical instance (pointer). That's the reason for a protected dtor.
 168         *//*-*****************************************************************************************************/
 169         virtual ~OFrames();
 170
 171         /*-****************************************************************************************************
 172             @short      reset instance to default values
 173             @descr      There are two ways to delete an instance of this class.<BR>
 174                         1) delete with destructor<BR>
 175                         2) dispose from parent or factory ore ...<BR>
 176                         This method do the same for both ways! It free used memory and release references ...
 177
 178             @seealso    method dispose() (if it exist!)
 179             @seealso    destructor ~TaskEnumeration()
 180         *//*-*****************************************************************************************************/
 181         void impl_resetObject();
 182
 183     private:
 184
 185         /*-****************************************************************************************************
 186             @short      append one sequence to another
 187             @descr      There is no operation to add to sequences! Use this helper-method to do this.
 188
 189             @seealso    class Sequence
 190
 191             @param      "seqDestination", reference to sequence on which operation will append the other sequence.
 192             @param      "seqSource"     , reference to sequence for append.
 193             @return     "seqDestination" is parameter AND return value at the same time.
 194         *//*-*****************************************************************************************************/
 195         void impl_appendSequence(           css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >&    seqDestination  ,
 196                                      const  css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >&    seqSource       );
 197
 198     //  debug methods
 199     //  (should be private everyway!)
 200
 201         /*-****************************************************************************************************
 202             @short      debug-method to check incoming parameter of some other mehods of this class
 203             @descr      The following methods are used to check parameters for other methods
 204                         of this class. The return value is used directly for an ASSERT(...).
 205
 206             @seealso    ASSERTs in implementation!
 207
 208             @param      references to checking variables
 209             @return     sal_False ,on invalid parameter
 210             @return     sal_True  ,otherwise
 211         *//*-*****************************************************************************************************/
 212
 213     private:
 214         static bool impldbg_checkParameter_OFramesCtor  (   const   css::uno::Reference< css::frame::XFrame >&              xOwner          ,
 215                                                                         FrameContainer*                                         pFrameContainer );
 216         static bool impldbg_checkParameter_append       (   const   css::uno::Reference< css::frame::XFrame >&              xFrame          );
 217         static bool impldbg_checkParameter_remove       (   const   css::uno::Reference< css::frame::XFrame >&              xFrame          );
 218         static bool impldbg_checkParameter_queryFrames  (           sal_Int32                                               nSearchFlags    );
 219
 220     //  variables
 221     //  (should be private everyway!)
 222
 223     private:
 224         css::uno::WeakReference< css::frame::XFrame >               m_xOwner;   /// reference to owner of this instance (Hold no hard reference!)
 225         FrameContainer*                                             m_pFrameContainer;   /// with owner shared list to hold all direct children of an XFramesSupplier
 226         bool                                                        m_bRecursiveSearchProtection;   /// flag to protect against recursive searches of frames at parents
 227
 228 };
 229
 230 }
 231
 232 #endif
 233
 234 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */