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