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         /** ensures that a given window is enabled or disabled, according to the check state
 142             of a given radio button
 143             @param _rRadio
 144                 denotes the radio button whose check state is to observe
 145             @param _rDependentWindow
 146                 denotes the window which should be enabled when ->_rRadio is checked, and
 147                 disabled when it's unchecked
 148         */
 149         void    enableOnRadioCheck( RadioButton& _rRadio, vcl::Window& _rDependentWindow );
 150         void    enableOnRadioCheck( RadioButton& _rRadio, vcl::Window& _rDependentWindow1, vcl::Window& _rDependentWindow2 );
 151         void    enableOnRadioCheck( RadioButton& _rRadio, vcl::Window& _rDependentWindow1, vcl::Window& _rDependentWindow2, vcl::Window& _rDependentWindow3 );
 152         void    enableOnRadioCheck( RadioButton& _rRadio, vcl::Window& _rDependentWindow1, vcl::Window& _rDependentWindow2, vcl::Window& _rDependentWindow3, vcl::Window& _rDependentWindow4, vcl::Window& _rDependentWindow5 );
 153
 154         /** adds a non-standard controller whose functionality is not covered by the other methods
 155
 156             @param _pController
 157                 the controller to add to the manager. Must not be <NULL/>.
 158         */
 159         void    addController( const std::shared_ptr<DialogController>& _pController );
 160
 161     private:
 162         ControlDependencyManager( const ControlDependencyManager& ) = delete;
 163         ControlDependencyManager& operator=( const ControlDependencyManager& ) = delete;
 164     };
 165
 166
 167     //= EnableOnCheck
 168
 169     /** a helper class implementing the ->IWindowOperator interface,
 170         which enables a dependent window depending on the check state of
 171         an instigator window.
 172
 173         @see DialogController
 174     */
 175     template< class CHECKABLE >
 176     class SVT_DLLPUBLIC EnableOnCheck : public IWindowOperator
 177     {
 178     public:
 179         typedef CHECKABLE   SourceType;
 180
 181     private:
 182         SourceType& m_rCheckable;
 183
 184     public:
 185         /** constructs the instance
 186
 187             @param _rCheckable
 188                 a ->Window instance which supports a boolean method IsChecked. Usually
 189                 a ->RadioButton or ->CheckBox
 190         */
 191         EnableOnCheck( SourceType& _rCheckable )
 192             :m_rCheckable( _rCheckable )
 193         {
 194         }
 195
 196         virtual void operateOn( const VclWindowEvent& /*_rTrigger*/, vcl::Window& _rOperateOn ) const override
 197         {
 198             _rOperateOn.Enable( m_rCheckable.IsChecked() );
 199         }
 200     };
 201
 202
 203     //= FilterForRadioOrCheckToggle
 204
 205     /** a helper class implementing the ->IWindowEventFilter interface,
 206         which filters for radio buttons or check boxes being toggled.
 207
 208         Technically, the class simply filters for the ->VclEventId::RadiobuttonToggle
 209         and the ->VclEventId::CheckboxToggle event.
 210     */
 211     class SVT_DLLPUBLIC FilterForRadioOrCheckToggle : public IWindowEventFilter
 212     {
 213         const vcl::Window&   m_rWindow;
 214     public:
 215         FilterForRadioOrCheckToggle( const vcl::Window& _rWindow )
 216             :m_rWindow( _rWindow )
 217         {
 218         }
 219
 220         bool payAttentionTo( const VclWindowEvent& _rEvent ) const override
 221         {
 222             if  (   ( _rEvent.GetWindow() == &m_rWindow )
 223                 &&  (   ( _rEvent.GetId() == VclEventId::RadiobuttonToggle )
 224                     ||  ( _rEvent.GetId() == VclEventId::CheckboxToggle )
 225                     )
 226                 )
 227                 return true;
 228             return false;
 229         }
 230     };
 231
 232
 233     //= RadioDependentEnabler
 234
 235     /** a ->DialogController derivee which enables or disables its dependent windows,
 236         depending on the check state of a radio button.
 237
 238         The usage of this class is as simple as
 239         <code>
 240         pController = new RadioDependentEnabler( m_aOptionSelectSomething );
 241         pController->addDependentWindow( m_aLabelSelection );
 242         pController->addDependentWindow( m_aListSelection );
 243         </code>
 244
 245         With this, both <code>m_aLabelSelection</code> and <code>m_aListSelection</code> will
 246         be disabled if and only <code>m_aOptionSelectSomething</code> is checked.
 247     */
 248     class SVT_DLLPUBLIC RadioDependentEnabler : public DialogController
 249     {
 250     public:
 251         RadioDependentEnabler( RadioButton& _rButton )
 252             :DialogController( _rButton,
 253                 PWindowEventFilter( new FilterForRadioOrCheckToggle( _rButton ) ),
 254                 PWindowOperator( new EnableOnCheck< RadioButton >( _rButton ) ) )
 255         {
 256         }
 257     };
 258
 259
 260 } // namespace svt
 261
 262
 263 #endif // INCLUDED_SVTOOLS_DIALOGCONTROLLING_HXX
 264
 265 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */