framework/inc/helper/otasksaccess.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: otasksaccess.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_OTASKSACCESS_HXX_
  32 #define __FRAMEWORK_HELPER_OTASKSACCESS_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <classes/framecontainer.hxx>
  39 #include <threadhelp/threadhelpbase.hxx>
  40 #include <macros/generic.hxx>
  41 #include <macros/xinterface.hxx>
  42 #include <macros/xtypeprovider.hxx>
  43 #include <macros/debug.hxx>
  44
  45 //_________________________________________________________________________________________________________________
  46 //      interface includes
  47 //_________________________________________________________________________________________________________________
  48 #include <com/sun/star/container/XEnumerationAccess.hpp>
  49 #include <com/sun/star/container/XElementAccess.hpp>
  50 #include <com/sun/star/container/XEnumeration.hpp>
  51 #include <com/sun/star/frame/XDesktop.hpp>
  52
  53 //_________________________________________________________________________________________________________________
  54 //      other includes
  55 //_________________________________________________________________________________________________________________
  56 #include <cppuhelper/weak.hxx>
  57 #include <cppuhelper/weakref.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 XEnumerationAccess interface as helper to create many oneway enumeration of tasks
  75     @descr                      We share mutex and framecontainer with ouer owner and have full access to his child tasks.
  76                     (Ouer owner can be the Desktop only!) We create oneway enumerations on demand. These "lists"
  77                     can be used for one time only. Step during the list from first to last element.
  78                     (The type of created enumerations is OTasksEnumeration.)
  79
  80     @implements         XInterface
  81                     XEnumerationAccess
  82                     XElementAccess
  83
  84     @base                       OWeakObject
  85
  86     @devstatus          deprecated
  87 *//*-*************************************************************************************************************/
  88
  89 class OTasksAccess      :       public css::lang::XTypeProvider                         ,
  90                         public css::container::XEnumerationAccess       ,       // => XElementAccess
  91                         private ThreadHelpBase                      ,
  92                         public ::cppu::OWeakObject
  93 {
  94     //-------------------------------------------------------------------------------------------------------------
  95     //  public methods
  96     //-------------------------------------------------------------------------------------------------------------
  97
  98     public:
  99
 100         //---------------------------------------------------------------------------------------------------------
 101         //      constructor / destructor
 102         //---------------------------------------------------------------------------------------------------------
 103
 104         /*-****************************************************************************************************//**
 105             @short              constructor to initialize this instance
 106             @descr              A desktop will create an enumeration-access-object. An enumeration is a oneway-list and a
 107                         snapshot of the tasklist of current tasks of desktop.
 108                         But we need a instance to create more then one enumerations to the same tasklist!
 109
 110             @seealso    class Desktop
 111             @seealso    class OTasksEnumeration
 112
 113             @param              "xOwner" is a reference to ouer owner and must be the desktop!
 114             @param              "pTasks" is a pointer to the taskcontainer of the desktop. We need it to create a new enumeration.
 115             @return             -
 116
 117             @onerror    Do nothing and reset this object to default with an empty list.
 118         *//*-*****************************************************************************************************/
 119
 120          OTasksAccess(  const   css::uno::Reference< css::frame::XDesktop >&    xOwner  ,
 121                                 FrameContainer*                                 pTasks  );
 122
 123         //---------------------------------------------------------------------------------------------------------
 124         //      XInterface
 125         //---------------------------------------------------------------------------------------------------------
 126
 127         DECLARE_XINTERFACE
 128         DECLARE_XTYPEPROVIDER
 129
 130         //---------------------------------------------------------------------------------------------------------
 131         //      XEnumerationAccess
 132         //---------------------------------------------------------------------------------------------------------
 133
 134         /*-****************************************************************************************************//**
 135             @short              create a new enumeration of tasks
 136             @descr              You can call this method to get a new snapshot to all tasks of the desktop as an enumeration.
 137
 138             @seealso    interface XEnumerationAccess
 139             @seealso    interface XEnumeration
 140             @seealso    class Desktop
 141
 142             @param              -
 143             @return             If the desktop and some tasks exist => a valid reference to an enumeration<BR>
 144                         An NULL-reference, other way.
 145
 146             @onerror    -
 147         *//*-*****************************************************************************************************/
 148
 149         virtual css::uno::Reference< css::container::XEnumeration > SAL_CALL createEnumeration() throw( css::uno::RuntimeException );
 150
 151         //---------------------------------------------------------------------------------------------------------
 152         //      XElementAccess
 153         //---------------------------------------------------------------------------------------------------------
 154
 155         /*-****************************************************************************************************//**
 156             @short              get the type of elements in enumeration
 157             @descr              -
 158
 159             @seealso    interface XElementAccess
 160             @seealso    class TasksEnumeration
 161
 162             @param              -
 163             @return             The uno-type XTask.
 164
 165             @onerror    -
 166         *//*-*****************************************************************************************************/
 167
 168         virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException );
 169
 170         /*-****************************************************************************************************//**
 171             @short              get state of tasklist of enumeration.
 172             @descr              -
 173
 174             @seealso    interface XElementAccess
 175
 176             @param              -
 177             @return             sal_True  ,if more then 0 elements exist.
 178             @return             sal_False ,otherwise.
 179
 180             @onerror    -
 181         *//*-*****************************************************************************************************/
 182
 183         virtual sal_Bool SAL_CALL hasElements() throw( 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                         Don't use an instance of this class as normal member. Use it dynamicly with a pointer.
 195                         We hold a weakreference to ouer owner and not to ouer superclass!
 196                         Thats the reason for a protected dtor.
 197
 198             @seealso    class Desktop
 199
 200             @param              -
 201             @return             -
 202
 203             @onerror    -
 204         *//*-*****************************************************************************************************/
 205
 206         virtual ~OTasksAccess();
 207
 208     //-------------------------------------------------------------------------------------------------------------
 209     //  private methods
 210     //-------------------------------------------------------------------------------------------------------------
 211
 212     private:
 213
 214     //-------------------------------------------------------------------------------------------------------------
 215     //  debug methods
 216     //  (should be private everyway!)
 217     //-------------------------------------------------------------------------------------------------------------
 218
 219         /*-****************************************************************************************************//**
 220             @short              debug-method to check incoming parameter of some other mehods of this class
 221             @descr              The following methods are used to check parameters for other methods
 222                         of this class. The return value is used directly for an ASSERT(...).
 223
 224             @seealso    ASSERTs in implementation!
 225
 226             @param              references to checking variables
 227             @return             sal_False ,on invalid parameter.
 228             @return             sal_True  ,otherwise
 229
 230             @onerror    -
 231         *//*-*****************************************************************************************************/
 232
 233     #ifdef ENABLE_ASSERTIONS
 234
 235     private:
 236
 237         static sal_Bool impldbg_checkParameter_OTasksAccessCtor(        const   css::uno::Reference< css::frame::XDesktop >&    xOwner  ,
 238                                                                             FrameContainer*                                 pTasks  );
 239
 240     #endif      // #ifdef ENABLE_ASSERTIONS
 241
 242     //-------------------------------------------------------------------------------------------------------------
 243     //  variables
 244     //  (should be private everyway!)
 245     //-------------------------------------------------------------------------------------------------------------
 246
 247     private:
 248
 249         css::uno::WeakReference< css::frame::XDesktop >         m_xOwner                        ;       /// weak reference to the desktop object!
 250         FrameContainer*                                                                         m_pTasks                        ;       /// pointer to list of current tasks on desktop (is a member of class Desktop!)
 251                                                                                     /// This pointer is valid only, if weakreference can be locked.
 252
 253 };              //      class OTasksAccess
 254
 255 }               //      namespace framework
 256
 257 #endif  //      #ifndef __FRAMEWORK_HELPER_OTASKSACCESS_HXX_