framework/source/classes/framecontainer.cxx

   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 #include <framework/framecontainer.hxx>
  21
  22 #include <com/sun/star/frame/FrameSearchFlag.hpp>
  23
  24 #include <vcl/svapp.hxx>
  25 #include <comphelper/sequence.hxx>
  26 #include <sal/log.hxx>
  27
  28 namespace framework
  29 {
  30 /**-***************************************************************************************************************
  31     @short      initialize an empty container
  32     @descr      The container will be empty then - special features (e.g. the async quit mechanism) are disabled.
  33
  34     @threadsafe not necessary - it's not a singleton
  35  *****************************************************************************************************************/
  36 FrameContainer::FrameContainer()
  37 /*DEPRECATEME
  38         , m_bAsyncQuit   ( sal_False                                      ) // default must be "disabled"!
  39         , m_aAsyncCall   ( LINK( this, FrameContainer, implts_asyncQuit ) )
  40 */
  41 {
  42 }
  43
  44 /**-***************************************************************************************************************
  45     @short      deinitialize may a filled container
  46     @descr      Special features (if the currently are running) will be disabled and we free all used other resources.
  47
  48     @threadsafe not necessary - it's not a singleton
  49  *****************************************************************************************************************/
  50 FrameContainer::~FrameContainer()
  51 {
  52     // Don't forget to free memory!
  53     m_aContainer.clear();
  54     m_xActiveFrame.clear();
  55 }
  56
  57 /**-***************************************************************************************************************
  58     @short      append a new frame to the container
  59     @descr      We accept the incoming frame only, if it is a valid reference and doesn't exist already.
  60
  61     @param      xFrame
  62                     frame, which should be added to this container
  63                     Must be a valid reference.
  64
  65     @threadsafe yes
  66  *****************************************************************************************************************/
  67 void FrameContainer::append(const css::uno::Reference<css::frame::XFrame>& xFrame)
  68 {
  69     if (xFrame.is() && !exist(xFrame))
  70     {
  71         SolarMutexGuard g;
  72         m_aContainer.push_back(xFrame);
  73     }
  74 }
  75
  76 /**-***************************************************************************************************************
  77     @short      remove a frame from the container
  78     @descr      In case we remove the last frame and our internal special feature (the async quit mechanism)
  79                 was enabled by the desktop instance, we start it.
  80
  81     @param      xFrame
  82                     frame, which should be deleted from this container
  83                     Must be a valid reference.
  84
  85     @threadsafe yes
  86  *****************************************************************************************************************/
  87 void FrameContainer::remove(const css::uno::Reference<css::frame::XFrame>& xFrame)
  88 {
  89     SolarMutexGuard g;
  90
  91     TFrameContainer::iterator aSearchedItem
  92         = ::std::find(m_aContainer.begin(), m_aContainer.end(), xFrame);
  93     if (aSearchedItem != m_aContainer.end())
  94     {
  95         m_aContainer.erase(aSearchedItem);
  96
  97         // If removed frame was the current active frame - reset state variable.
  98         if (m_xActiveFrame == xFrame)
  99             m_xActiveFrame.clear();
 100     }
 101 }
 102
 103 /**-***************************************************************************************************************
 104     @short      check if the given frame currently exist inside the container
 105     @param      xFrame
 106                     reference to the queried frame
 107
 108     @return     <TRUE/> if frame is part of this container
 109                 <FALSE/> otherwise
 110
 111     @threadsafe yes
 112  *****************************************************************************************************************/
 113 bool FrameContainer::exist(const css::uno::Reference<css::frame::XFrame>& xFrame) const
 114 {
 115     SolarMutexGuard g;
 116     return (::std::find(m_aContainer.begin(), m_aContainer.end(), xFrame) != m_aContainer.end());
 117 }
 118
 119 /**-***************************************************************************************************************
 120     @short      delete all existing items of the container
 121     @threadsafe yes
 122  *****************************************************************************************************************/
 123 void FrameContainer::clear()
 124 {
 125     SolarMutexGuard g;
 126     // Clear the container ...
 127     m_aContainer.clear();
 128     // ... and don't forget to reset the active frame.
 129     // It's a reference to a valid container-item.
 130     // But no container item => no active frame!
 131     m_xActiveFrame.clear();
 132 }
 133
 134 /**-***************************************************************************************************************
 135     @short      returns count of all current existing frames
 136     @deprecated This value can't be guaranteed for multithreading environments.
 137                 So it will be marked as deprecated and should be replaced by "getAllElements()".
 138
 139     @return     the count of existing container items
 140
 141     @threadsafe yes
 142  *****************************************************************************************************************/
 143 sal_uInt32 FrameContainer::getCount() const
 144 {
 145     SolarMutexGuard g;
 146     return static_cast<sal_uInt32>(m_aContainer.size());
 147 }
 148
 149 /**-***************************************************************************************************************
 150     @short      returns one item of this container
 151     @deprecated This value can't be guaranteed for multithreading environments.
 152                 So it will be marked as deprecated and should be replaced by "getAllElements()".
 153
 154     @param      nIndex
 155                     a value between 0 and (getCount()-1) to address one container item
 156
 157     @return     a reference to a frame inside the container, which match with given index
 158
 159     @threadsafe yes
 160  *****************************************************************************************************************/
 161 css::uno::Reference<css::frame::XFrame> FrameContainer::operator[](sal_uInt32 nIndex) const
 162 {
 163     css::uno::Reference<css::frame::XFrame> xFrame;
 164     try
 165     {
 166         // Get element form container WITH automatic test of ranges!
 167         // If index not valid, an out_of_range exception is thrown.
 168         SolarMutexGuard g;
 169         xFrame = m_aContainer.at(nIndex);
 170     }
 171     catch (const std::out_of_range&)
 172     {
 173         // The index is not valid for current container-content - we must handle this case!
 174         // We can return the default value ...
 175         SAL_INFO("fwk", "FrameContainer::operator[]: Exception caught: std::out_of_range");
 176     }
 177     return xFrame;
 178 }
 179
 180 /**-***************************************************************************************************************
 181     @short      returns a snapshot of all currently existing frames inside this container
 182     @descr      Should be used to replace the deprecated functions getCount()/operator[]!
 183
 184     @return     a list of all frame references inside this container
 185
 186     @threadsafe yes
 187  *****************************************************************************************************************/
 188 css::uno::Sequence<css::uno::Reference<css::frame::XFrame>> FrameContainer::getAllElements() const
 189 {
 190     SolarMutexGuard g;
 191     return comphelper::containerToSequence(m_aContainer);
 192 }
 193
 194 /**-***************************************************************************************************************
 195     @short      set the given frame as  the new active one inside this container
 196     @descr      We accept this frame only, if it's already a part of this container.
 197
 198     @param      xFrame
 199                     reference to the new active frame
 200                     Must be a valid reference and already part of this container.
 201
 202     @threadsafe yes
 203  *****************************************************************************************************************/
 204 void FrameContainer::setActive(const css::uno::Reference<css::frame::XFrame>& xFrame)
 205 {
 206     if (!xFrame.is() || exist(xFrame))
 207     {
 208         SolarMutexGuard g;
 209         m_xActiveFrame = xFrame;
 210     }
 211 }
 212
 213 /**-***************************************************************************************************************
 214     @short      return the current active frame of this container
 215     @descr      Value can be null in case the frame was removed from the container and nobody
 216                 from outside decide which of all others should be the new one...
 217
 218     @return     a reference to the current active frame
 219                 Value can be NULL!
 220
 221     @threadsafe yes
 222  *****************************************************************************************************************/
 223 css::uno::Reference<css::frame::XFrame> FrameContainer::getActive() const
 224 {
 225     SolarMutexGuard g;
 226     return m_xActiveFrame;
 227 }
 228
 229 /**-***************************************************************************************************************
 230     @short      implements a simple search based on current container items
 231     @descr      It can be used for findFrame() and implements a deep down search.
 232
 233     @param      sName
 234                     target name, which is searched
 235
 236     @return     reference to the found frame or NULL if not.
 237
 238     @threadsafe yes
 239  *****************************************************************************************************************/
 240 css::uno::Reference<css::frame::XFrame>
 241 FrameContainer::searchOnAllChildrens(const OUString& sName) const
 242 {
 243     SolarMutexGuard g;
 244     // Step over all child frames. But if direct child isn't the right one search on his children first - before
 245     // you go to next direct child of this container!
 246     css::uno::Reference<css::frame::XFrame> xSearchedFrame;
 247     for (auto const& container : m_aContainer)
 248     {
 249         if (container->getName() == sName)
 250         {
 251             xSearchedFrame = container;
 252             break;
 253         }
 254         else
 255         {
 256             xSearchedFrame = container->findFrame(sName, css::frame::FrameSearchFlag::CHILDREN);
 257             if (xSearchedFrame.is())
 258                 break;
 259         }
 260     }
 261     return xSearchedFrame;
 262 }
 263
 264 /**-***************************************************************************************************************
 265     @short      implements a simple search based on current container items
 266     @descr      It can be used for findFrame() and search on members of this container only!
 267
 268     @param      sName
 269                     target name, which is searched
 270
 271     @return     reference to the found frame or NULL if not.
 272
 273     @threadsafe yes
 274  *****************************************************************************************************************/
 275 css::uno::Reference<css::frame::XFrame>
 276 FrameContainer::searchOnDirectChildrens(std::u16string_view sName) const
 277 {
 278     SolarMutexGuard g;
 279     css::uno::Reference<css::frame::XFrame> xSearchedFrame;
 280     for (auto const& container : m_aContainer)
 281     {
 282         if (container->getName() == sName)
 283         {
 284             xSearchedFrame = container;
 285             break;
 286         }
 287     }
 288     return xSearchedFrame;
 289 }
 290
 291 } //  namespace framework
 292
 293 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */