framework/inc/helper/ocomponentenumeration.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: ocomponentenumeration.hxx,v $
  10  * $Revision: 1.7 $
  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_OCOMPONENTENUMERATION_HXX_
  32 #define __FRAMEWORK_HELPER_OCOMPONENTENUMERATION_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #ifndef __FRAMEWORK_OMUTEXMEMBER_HXX_
  39 #include <threadhelp/threadhelpbase.hxx>
  40 #endif
  41 #include <macros/generic.hxx>
  42 #include <macros/xinterface.hxx>
  43 #include <macros/xtypeprovider.hxx>
  44 #include <macros/debug.hxx>
  45 #include <general.h>
  46
  47 //_________________________________________________________________________________________________________________
  48 //      interface includes
  49 //_________________________________________________________________________________________________________________
  50 #include <com/sun/star/lang/XEventListener.hpp>
  51 #include <com/sun/star/container/XEnumeration.hpp>
  52 #include <com/sun/star/lang/XComponent.hpp>
  53
  54 //_________________________________________________________________________________________________________________
  55 //      other includes
  56 //_________________________________________________________________________________________________________________
  57 #include <cppuhelper/implbase2.hxx>
  58
  59 //_________________________________________________________________________________________________________________
  60 //      namespace
  61 //_________________________________________________________________________________________________________________
  62
  63 namespace framework{
  64
  65 //_________________________________________________________________________________________________________________
  66 //      exported const
  67 //_________________________________________________________________________________________________________________
  68
  69 //_________________________________________________________________________________________________________________
  70 //      exported definitions
  71 //_________________________________________________________________________________________________________________
  72
  73 /*-************************************************************************************************************//**
  74     @short                      implement a helper for a oneway enumeration of components
  75     @descr                      You can step during this list only for one time! Its a snapshot.
  76                     Don't forget to release the reference. You are the owner of an instance of this implementation.
  77                     You cant use this as a baseclass. Please use it as a dynamical object for return.
  78
  79     @implements         XInterface
  80                     XTypeProvider
  81                     XEventListener
  82                     XEnumeration
  83
  84     @base                       ThreadHelpBase
  85                     OWeakObject
  86
  87     @devstatus          ready to use
  88     @threadsafe         yes
  89 *//*-*************************************************************************************************************/
  90
  91 class OComponentEnumeration     :       public ThreadHelpBase               ,
  92                                 public ::cppu::WeakImplHelper2< ::com::sun::star::container::XEnumeration,::com::sun::star::lang::XEventListener >
  93 {
  94     //-------------------------------------------------------------------------------------------------------------
  95     //  public methods
  96     //-------------------------------------------------------------------------------------------------------------
  97
  98     public:
  99
 100         //---------------------------------------------------------------------------------------------------------
 101         //      constructor / destructor
 102         //---------------------------------------------------------------------------------------------------------
 103
 104         /*-****************************************************************************************************//**
 105             @short              constructor to initialize this enumeration
 106             @descr              An enumeration is a list with oneway-access! You can get every member only for one time.
 107                         This method allow to initialize this oneway list with values.
 108
 109             @seealso    -
 110
 111             @param              "seqComponents" is a sequence of interfaces, which are components.
 112             @return             -
 113
 114             @onerror    Do nothing and reset this object to default with an empty list.
 115         *//*-*****************************************************************************************************/
 116
 117          OComponentEnumeration( const css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >& seqComponents );
 118
 119         //---------------------------------------------------------------------------------------------------------
 120         //      XEventListener
 121         //---------------------------------------------------------------------------------------------------------
 122
 123         /*-****************************************************************************************************//**
 124             @short              last chance to release all references and free memory
 125             @descr              This method is called, if the enumeration is used completly and has no more elements.
 126                         Then we must destroy ouer list and release all references to other objects.
 127
 128             @seealso    interface XEventListener
 129
 130             @param              "aEvent" describe the source of this event.
 131             @return             -
 132
 133             @onerror    -
 134         *//*-*****************************************************************************************************/
 135
 136         virtual void SAL_CALL disposing( const css::lang::EventObject& aEvent ) throw( css::uno::RuntimeException );
 137
 138         //---------------------------------------------------------------------------------------------------------
 139         //      XEnumeration
 140         //---------------------------------------------------------------------------------------------------------
 141
 142         /*-****************************************************************************************************//**
 143             @short              check count of accessible elements of enumeration
 144             @descr              You can call this method to get information about accessible elements in future.
 145                         Elements you have already getted are not accessible!
 146
 147             @seealso    interface XEnumeration
 148
 149             @param              -
 150             @return             sal_True  = if more elements accessible<BR>
 151                         sal_False = other way
 152
 153             @onerror    sal_False<BR>
 154                         (List is emtpy and there no accessible elements ...)
 155         *//*-*****************************************************************************************************/
 156
 157         virtual sal_Bool SAL_CALL hasMoreElements() throw( css::uno::RuntimeException );
 158
 159         /*-****************************************************************************************************//**
 160             @short              give the next element, if some exist
 161             @descr              If a call "hasMoreElements()" return true, you can get the next element of list.
 162
 163             @seealso    interface XEnumeration
 164
 165             @param              -
 166             @return             A Reference to a component, safed in an Any-structure.
 167
 168             @onerror    If end of enumeration is arrived or there are no elements in list => a NoSuchElementException is thrown.
 169         *//*-*****************************************************************************************************/
 170
 171         virtual css::uno::Any SAL_CALL nextElement() throw(     css::container::NoSuchElementException  ,
 172                                                              css::lang::WrappedTargetException          ,
 173                                                             css::uno::RuntimeException                          );
 174
 175     //-------------------------------------------------------------------------------------------------------------
 176     //  protected methods
 177     //-------------------------------------------------------------------------------------------------------------
 178
 179     protected:
 180
 181         /*-****************************************************************************************************//**
 182             @short              standard destructor
 183             @descr              This method destruct an instance of this class and clear some member.
 184                         We make it protected, because its not supported to use this class as normal instance!
 185                         You must create it dynamical in memory and use a pointer.
 186
 187             @seealso    -
 188
 189             @param              -
 190             @return             -
 191
 192             @onerror    -
 193         *//*-*****************************************************************************************************/
 194
 195         virtual ~OComponentEnumeration();
 196
 197         /*-****************************************************************************************************//**
 198             @short              reset instance to default values
 199
 200             @descr              There are two ways to delete an instance of this class.<BR>
 201                         1) delete with destructor<BR>
 202                         2) dispose from parent or factory ore ...<BR>
 203                         This method do the same for both ways! It free used memory and release references ...
 204
 205             @seealso    method dispose()
 206             @seealso    destructor ~TaskEnumeration()
 207
 208             @param              -
 209
 210             @return             -
 211
 212             @onerror    -
 213         *//*-*****************************************************************************************************/
 214
 215         virtual void impl_resetObject();
 216
 217     //-------------------------------------------------------------------------------------------------------------
 218     //  private methods
 219     //-------------------------------------------------------------------------------------------------------------
 220
 221     private:
 222
 223     //-------------------------------------------------------------------------------------------------------------
 224     //  debug methods
 225     //  (should be private everyway!)
 226     //-------------------------------------------------------------------------------------------------------------
 227
 228         /*-****************************************************************************************************//**
 229             @short              debug-method to check incoming parameter of some other mehods of this class
 230             @descr              The following methods are used to check parameters for other methods
 231                         of this class. The return value is used directly for an ASSERT(...).
 232
 233             @seealso    ASSERT in implementation!
 234
 235             @param              references to checking variables
 236             @return             sal_False on invalid parameter<BR>
 237                         sal_True  otherway
 238
 239             @onerror    -
 240         *//*-*****************************************************************************************************/
 241
 242     #ifdef ENABLE_ASSERTIONS
 243
 244     private:
 245
 246         static sal_Bool impldbg_checkParameter_OComponentEnumerationCtor        (       const   css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >&     seqComponents   );
 247         static sal_Bool impldbg_checkParameter_disposing                                        (       const   css::lang::EventObject&                                                                                         aEvent                  );
 248
 249     #endif      // #ifdef ENABLE_ASSERTIONS
 250
 251     //-------------------------------------------------------------------------------------------------------------
 252     //  variables
 253     //  (should be private everyway!)
 254     //-------------------------------------------------------------------------------------------------------------
 255
 256     private:
 257
 258         sal_uInt32                                                                                                                              m_nPosition                     ;       /// current position in enumeration
 259         css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >              m_seqComponents         ;       /// list of current components
 260
 261 };              //      class OComponentEnumeration
 262
 263 }               //      namespace framework
 264
 265 #endif  //      #ifndef __FRAMEWORK_HELPER_OCOMPONENTENUMERATION_HXX_