framework/inc/helper/ocomponentenumeration.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_OCOMPONENTENUMERATION_HXX
  21 #define INCLUDED_FRAMEWORK_INC_HELPER_OCOMPONENTENUMERATION_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/lang/XEventListener.hpp>
  29 #include <com/sun/star/container/XEnumeration.hpp>
  30 #include <com/sun/star/lang/XComponent.hpp>
  31
  32 #include <cppuhelper/implbase2.hxx>
  33
  34 namespace framework{
  35
  36 /*-************************************************************************************************************
  37     @short          implement a helper for a oneway enumeration of components
  38     @descr          You can step during this list only for one time! Its a snapshot.
  39                     Don't forget to release the reference. You are the owner of an instance of this implementation.
  40                     You can't use this as a baseclass. Please use it as a dynamical object for return.
  41
  42     @implements     XInterface
  43                     XTypeProvider
  44                     XEventListener
  45                     XEnumeration
  46
  47     @base           OWeakObject
  48
  49     @devstatus      ready to use
  50     @threadsafe     yes
  51 *//*-*************************************************************************************************************/
  52
  53 class OComponentEnumeration :   public ::cppu::WeakImplHelper2< ::com::sun::star::container::XEnumeration,::com::sun::star::lang::XEventListener >
  54 {
  55
  56     //  public methods
  57
  58     public:
  59
  60         //  constructor / destructor
  61
  62         /*-****************************************************************************************************
  63             @short      constructor to initialize this enumeration
  64             @descr      An enumeration is a list with oneway-access! You can get every member only for one time.
  65                         This method allow to initialize this oneway list with values.
  66             @param      "seqComponents" is a sequence of interfaces, which are components.
  67             @onerror    Do nothing and reset this object to default with an empty list.
  68         *//*-*****************************************************************************************************/
  69
  70          OComponentEnumeration( const css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >& seqComponents );
  71
  72         //  XEventListener
  73
  74         /*-****************************************************************************************************
  75             @short      last chance to release all references and free memory
  76             @descr      This method is called, if the enumeration is used completely and has no more elements.
  77                         Then we must destroy our list and release all references to other objects.
  78
  79             @seealso    interface XEventListener
  80
  81             @param      "aEvent" describe the source of this event.
  82         *//*-*****************************************************************************************************/
  83
  84         virtual void SAL_CALL disposing( const css::lang::EventObject& aEvent ) throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
  85
  86         //  XEnumeration
  87
  88         /*-****************************************************************************************************
  89             @short      check count of accessible elements of enumeration
  90             @descr      You can call this method to get information about accessible elements in future.
  91                         Elements you have already getted are not accessible!
  92
  93             @seealso    interface XEnumeration
  94             @return     sal_True  = if more elements accessible<BR>
  95                         sal_False = other way
  96
  97             @onerror    sal_False<BR>
  98                         (List is emtpy and there no accessible elements ...)
  99         *//*-*****************************************************************************************************/
 100
 101         virtual sal_Bool SAL_CALL hasMoreElements() throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 102
 103         /*-****************************************************************************************************
 104             @short      give the next element, if some exist
 105             @descr      If a call "hasMoreElements()" return true, you can get the next element of list.
 106
 107             @seealso    interface XEnumeration
 108             @return     A Reference to a component, safed in an Any-structure.
 109
 110             @onerror    If end of enumeration is arrived or there are no elements in list => a NoSuchElementException is thrown.
 111         *//*-*****************************************************************************************************/
 112
 113         virtual css::uno::Any SAL_CALL nextElement() throw( css::container::NoSuchElementException  ,
 114                                                              css::lang::WrappedTargetException      ,
 115                                                             css::uno::RuntimeException, std::exception              ) SAL_OVERRIDE;
 116
 117     //  protected methods
 118
 119     protected:
 120
 121         /*-****************************************************************************************************
 122             @short      standard destructor
 123             @descr      This method destruct an instance of this class and clear some member.
 124                         We make it protected, because its not supported to use this class as normal instance!
 125                         You must create it dynamical in memory and use a pointer.
 126         *//*-*****************************************************************************************************/
 127
 128         virtual ~OComponentEnumeration();
 129
 130         /*-****************************************************************************************************
 131             @short      reset instance to default values
 132
 133             @descr      There are two ways to delete an instance of this class.<BR>
 134                         1) delete with destructor<BR>
 135                         2) dispose from parent or factory ore ...<BR>
 136                         This method do the same for both ways! It free used memory and release references ...
 137
 138             @seealso    method dispose()
 139             @seealso    destructor ~TaskEnumeration()
 140         *//*-*****************************************************************************************************/
 141
 142         void impl_resetObject();
 143
 144
 145     private:
 146
 147     //  debug methods
 148     //  (should be private everyway!)
 149
 150         /*-****************************************************************************************************
 151             @short      debug-method to check incoming parameter of some other mehods of this class
 152             @descr      The following methods are used to check parameters for other methods
 153                         of this class. The return value is used directly for an ASSERT(...).
 154
 155             @seealso    ASSERT in implementation!
 156
 157             @param      references to checking variables
 158             @return     sal_False on invalid parameter<BR>
 159                         sal_True  otherway
 160         *//*-*****************************************************************************************************/
 161
 162     private:
 163
 164         sal_uInt32                                                              m_nPosition;   /// current position in enumeration
 165         css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >      m_seqComponents;   /// list of current components
 166
 167 };      //  class OComponentEnumeration
 168
 169 }       //  namespace framework
 170
 171 #endif // INCLUDED_FRAMEWORK_INC_HELPER_OCOMPONENTENUMERATION_HXX
 172
 173 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */