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