svtools/inc/dialogcontrolling.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: dialogcontrolling.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 SVTOOLS_DIALOGCONTROLLING_HXX
  32 #define SVTOOLS_DIALOGCONTROLLING_HXX
  33
  34 #include <svtools/svtdllapi.h>
  35
  36 #include <tools/link.hxx>
  37 #include <vcl/button.hxx>
  38
  39 #include <vector>
  40 #include <boost/shared_ptr.hpp>
  41
  42 //........................................................................
  43 namespace svt
  44 {
  45 //........................................................................
  46
  47     //=====================================================================
  48     //= IWindowOperator
  49     //=====================================================================
  50     /** an abstract interface for operating on a ->Window
  51     */
  52     class SVT_DLLPUBLIC SAL_NO_VTABLE IWindowOperator
  53     {
  54     public:
  55         /** called when an event happened which should be reacted to
  56
  57             @param _rTrigger
  58                 the event which triggered the call. If the Id of the event is 0, then this is the initial
  59                 call which is made when ->_rOperateOn is added to the responsibility of the DialogController.
  60             @param _rOperateOn
  61                 the window on which to operate
  62         */
  63         virtual void operateOn( const VclWindowEvent& _rTrigger, Window& _rOperateOn ) const = 0;
  64
  65         virtual ~IWindowOperator();
  66     };
  67     typedef ::boost::shared_ptr< IWindowOperator >  PWindowOperator;
  68
  69     //=====================================================================
  70     //= IWindowEventFilter
  71     //=====================================================================
  72     /** an abstract interface for deciding whether a ->VclWindowEvent
  73         is worth paying attention to
  74     */
  75     class SVT_DLLPUBLIC SAL_NO_VTABLE IWindowEventFilter
  76     {
  77     public:
  78         virtual bool payAttentionTo( const VclWindowEvent& _rEvent ) const = 0;
  79
  80         virtual ~IWindowEventFilter();
  81     };
  82     typedef ::boost::shared_ptr< IWindowEventFilter >   PWindowEventFilter;
  83
  84     //=====================================================================
  85     //= DialogController
  86     //=====================================================================
  87     struct DialogController_Data;
  88     /** a class controlling interactions between dialog controls
  89
  90         An instance of this class listens to all events fired by a certain
  91         ->Control (more precise, a ->Window), the so-called instigator.
  92
  93         Additionally, the ->DialogController maintains a list of windows which
  94         are affected by changes in the instigator window. Let's call those the
  95         dependent windows.
  96
  97         Now, by help of an owner-provided ->IWindowEventFilter, the ->DialogController
  98         decides which events are worth attention. By help of an owner-provided
  99         ->IWindowOperator, it handles those events for all dependent windows.
 100     */
 101     class SVT_DLLPUBLIC DialogController
 102     {
 103     private:
 104         ::std::auto_ptr< DialogController_Data >    m_pImpl;
 105
 106     public:
 107         DialogController( Window& _rInstigator, const PWindowEventFilter& _pEventFilter, const PWindowOperator& _pOperator );
 108         virtual ~DialogController();
 109
 110         /** adds a window to the list of dependent windows
 111
 112             @param _rWindow
 113                 The window to add to the list of dependent windows.
 114
 115                 The caller is responsible for life-time control: The given window
 116                 must live at least as long as the ->DialogController instance does.
 117         */
 118         void    addDependentWindow( Window& _rWindow );
 119
 120         /** resets the controller so that no actions happend anymore.
 121
 122             The instances is disfunctional after this method has been called.
 123         */
 124         void    reset();
 125
 126     private:
 127         void    impl_Init();
 128         void    impl_updateAll( const VclWindowEvent& _rTriggerEvent );
 129         void    impl_update( const VclWindowEvent& _rTriggerEvent, Window& _rWindow );
 130
 131         DECL_LINK( OnWindowEvent, const VclWindowEvent* );
 132
 133     private:
 134         DialogController( const DialogController& );            // never implemented
 135         DialogController& operator=( const DialogController& ); // never implemented
 136     };
 137     typedef ::boost::shared_ptr< DialogController > PDialogController;
 138
 139     //=====================================================================
 140     //= ControlDependencyManager
 141     //=====================================================================
 142     struct ControlDependencyManager_Data;
 143     /** helper class for managing control dependencies
 144
 145         Instances of this class are intended to be held as members of a dialog/tabpage/whatever
 146         class, with easy administration of inter-control dependencies (such as "Enable
 147         control X if and only if checkbox Y is checked).
 148     */
 149     class SVT_DLLPUBLIC ControlDependencyManager
 150     {
 151     private:
 152         ::std::auto_ptr< ControlDependencyManager_Data >    m_pImpl;
 153
 154     public:
 155         ControlDependencyManager();
 156         ~ControlDependencyManager();
 157
 158         /** clears all dialog controllers previously added to the manager
 159         */
 160         void    clear();
 161
 162         /** ensures that a given window is enabled or disabled, according to the check state
 163             of a given radio button
 164             @param _rRadio
 165                 denotes the radio button whose check state is to observe
 166             @param _rDependentWindow
 167                 denotes the window which should be enabled when ->_rRadio is checked, and
 168                 disabled when it's unchecked
 169         */
 170         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow );
 171         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow1, Window& _rDependentWindow2 );
 172         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3 );
 173         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4 );
 174         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4, Window& _rDependentWindow5 );
 175         void    enableOnRadioCheck( RadioButton& _rRadio, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4, Window& _rDependentWindow5, Window& _rDependentWindow6 );
 176
 177         /** ensures that a given window is enabled or disabled, according to the mark state
 178             of a given check box
 179             @param _rBox
 180                 denotes the check box whose mark state is to observe
 181             @param _rDependentWindow
 182                 denotes the window which should be enabled when ->_rBox is marked, and
 183                 disabled when it's unmarked
 184         */
 185         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow );
 186         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow1, Window& _rDependentWindow2 );
 187         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3 );
 188         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4 );
 189         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4, Window& _rDependentWindow5 );
 190         void    enableOnCheckMark( CheckBox& _rBox, Window& _rDependentWindow1, Window& _rDependentWindow2, Window& _rDependentWindow3, Window& _rDependentWindow4, Window& _rDependentWindow5, Window& _rDependentWindow6 );
 191
 192         /** adds a non-standard controller whose functionality is not covered by the other methods
 193
 194             @param _pController
 195                 the controller to add to the manager. Must not be <NULL/>.
 196         */
 197         void    addController( const PDialogController& _pController );
 198
 199     private:
 200         ControlDependencyManager( const ControlDependencyManager& );            // never implemented
 201         ControlDependencyManager& operator=( const ControlDependencyManager& ); // never implemented
 202     };
 203
 204     //=====================================================================
 205     //= EnableOnCheck
 206     //=====================================================================
 207     /** a helper class implementing the ->IWindowOperator interface,
 208         which enables a dependent window depending on the check state of
 209         an instigator window.
 210
 211         @see DialogController
 212     */
 213     template< class CHECKABLE >
 214     class SVT_DLLPUBLIC EnableOnCheck : public IWindowOperator
 215     {
 216     public:
 217         typedef CHECKABLE   SourceType;
 218
 219     private:
 220         SourceType& m_rCheckable;
 221
 222     public:
 223         /** constructs the instance
 224
 225             @param _rCheckable
 226                 a ->Window instance which supports a boolean method IsChecked. Usually
 227                 a ->RadioButton or ->CheckBox
 228         */
 229         EnableOnCheck( SourceType& _rCheckable )
 230             :m_rCheckable( _rCheckable )
 231         {
 232         }
 233
 234         virtual void operateOn( const VclWindowEvent& /*_rTrigger*/, Window& _rOperateOn ) const
 235         {
 236             _rOperateOn.Enable( m_rCheckable.IsChecked() );
 237         }
 238     };
 239
 240     //=====================================================================
 241     //= FilterForRadioOrCheckToggle
 242     //=====================================================================
 243     /** a helper class implementing the ->IWindowEventFilter interface,
 244         which filters for radio buttons or check boxes being toggled.
 245
 246         Technically, the class simply filters for the ->VCLEVENT_RADIOBUTTON_TOGGLE
 247         and the ->VCLEVENT_CHECKBOX_TOGGLE event.
 248     */
 249     class SVT_DLLPUBLIC FilterForRadioOrCheckToggle : public IWindowEventFilter
 250     {
 251         const Window&   m_rWindow;
 252     public:
 253         FilterForRadioOrCheckToggle( const Window& _rWindow )
 254             :m_rWindow( _rWindow )
 255         {
 256         }
 257
 258         bool payAttentionTo( const VclWindowEvent& _rEvent ) const
 259         {
 260             if  (   ( _rEvent.GetWindow() == &m_rWindow )
 261                 &&  (   ( _rEvent.GetId() == VCLEVENT_RADIOBUTTON_TOGGLE )
 262                     ||  ( _rEvent.GetId() == VCLEVENT_CHECKBOX_TOGGLE )
 263                     )
 264                 )
 265                 return true;
 266             return false;
 267         }
 268     };
 269
 270     //=====================================================================
 271     //= RadioDependentEnabler
 272     //=====================================================================
 273     /** a ->DialogController derivee which enables or disables its dependent windows,
 274         depending on the check state of a radio button.
 275
 276         The usage of this class is as simple as
 277         <code>
 278         pController = new RadioDependentEnabler( m_aOptionSelectSomething );
 279         pController->addDependentWindow( m_aLabelSelection );
 280         pController->addDependentWindow( m_aListSelection );
 281         </code>
 282
 283         With this, both <code>m_aLabelSelection</code> and <code>m_aListSelection</code> will
 284         be disabled if and only <code>m_aOptionSelectSomething</code> is checked.
 285     */
 286     class SVT_DLLPUBLIC RadioDependentEnabler : public DialogController
 287     {
 288     public:
 289         RadioDependentEnabler( RadioButton& _rButton )
 290             :DialogController( _rButton,
 291                 PWindowEventFilter( new FilterForRadioOrCheckToggle( _rButton ) ),
 292                 PWindowOperator( new EnableOnCheck< RadioButton >( _rButton ) ) )
 293         {
 294         }
 295
 296         RadioDependentEnabler( CheckBox& _rBox )
 297             :DialogController( _rBox,
 298                 PWindowEventFilter( new FilterForRadioOrCheckToggle( _rBox ) ),
 299                 PWindowOperator( new EnableOnCheck< CheckBox >( _rBox ) ) )
 300         {
 301         }
 302     };
 303
 304 //........................................................................
 305 } // namespace svt
 306 //........................................................................
 307
 308 #endif // SVTOOLS_DIALOGCONTROLLING_HXX
 309