framework/inc/helper/ocomponentaccess.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_OCOMPONENTACCESS_HXX_
  21 #define __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
  22
  23 #include <threadhelp/threadhelpbase.hxx>
  24 #include <macros/generic.hxx>
  25 #include <macros/xinterface.hxx>
  26 #include <macros/xtypeprovider.hxx>
  27 #include <macros/debug.hxx>
  28 #include <general.h>
  29
  30 #include <com/sun/star/frame/XFramesSupplier.hpp>
  31 #include <com/sun/star/container/XEnumerationAccess.hpp>
  32 #include <com/sun/star/container/XElementAccess.hpp>
  33 #include <com/sun/star/container/XEnumeration.hpp>
  34 #include <com/sun/star/frame/XDesktop.hpp>
  35 #include <com/sun/star/lang/XComponent.hpp>
  36
  37 #include <cppuhelper/implbase1.hxx>
  38 #include <cppuhelper/weakref.hxx>
  39
  40 namespace framework{
  41
  42 /*-************************************************************************************************************//**
  43     @short          implement XEnumerationAccess interface as helper to create many oneway enumeration of components
  44     @descr          We share mutex and framecontainer with ouer owner and have full access to his child tasks.
  45                     (Ouer owner can be the Desktop only!) We create oneway enumerations on demand. These "lists"
  46                     can be used for one time only. Step during the list from first to last element.
  47                     (The type of created enumerations is OComponentEnumeration.)
  48
  49     @implements     XInterface
  50                     XTypeProvider
  51                     XEnumerationAccess
  52                     XElementAccess
  53
  54     @base           ThreadHelpBase
  55                     OWeakObject
  56
  57     @devstatus      ready to use
  58 *//*-*************************************************************************************************************/
  59
  60 class OComponentAccess  :   private ThreadHelpBase                      ,   // Must be the first of baseclasses - Is necessary for right initialization of objects!
  61                             public ::cppu::WeakImplHelper1< ::com::sun::star::container::XEnumerationAccess >
  62 {
  63     //-------------------------------------------------------------------------------------------------------------
  64     //  public methods
  65     //-------------------------------------------------------------------------------------------------------------
  66
  67     public:
  68
  69         //---------------------------------------------------------------------------------------------------------
  70         //  constructor / destructor
  71         //---------------------------------------------------------------------------------------------------------
  72
  73         /*-****************************************************************************************************//**
  74             @short      constructor to initialize this instance
  75             @descr      A desktop will create an enumeration-access-object. An enumeration is a oneway-list and a
  76                         snapshot of the components of current tasks under the desktop.
  77                         But we need a instance to create more then one enumerations at different times!
  78
  79             @seealso    class Desktop
  80             @seealso    class OComponentEnumeration
  81
  82             @param      "xOwner" is a reference to ouer owner and must be the desktop!
  83             @return     -
  84
  85             @onerror    Do nothing and reset this object to default with an empty list.
  86         *//*-*****************************************************************************************************/
  87
  88         OComponentAccess( const css::uno::Reference< css::frame::XDesktop >& xOwner );
  89
  90         //---------------------------------------------------------------------------------------------------------
  91         //  XEnumerationAccess
  92         //---------------------------------------------------------------------------------------------------------
  93
  94         /*-****************************************************************************************************//**
  95             @short      create a new enumeration of components
  96             @descr      You can call this method to get a new snapshot from all components of all tasks of the desktop as an enumeration.
  97
  98             @seealso    interface XEnumerationAccess
  99             @seealso    interface XEnumeration
 100             @seealso    class Desktop
 101
 102             @param      -
 103             @return     If the desktop and some components exist => a valid reference to an enumeration<BR>
 104                         An NULL-reference, other way.
 105
 106             @onerror    -
 107         *//*-*****************************************************************************************************/
 108
 109         virtual css::uno::Reference< css::container::XEnumeration > SAL_CALL createEnumeration() throw( css::uno::RuntimeException );
 110
 111         //---------------------------------------------------------------------------------------------------------
 112         //  XElementAccess
 113         //---------------------------------------------------------------------------------------------------------
 114
 115         /*-****************************************************************************************************//**
 116             @short      get the type of elements in enumeration
 117             @descr      -
 118
 119             @seealso    interface XElementAccess
 120             @seealso    class OComponentEnumeration
 121
 122             @param      -
 123             @return     The uno-type XComponent.
 124
 125             @onerror    -
 126         *//*-*****************************************************************************************************/
 127
 128         virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException );
 129
 130         /*-****************************************************************************************************//**
 131             @short      get state of componentlist of enumeration.
 132             @descr      -
 133
 134             @seealso    interface XElementAccess
 135
 136             @param      -
 137             @return     sal_True  ,if more then 0 elements exist.
 138             @return     sal_False ,otherwise.
 139
 140             @onerror    -
 141         *//*-*****************************************************************************************************/
 142
 143         virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException );
 144
 145     //-------------------------------------------------------------------------------------------------------------
 146     //  protected methods
 147     //-------------------------------------------------------------------------------------------------------------
 148
 149     protected:
 150
 151         /*-****************************************************************************************************//**
 152             @short      standard destructor
 153             @descr      This method destruct an instance of this class and clear some member.
 154                         Don't use an instance of this class as normal member. Use it dynamicly with a pointer.
 155                         We hold a weakreference to ouer owner and not to ouer superclass!
 156                         Thats the reason for a protected dtor.
 157
 158             @seealso    class Desktop
 159
 160             @param      -
 161             @return     -
 162
 163             @onerror    -
 164         *//*-*****************************************************************************************************/
 165
 166         virtual ~OComponentAccess();
 167
 168     //-------------------------------------------------------------------------------------------------------------
 169     //  private methods
 170     //-------------------------------------------------------------------------------------------------------------
 171
 172     private:
 173
 174         /*-****************************************************************************************************//**
 175             @short      recursive method (!) to collect all components of all frames from the subtree of given node
 176             @descr      This is neccessary to create the enumeration.
 177
 178             @seealso    method createEnumeration
 179
 180             @param      "xNode"        , root of subtree and start point of search
 181             @param      "seqComponents", result list of search. We cant use a return value, we search recursive
 182                                          and must collect all information.
 183             @return     -
 184
 185             @onerror    -
 186         *//*-*****************************************************************************************************/
 187
 188         void impl_collectAllChildComponents(    const   css::uno::Reference< css::frame::XFramesSupplier >&                 xNode           ,
 189                                                           css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >&   seqComponents   );
 190
 191         /*-****************************************************************************************************//**
 192             @short      get the component of a frame
 193             @descr      The component of a frame can be the window, the controller or the model.
 194
 195             @seealso    method createEnumeration
 196
 197             @param      "xFrame", frame which contains the component
 198             @return     A reference to the component of given frame.
 199
 200             @onerror    A null reference is returned.
 201         *//*-*****************************************************************************************************/
 202
 203         css::uno::Reference< css::lang::XComponent > impl_getFrameComponent( const css::uno::Reference< css::frame::XFrame >& xFrame ) const;
 204
 205     //-------------------------------------------------------------------------------------------------------------
 206     //  debug methods
 207     //  (should be private everyway!)
 208     //-------------------------------------------------------------------------------------------------------------
 209
 210         /*-****************************************************************************************************//**
 211             @short      debug-method to check incoming parameter of some other mehods of this class
 212             @descr      The following methods are used to check parameters for other methods
 213                         of this class. The return value is used directly for an ASSERT(...).
 214
 215             @seealso    ASSERTs in implementation!
 216
 217             @param      references to checking variables
 218             @return     sal_False ,on invalid parameter.
 219             @return     sal_True  ,otherwise
 220
 221             @onerror    -
 222         *//*-*****************************************************************************************************/
 223
 224     #ifdef ENABLE_ASSERTIONS
 225
 226     private:
 227
 228         static sal_Bool impldbg_checkParameter_OComponentAccessCtor( const css::uno::Reference< css::frame::XDesktop >& xOwner );
 229
 230     #endif  // #ifdef ENABLE_ASSERTIONS
 231
 232     //-------------------------------------------------------------------------------------------------------------
 233     //  variables
 234     //  (should be private everyway!)
 235     //-------------------------------------------------------------------------------------------------------------
 236
 237     private:
 238
 239         css::uno::WeakReference< css::frame::XDesktop >     m_xOwner    ;   /// weak reference to the desktop object!
 240
 241 };      //  class OComponentAccess
 242
 243 }       //  namespace framework
 244
 245 #endif  //  #ifndef __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
 246
 247 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */