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