src/frontends/ButtonPolicies.h

   1 // -*- C++ -*-
   2 /* ButtonPolicies.h
   3  * Provides a state machine implementation of the various button policies
   4  * used by the dialogs.
   5  * Author: Allan Rae <rae@lyx.org>
   6  * This file is part of
   7  * ======================================================
   8  *
   9  *           LyX, The Document Processor
  10  *
  11  *           Copyright 1995 Matthias Ettrich
  12  *           Copyright 1995-2000 The LyX Team.
  13  *
  14  *           This file Copyright 2000
  15  *           Allan Rae
  16  * ======================================================
  17  */
  18
  19 #ifndef BUTTONPOLICIES_H
  20 #define BUTTONPOLICIES_H
  21
  22
  23 #include <vector>
  24 #include "support/utility.hpp"
  25
  26
  27 /** An abstract base class for button policies.
  28     A state machine implementation of the various button policies used by the
  29     dialogs. Only the policy is implemented here.  Separate ButtonController
  30     classes are needed for each GUI implementation.
  31  */
  32 class ButtonPolicy : public noncopyable
  33 {
  34 public:
  35         /**@name Constructors and Deconstructors */
  36         //@{
  37         ///
  38         virtual ~ButtonPolicy() {}
  39         //@}
  40
  41         /**@name Enums */
  42         //@{
  43         /** The various possible state names.
  44             Not all state-machines have this many states.  However, we need
  45             to define them all here so we can share the code.
  46         */
  47         enum State {
  48                 INITIAL = 0,
  49                 VALID,
  50                 INVALID,
  51                 APPLIED,
  52                 RO_INITIAL,
  53                 RO_VALID,
  54                 RO_INVALID,
  55                 RO_APPLIED,
  56                 BOGUS = 55
  57         };
  58         /// The various button types.
  59         enum Button {
  60                 CLOSE    = 0,  // Not a real button, but effectively !CANCEL
  61                 OKAY     = 1,
  62                 APPLY    = 2,
  63                 CANCEL   = 4,
  64                 UNDO_ALL = 8
  65         };
  66         /** State machine inputs.
  67             All the policies so far have both CANCEL and HIDE always going to
  68             INITIAL. This won't necessarily be true for all [future] policies
  69             though so I'll leave those two as distinct inputs rather than merge
  70             them.  For example, a dialog that doesn't update it's input fields
  71             when reshown after being hidden needs a policy where CANCEL and
  72             HIDE are treated differently.
  73          */
  74         enum SMInput {
  75                 SMI_VALID = 0,
  76                 SMI_INVALID,
  77                 SMI_OKAY,
  78                 SMI_APPLY,
  79                 SMI_CANCEL,
  80                 SMI_UNDO_ALL,
  81                 SMI_HIDE,
  82                 SMI_READ_ONLY,
  83                 SMI_READ_WRITE,
  84                 SMI_TOTAL       // not a real input
  85         };
  86         //@}
  87
  88         /**@name Access Functions */
  89         //@{
  90         /// Trigger a transition with this input.
  91         virtual void input(SMInput) = 0;
  92         /// Activation status of OK
  93         virtual bool buttonStatus(Button) = 0;
  94         //@}
  95
  96         /**@name Typedefs */
  97         //@{
  98         /// Transition map of the state machine.
  99         typedef std::vector<State> StateArray;
 100         typedef std::vector<StateArray> StateMachine;
 101         /// The state outputs are the status of the buttons.
 102         typedef std::vector<int> StateOutputs;
 103         //@}
 104 };
 105
 106
 107 /** Defines the policy used by the Preferences dialog.
 108     Four buttons: Ok (Save), Apply, Cancel/Close, Restore.
 109     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 110     This is based on the value of the bool state of the Button::CANCEL.
 111     true == Cancel, false == Close
 112  */
 113 class PreferencesPolicy : public ButtonPolicy
 114 {
 115 public:
 116         ///
 117         PreferencesPolicy();
 118         ///
 119         virtual ~PreferencesPolicy() {}
 120
 121         /**@name Access Functions */
 122         //@{
 123         /// Trigger a transition with this input.
 124         virtual void input(SMInput);
 125         /** Activation status of a button.
 126             We assume that we haven't gotten into an undefined state.
 127             This is reasonable since we can only reach states defined
 128             in the state machine and they should all have been defined in
 129             the outputs_ variable.  Perhaps we can do something at compile
 130             time to check that all the states have corresponding outputs.
 131          */
 132         virtual bool buttonStatus(Button button)
 133                 { return button & outputs_[state_]; }
 134         //@}
 135 private:
 136         /**@name Private Data Members */
 137         //@{
 138         /// Current state.
 139         State state_;
 140         /// Which buttons are active for a given state.
 141         StateOutputs outputs_;
 142         ///
 143         StateMachine state_machine_;
 144         //@}
 145 };
 146
 147
 148
 149 /** Ok and Cancel buttons for dialogs with read-only operation.
 150     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 151     This is based on the value of the bool state of the Button::CANCEL.
 152     true == Cancel, false == Close
 153  */
 154 class OkCancelPolicy : public ButtonPolicy
 155 {
 156 public:
 157         ///
 158         OkCancelPolicy();
 159         ///
 160         virtual ~OkCancelPolicy() {}
 161
 162         /**@name Access Functions */
 163         //@{
 164         /// Trigger a transition with this input.
 165         virtual void input(SMInput);
 166         /// Activation status of a button.
 167         virtual bool buttonStatus(Button button)
 168                 { return button & outputs_[state_]; }
 169         //@}
 170 private:
 171         /**@name Private Data Members */
 172         //@{
 173         /// Current state.
 174         State state_;
 175         /// Which buttons are active for a given state.
 176         StateOutputs outputs_;
 177         ///
 178         StateMachine state_machine_;
 179         //@}
 180 };
 181
 182
 183 /** Ok and Cancel buttons for dialogs where read-only operation is blocked.
 184     The state machine design for this policy allows changes to occur within
 185     the dialog while a file is read-only -- the okay button is disabled until
 186     a read-write input is given.  When the file is made read-write the dialog
 187     will then be in the correct state (as if the file had always been read-write).
 188     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 189     This is based on the value of the bool state of the Button::CANCEL.
 190     true == Cancel, false == Close
 191  */
 192 class OkCancelReadOnlyPolicy : public ButtonPolicy
 193 {
 194 public:
 195         ///
 196         OkCancelReadOnlyPolicy();
 197         ///
 198         virtual ~OkCancelReadOnlyPolicy() {}
 199
 200         /**@name Access Functions */
 201         //@{
 202         /// Trigger a transition with this input.
 203         virtual void input(SMInput);
 204         /// Activation status of a button.
 205         virtual bool buttonStatus(Button button)
 206                 { return button & outputs_[state_]; }
 207         //@}
 208 private:
 209         /**@name Private Data Members */
 210         //@{
 211         /// Current state.
 212         State state_;
 213         /// Which buttons are active for a given state.
 214         StateOutputs outputs_;
 215         ///
 216         StateMachine state_machine_;
 217         //@}
 218 };
 219
 220
 221 /** Ok, Apply and Cancel buttons for dialogs where read-only operation is blocked.
 222     Repeated Apply are not allowed.  Likewise,  Ok cannot follow Apply without
 223     some valid input. That is, the dialog contents must change between each Apply
 224     or Apply and Ok.
 225     The state machine design for this policy allows changes to occur within
 226     the dialog while a file is read-only -- the Ok+Apply buttons are disabled
 227     until a read-write input is given.  When the file is made read-write the
 228     dialog will then be in the correct state (as if the file had always been
 229     read-write).
 230     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 231     This is based on the value of the bool state of the Button::CANCEL.
 232     true == Cancel, false == Close
 233  */
 234 class NoRepeatedApplyReadOnlyPolicy : public ButtonPolicy
 235 {
 236 public:
 237         ///
 238         NoRepeatedApplyReadOnlyPolicy();
 239         ///
 240         virtual ~NoRepeatedApplyReadOnlyPolicy() {}
 241
 242         /**@name Access Functions */
 243         //@{
 244         /// Trigger a transition with this input.
 245         virtual void input(SMInput);
 246         /// Activation status of a button.
 247         virtual bool buttonStatus(Button button)
 248                 { return button & outputs_[state_]; }
 249         //@}
 250 private:
 251         /**@name Private Data Members */
 252         //@{
 253         /// Current state.
 254         State state_;
 255         /// Which buttons are active for a given state.
 256         StateOutputs outputs_;
 257         ///
 258         StateMachine state_machine_;
 259         //@}
 260 };
 261
 262
 263 /** Ok, Apply and Cancel buttons for dialogs where read-only operation is blocked.
 264     Repeated Apply is allowed.  Likewise,  Ok can follow Apply.
 265     The state machine design for this policy allows changes to occur within
 266     the dialog while a file is read-only -- the Ok+Apply buttons are disabled
 267     until a read-write input is given.  When the file is made read-write the
 268     dialog will then be in the correct state (as if the file had always been
 269     read-write).
 270     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 271     This is based on the value of the bool state of the Button::CANCEL.
 272     true == Cancel, false == Close
 273  */
 274 class OkApplyCancelReadOnlyPolicy : public ButtonPolicy
 275 {
 276 public:
 277         ///
 278         OkApplyCancelReadOnlyPolicy();
 279         ///
 280         virtual ~OkApplyCancelReadOnlyPolicy() {}
 281
 282         /**@name Access Functions */
 283         //@{
 284         /// Trigger a transition with this input.
 285         virtual void input(SMInput);
 286         /// Activation status of a button.
 287         virtual bool buttonStatus(Button button)
 288                 { return button & outputs_[state_]; }
 289         //@}
 290 private:
 291         /**@name Private Data Members */
 292         //@{
 293         /// Current state.
 294         State state_;
 295         /// Which buttons are active for a given state.
 296         StateOutputs outputs_;
 297         ///
 298         StateMachine state_machine_;
 299         //@}
 300 };
 301
 302
 303 /** Ok, Apply and Cancel buttons for dialogs where repeated Apply is allowed.
 304     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 305     This is based on the value of the bool state of the Button::CANCEL.
 306     true == Cancel, false == Close
 307  */
 308 class OkApplyCancelPolicy : public ButtonPolicy
 309 {
 310 public:
 311         ///
 312         OkApplyCancelPolicy();
 313         ///
 314         virtual ~OkApplyCancelPolicy() {}
 315
 316         /**@name Access Functions */
 317         //@{
 318         /// Trigger a transition with this input.
 319         virtual void input(SMInput);
 320         /// Activation status of a button.
 321         virtual bool buttonStatus(Button button)
 322                 { return button & outputs_[state_]; }
 323         //@}
 324 private:
 325         /**@name Private Data Members */
 326         //@{
 327         /// Current state.
 328         State state_;
 329         /// Which buttons are active for a given state.
 330         StateOutputs outputs_;
 331         ///
 332         StateMachine state_machine_;
 333         //@}
 334 };
 335
 336
 337 /** Ok, Apply and Cancel buttons for dialogs with no repeated Apply.
 338     Note: This scheme supports the relabelling of Cancel to Close and vice versa.
 339     This is based on the value of the bool state of the Button::CANCEL.
 340     true == Cancel, false == Close
 341  */
 342 class NoRepeatedApplyPolicy : public ButtonPolicy
 343 {
 344 public:
 345         ///
 346         NoRepeatedApplyPolicy();
 347         ///
 348         virtual ~NoRepeatedApplyPolicy() {}
 349
 350         /**@name Access Functions */
 351         //@{
 352         /// Trigger a transition with this input.
 353         virtual void input(SMInput);
 354         /// Activation status of a button.
 355         virtual bool buttonStatus(Button button)
 356                 { return button & outputs_[state_]; }
 357         //@}
 358 private:
 359         /**@name Private Data Members */
 360         //@{
 361         /// Current state.
 362         State state_;
 363         /// Which buttons are active for a given state.
 364         StateOutputs outputs_;
 365         ///
 366         StateMachine state_machine_;
 367         //@}
 368 };
 369
 370 #endif