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