framework/inc/helper/statusindicatorfactory.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: statusindicatorfactory.hxx,v $
  10  * $Revision: 1.15 $
  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_STATUSINDICATORFACTORY_HXX_
  32 #define __FRAMEWORK_HELPER_STATUSINDICATORFACTORY_HXX_
  33
  34 // Attention: stl headers must(!) be included at first. Otherwhise it can make trouble
  35 // with solaris headers ...
  36 #include <vector>
  37
  38 //_______________________________________________
  39 // include files of own module
  40 #include <helper/wakeupthread.hxx>
  41 #include <threadhelp/threadhelpbase.hxx>
  42 #include <macros/xinterface.hxx>
  43 #include <macros/xtypeprovider.hxx>
  44 #include <macros/xserviceinfo.hxx>
  45 #include <macros/debug.hxx>
  46 #include <macros/generic.hxx>
  47 #include <general.h>
  48
  49 //_______________________________________________
  50 // include uno interfaces
  51 #include <com/sun/star/lang/XTypeProvider.hpp>
  52 #include <com/sun/star/lang/XServiceInfo.hpp>
  53 #include <com/sun/star/lang/XInitialization.hpp>
  54 #include <com/sun/star/lang/XEventListener.hpp>
  55 #include <com/sun/star/task/XStatusIndicatorFactory.hpp>
  56 #include <com/sun/star/task/XStatusIndicator.hpp>
  57 #include <com/sun/star/awt/XWindow.hpp>
  58 #include <com/sun/star/awt/XWindowListener.hpp>
  59 #include <com/sun/star/lang/EventObject.hpp>
  60 #include <com/sun/star/awt/WindowEvent.hpp>
  61 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  62 #include <com/sun/star/frame/XFrame.hpp>
  63
  64 #ifndef _COM_SUN_STAR_URTIL_XUPDATABLE_HPP_
  65 #include <com/sun/star/util/XUpdatable.hpp>
  66 #endif
  67
  68 //_______________________________________________
  69 // include others
  70 #include <vcl/status.hxx>
  71 #include <cppuhelper/weak.hxx>
  72 #include <osl/thread.hxx>
  73
  74 //_______________________________________________
  75 // namespace
  76
  77 namespace framework{
  78
  79 //_______________________________________________
  80 // definitions
  81
  82 //===============================================
  83 /**
  84     @descr  This struct hold some informations about all currently running progress proccesses.
  85             Because the can be used on a stack, we must cache her states but must paint only
  86             the top most one.
  87  */
  88 struct IndicatorInfo
  89 {
  90     //-------------------------------------------
  91     // member
  92     public:
  93
  94         /** @short  points to the indicator child, where we hold its states
  95                     alive here. */
  96         css::uno::Reference< css::task::XStatusIndicator > m_xIndicator;
  97
  98         /** @short  the last set text for this indicator */
  99         ::rtl::OUString m_sText;
 100
 101         /** @short  the max range for this indicator. */
 102         sal_Int32 m_nRange;
 103
 104         /** @short  the last set value for this indicator */
 105         sal_Int32 m_nValue;
 106
 107     //-------------------------------------------
 108     // interface
 109     public:
 110
 111         //---------------------------------------
 112         /** @short  initialize new instance of this class
 113
 114             @param  xIndicator
 115                     the new child indiactor of our factory.
 116
 117             @param  sText
 118                     its initial text.
 119
 120             @param  nRange
 121                     the max range for this indicator.
 122          */
 123         IndicatorInfo(const css::uno::Reference< css::task::XStatusIndicator >& xIndicator,
 124                       const ::rtl::OUString&                                    sText     ,
 125                             sal_Int32                                           nRange    )
 126         {
 127             m_xIndicator = xIndicator;
 128             m_sText      = sText     ;
 129             m_nRange     = nRange    ;
 130             m_nValue     = 0         ;
 131         }
 132
 133         //---------------------------------------
 134         /** @short  Don't forget to free used references!
 135          */
 136         ~IndicatorInfo()
 137         {
 138             m_xIndicator.clear();
 139         }
 140
 141         //---------------------------------------------------------------------------------------------------------
 142         /** @short  Used to locate an info struct inside a stl structure ...
 143
 144             @descr  The indicator object itself is used as key. Its values
 145                     are not interesting then. Because mor then one child
 146                     indicator can use the same values ...
 147          */
 148         sal_Bool operator==(const css::uno::Reference< css::task::XStatusIndicator >& xIndicator)
 149         {
 150             return (m_xIndicator == xIndicator);
 151         }
 152 };
 153 /*
 154     //---------------------------------------------------------------------------------------------------------
 155     // norm nValue to fit range of 0..100%
 156     sal_Int32 calcPercentage()
 157     {
 158     return ::std::min( (( m_nValue * 100 )/ ::std::max( m_nRange, (sal_Int32)1 ) ), (sal_Int32)100 );
 159     }
 160 */
 161
 162 //===============================================
 163 /** @descr  Define a lits of child indicator objects and her data. */
 164 typedef ::std::vector< IndicatorInfo > IndicatorStack;
 165
 166 //===============================================
 167 /** @short          implement a factory service to create new status indicator objects
 168
 169     @descr                      Internaly it uses:
 170                     - a vcl based
 171                     - or an uno based and by the frame layouted
 172                     progress implementation.
 173
 174                     This factory create different indicators and control his access
 175                     to a shared output device! Only the last activated component
 176                     can write his state to this device. All other requests will be
 177                     cached only.
 178
 179     @devstatus          ready to use
 180     @threadsafe     yes
 181  */
 182 class StatusIndicatorFactory : public  css::lang::XTypeProvider
 183                              , public  css::lang::XServiceInfo
 184                              , public  css::lang::XInitialization
 185                              , public  css::task::XStatusIndicatorFactory
 186                              , public  css::util::XUpdatable
 187                              , private ThreadHelpBase
 188                              , public  ::cppu::OWeakObject                   // => XInterface
 189 {
 190     //-------------------------------------------
 191     // member
 192     private:
 193
 194         /** stack with all current indicator childs. */
 195         IndicatorStack m_aStack;
 196
 197         /** uno service manager to create own needed uno resources. */
 198         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 199
 200         /** most active indicator child, which could work with our shared indicator window only. */
 201         css::uno::Reference< css::task::XStatusIndicator > m_xActiveChild;
 202
 203         /** used to show the progress on the frame (layouted!) or
 204             as a plugged vcl window. */
 205         css::uno::Reference< css::task::XStatusIndicator > m_xProgress;
 206
 207         /** points to the frame, where we show the progress (in case
 208             m_xProgress points to a frame progress. */
 209         css::uno::WeakReference< css::frame::XFrame > m_xFrame;
 210
 211         /** points to an outside window, where we show the progress (in case
 212             we are plugged into such window). */
 213         css::uno::WeakReference< css::awt::XWindow > m_xPluggWindow;
 214
 215         /** Notify us if a fix time is over. We use it to implement an
 216             intelligent "Reschedule" ... */
 217         WakeUpThread* m_pWakeUp;
 218
 219         /** Our WakeUpThread calls us in our interface method "XUpdatable::update().
 220             There we set this member m_bAllowReschedule to TRUE. Next time if our impl_reschedule()
 221             method is called, we know, that an Application::Reschedule() should be made.
 222             Because the last made Reschedule can be was taken long time ago ... may be.*/
 223         sal_Bool m_bAllowReschedule;
 224
 225         /** enable/disable automatic showing of our parent window. */
 226         sal_Bool m_bAllowParentShow;
 227
 228         /** enable/disable rescheduling. Default=enabled*/
 229         sal_Bool m_bDisableReschedule;
 230
 231         /** prevent recursive calling of Application::Reschedule(). */
 232         static sal_Int32 m_nInReschedule;
 233
 234         /** time where there last start call was made. */
 235         sal_Int32 m_nStartTime;
 236
 237     //-------------------------------------------
 238     // interface
 239
 240     public:
 241
 242         //---------------------------------------
 243         // ctor
 244         StatusIndicatorFactory(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR);
 245
 246         //---------------------------------------
 247         // XInterface, XTypeProvider, XServiceInfo
 248         FWK_DECLARE_XINTERFACE
 249         FWK_DECLARE_XTYPEPROVIDER
 250         DECLARE_XSERVICEINFO
 251
 252         //---------------------------------------
 253         // XInitialization
 254         virtual void SAL_CALL initialize(const css::uno::Sequence< css::uno::Any >& lArguments)
 255             throw(css::uno::Exception       ,
 256                   css::uno::RuntimeException);
 257
 258         //---------------------------------------
 259         // XStatusIndicatorFactory
 260         virtual css::uno::Reference< css::task::XStatusIndicator > SAL_CALL createStatusIndicator()
 261             throw(css::uno::RuntimeException);
 262
 263         //---------------------------------------
 264         // XUpdatable
 265         virtual void SAL_CALL update()
 266             throw(css::uno::RuntimeException);
 267
 268         //---------------------------------------
 269         // similar (XStatusIndicator)
 270         virtual void start(const css::uno::Reference< css::task::XStatusIndicator >& xChild,
 271                            const ::rtl::OUString&                                    sText ,
 272                                  sal_Int32                                           nRange);
 273
 274         virtual void SAL_CALL reset(const css::uno::Reference< css::task::XStatusIndicator >& xChild);
 275
 276         virtual void SAL_CALL end(const css::uno::Reference< css::task::XStatusIndicator >& xChild);
 277
 278         virtual void SAL_CALL setText(const css::uno::Reference< css::task::XStatusIndicator >& xChild,
 279                                       const ::rtl::OUString&                                    sText );
 280
 281         virtual void SAL_CALL setValue(const css::uno::Reference< css::task::XStatusIndicator >& xChild,
 282                                              sal_Int32                                           nValue);
 283
 284     //-------------------------------------------
 285     // specials
 286
 287     protected:
 288
 289         virtual ~StatusIndicatorFactory();
 290
 291     //-------------------------------------------
 292     // helper
 293     private:
 294
 295         /** @short  show the parent window of this progress ...
 296                     if it's allowed to do so.
 297
 298
 299             @descr  By default we show the parent window automaticly
 300                     if this progress is used.
 301                     If that isn't a valid operation, the user of this
 302                     progress can suppress this feature by initializaing
 303                     us with a special parameter.
 304
 305             @seealso    initialize()
 306          */
 307         void implts_makeParentVisibleIfAllowed();
 308
 309         /** @short  creates a new internal used progress.
 310             @descr  This factory does not paint the progress itself.
 311                     It uses helper for that. They can be vcl based or
 312                     layouted by the frame and provided as an uno interface.
 313          */
 314         void impl_createProgress();
 315
 316         /** @short  shows the internal used progress.
 317             @descr  This factory does not paint the progress itself.
 318                     It uses helper for that. They can be vcl based or
 319                     layouted by the frame and provided as an uno interface.
 320          */
 321         void impl_showProgress();
 322
 323         /** @short  hides the internal used progress.
 324             @descr  This factory does not paint the progress itself.
 325                     It uses helper for that. They can be vcl based or
 326                     layouted by the frame and provided as an uno interface.
 327          */
 328         void impl_hideProgress();
 329
 330         /** @short  try to "share the current thread in an intelligent manner" :-)
 331
 332             @param  Overwrites our algorithm for Reschedule and force it to be shure
 333                     that our progress was painted right.
 334          */
 335         void impl_reschedule(sal_Bool bForceUpdate);
 336
 337         void impl_startWakeUpThread();
 338         void impl_stopWakeUpThread();
 339
 340 }; // class StatusIndicatorFactory
 341
 342 } // namespace framework
 343
 344 #endif // #ifndef __FRAMEWORK_HELPER_STATUSINDICATORFACTORY_HXX_