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