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