framework/inc/helper/ocomponentaccess.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ocomponentaccess.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
  32 #define __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <threadhelp/threadhelpbase.hxx>
  39 #include <macros/generic.hxx>
  40 #include <macros/xinterface.hxx>
  41 #include <macros/xtypeprovider.hxx>
  42 #include <macros/debug.hxx>
  43 #include <general.h>
  44
  45 //_________________________________________________________________________________________________________________
  46 //      interface includes
  47 //_________________________________________________________________________________________________________________
  48 #include <com/sun/star/frame/XFramesSupplier.hpp>
  49 #include <com/sun/star/container/XEnumerationAccess.hpp>
  50 #include <com/sun/star/container/XElementAccess.hpp>
  51 #include <com/sun/star/container/XEnumeration.hpp>
  52 #include <com/sun/star/frame/XDesktop.hpp>
  53 #include <com/sun/star/lang/XComponent.hpp>
  54
  55 //_________________________________________________________________________________________________________________
  56 //      other includes
  57 //_________________________________________________________________________________________________________________
  58 #include <cppuhelper/implbase1.hxx>
  59 #include <cppuhelper/weakref.hxx>
  60
  61 //_________________________________________________________________________________________________________________
  62 //      namespace
  63 //_________________________________________________________________________________________________________________
  64
  65 namespace framework{
  66
  67 //_________________________________________________________________________________________________________________
  68 //      exported const
  69 //_________________________________________________________________________________________________________________
  70
  71 //_________________________________________________________________________________________________________________
  72 //      exported definitions
  73 //_________________________________________________________________________________________________________________
  74
  75 /*-************************************************************************************************************//**
  76     @short                      implement XEnumerationAccess interface as helper to create many oneway enumeration of components
  77     @descr                      We share mutex and framecontainer with ouer owner and have full access to his child tasks.
  78                     (Ouer owner can be the Desktop only!) We create oneway enumerations on demand. These "lists"
  79                     can be used for one time only. Step during the list from first to last element.
  80                     (The type of created enumerations is OComponentEnumeration.)
  81
  82     @implements         XInterface
  83                     XTypeProvider
  84                     XEnumerationAccess
  85                     XElementAccess
  86
  87     @base           ThreadHelpBase
  88                     OWeakObject
  89
  90     @devstatus          ready to use
  91 *//*-*************************************************************************************************************/
  92
  93 class OComponentAccess  :       private ThreadHelpBase                      ,   // Must be the first of baseclasses - Is neccessary for right initialization of objects!
  94                             public ::cppu::WeakImplHelper1< ::com::sun::star::container::XEnumerationAccess >
  95 {
  96     //-------------------------------------------------------------------------------------------------------------
  97     //  public methods
  98     //-------------------------------------------------------------------------------------------------------------
  99
 100     public:
 101
 102         //---------------------------------------------------------------------------------------------------------
 103         //      constructor / destructor
 104         //---------------------------------------------------------------------------------------------------------
 105
 106         /*-****************************************************************************************************//**
 107             @short              constructor to initialize this instance
 108             @descr              A desktop will create an enumeration-access-object. An enumeration is a oneway-list and a
 109                         snapshot of the components of current tasks under the desktop.
 110                         But we need a instance to create more then one enumerations at different times!
 111
 112             @seealso    class Desktop
 113             @seealso    class OComponentEnumeration
 114
 115             @param              "xOwner" is a reference to ouer owner and must be the desktop!
 116             @return             -
 117
 118             @onerror    Do nothing and reset this object to default with an empty list.
 119         *//*-*****************************************************************************************************/
 120
 121         OComponentAccess( const css::uno::Reference< css::frame::XDesktop >& xOwner );
 122
 123         //---------------------------------------------------------------------------------------------------------
 124         //      XEnumerationAccess
 125         //---------------------------------------------------------------------------------------------------------
 126
 127         /*-****************************************************************************************************//**
 128             @short              create a new enumeration of components
 129             @descr              You can call this method to get a new snapshot from all components of all tasks of the desktop as an enumeration.
 130
 131             @seealso    interface XEnumerationAccess
 132             @seealso    interface XEnumeration
 133             @seealso    class Desktop
 134
 135             @param              -
 136             @return             If the desktop and some components exist => a valid reference to an enumeration<BR>
 137                         An NULL-reference, other way.
 138
 139             @onerror    -
 140         *//*-*****************************************************************************************************/
 141
 142         virtual css::uno::Reference< css::container::XEnumeration > SAL_CALL createEnumeration() throw( css::uno::RuntimeException );
 143
 144         //---------------------------------------------------------------------------------------------------------
 145         //      XElementAccess
 146         //---------------------------------------------------------------------------------------------------------
 147
 148         /*-****************************************************************************************************//**
 149             @short              get the type of elements in enumeration
 150             @descr              -
 151
 152             @seealso    interface XElementAccess
 153             @seealso    class OComponentEnumeration
 154
 155             @param              -
 156             @return             The uno-type XComponent.
 157
 158             @onerror    -
 159         *//*-*****************************************************************************************************/
 160
 161         virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException );
 162
 163         /*-****************************************************************************************************//**
 164             @short              get state of componentlist of enumeration.
 165             @descr              -
 166
 167             @seealso    interface XElementAccess
 168
 169             @param              -
 170             @return             sal_True  ,if more then 0 elements exist.
 171             @return             sal_False ,otherwise.
 172
 173             @onerror    -
 174         *//*-*****************************************************************************************************/
 175
 176         virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException );
 177
 178     //-------------------------------------------------------------------------------------------------------------
 179     //  protected methods
 180     //-------------------------------------------------------------------------------------------------------------
 181
 182     protected:
 183
 184         /*-****************************************************************************************************//**
 185             @short              standard destructor
 186             @descr              This method destruct an instance of this class and clear some member.
 187                         Don't use an instance of this class as normal member. Use it dynamicly with a pointer.
 188                         We hold a weakreference to ouer owner and not to ouer superclass!
 189                         Thats the reason for a protected dtor.
 190
 191             @seealso    class Desktop
 192
 193             @param              -
 194             @return             -
 195
 196             @onerror    -
 197         *//*-*****************************************************************************************************/
 198
 199         virtual ~OComponentAccess();
 200
 201     //-------------------------------------------------------------------------------------------------------------
 202     //  private methods
 203     //-------------------------------------------------------------------------------------------------------------
 204
 205     private:
 206
 207         /*-****************************************************************************************************//**
 208             @short              recursive method (!) to collect all components of all frames from the subtree of given node
 209             @descr              This is neccessary to create the enumeration.
 210
 211             @seealso    method createEnumeration
 212
 213             @param              "xNode"        , root of subtree and start point of search
 214             @param              "seqComponents", result list of search. We cant use a return value, we search recursive
 215                                          and must collect all informations.
 216             @return             -
 217
 218             @onerror    -
 219         *//*-*****************************************************************************************************/
 220
 221         void impl_collectAllChildComponents(    const   css::uno::Reference< css::frame::XFramesSupplier >&                                     xNode                   ,
 222                                                           css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >&   seqComponents   );
 223
 224         /*-****************************************************************************************************//**
 225             @short              get the component of a frame
 226             @descr              The component of a frame can be the window, the controller or the model.
 227
 228             @seealso    method createEnumeration
 229
 230             @param              "xFrame", frame which contains the component
 231             @return             A reference to the component of given frame.
 232
 233             @onerror    A null reference is returned.
 234         *//*-*****************************************************************************************************/
 235
 236         css::uno::Reference< css::lang::XComponent > impl_getFrameComponent( const css::uno::Reference< css::frame::XFrame >& xFrame ) const;
 237
 238     //-------------------------------------------------------------------------------------------------------------
 239     //  debug methods
 240     //  (should be private everyway!)
 241     //-------------------------------------------------------------------------------------------------------------
 242
 243         /*-****************************************************************************************************//**
 244             @short              debug-method to check incoming parameter of some other mehods of this class
 245             @descr              The following methods are used to check parameters for other methods
 246                         of this class. The return value is used directly for an ASSERT(...).
 247
 248             @seealso    ASSERTs in implementation!
 249
 250             @param              references to checking variables
 251             @return             sal_False ,on invalid parameter.
 252             @return             sal_True  ,otherwise
 253
 254             @onerror    -
 255         *//*-*****************************************************************************************************/
 256
 257     #ifdef ENABLE_ASSERTIONS
 258
 259     private:
 260
 261         static sal_Bool impldbg_checkParameter_OComponentAccessCtor( const css::uno::Reference< css::frame::XDesktop >& xOwner );
 262
 263     #endif      // #ifdef ENABLE_ASSERTIONS
 264
 265     //-------------------------------------------------------------------------------------------------------------
 266     //  variables
 267     //  (should be private everyway!)
 268     //-------------------------------------------------------------------------------------------------------------
 269
 270     private:
 271
 272         css::uno::WeakReference< css::frame::XDesktop >     m_xOwner    ;   /// weak reference to the desktop object!
 273
 274 };              //      class OComponentAccess
 275
 276 }               //      namespace framework
 277
 278 #endif  //      #ifndef __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_