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