src/frontends/qt4/ButtonPolicy.h

   1 // -*- C++ -*-
   2 /**
   3  * \file ButtonPolicy.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Allan Rae
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  *
  11  * Provides a state machine implementation of the various button policies
  12  * used by the dialogs.
  13  */
  14
  15 #ifndef BUTTONPOLICY_H
  16 #define BUTTONPOLICY_H
  17
  18 namespace lyx {
  19 namespace frontend {
  20
  21 /** A class for button policies.
  22     A state machine implementation of the various button policies used by the
  23     dialogs. Only the policy is implemented here.  Separate ButtonController
  24     classes are needed for each GUI implementation.
  25
  26                 Policy                    | ReadOnly | Apply Button | Repeated Apply
  27     ========================================================================
  28     OkCancel                  |     N    |      N        |      -
  29     OkCancelReadOnly          |     Y    |      N        |      -
  30     OkApplyCancel             |     N    |      Y        |      Y
  31     OkApplyCancelReadOnly     |     Y    |      Y        |      Y
  32     NoRepeatedApply           |     N    |      Y        |      N
  33     NoRepeatedApplyReadOnly   |     Y    |      Y        |      N
  34     Preferences               |     N    |      Y        | No (Ok-Close)
  35     Ignorant                  |    N/A   |     N/A       |     N/A
  36     ========================================================================
  37
  38     Policy
  39         The name of the policy
  40     ReadOnly
  41         Does the policy treat read-only docs differently to read-write docs?
  42         This usually means that when an SMI_READ_ONLY input arrives then
  43         all the buttons are disabled except Cancel/Close.  The state
  44         machine tracks the inputs (valid/invalid) and has states for all
  45         combinations. When an SMI_READ_WRITE input arrives the appropriate
  46         machine state is entered (just as if the document had always been
  47         read-write).
  48         NOTE: If a dialog doesn't care about the read-only status of a document
  49         (and uses an appropriate policy) it can never get into a read-only state
  50         so isReadOnly() can only ever return false even though the document may
  51         be read-only.
  52     Repeated Apply
  53         Simply means that it is alright to use the Apply button multiple times
  54         without requiring a change of the dialog contents.  If no repeating is
  55         allowed the Ok+Apply buttons are deactivated.  The Preferences dialog
  56         has its own special version of repeated apply handling because its Ok
  57         button is actually a Save button -- it is always reasonable to Save the
  58         preferences if the dialog has changed since the last save.
  59
  60     The IgnorantPolicy is a special case that allows anything.
  61  */
  62
  63 class ButtonPolicy
  64 {
  65 public:
  66
  67         // The various poicies
  68         enum Policy {
  69                 /** Ok and Cancel buttons for dialogs with read-only operation.
  70                         Note: This scheme supports the relabelling of Cancel to Close and
  71                         vice versa.
  72                         This is based on the value of the bool state of the Button::CANCEL.
  73                         true == Cancel, false == Close
  74                  */
  75     OkCancelPolicy,
  76
  77
  78                 /** Ok and Cancel buttons for dialogs where read-only operation is blocked.
  79                         The state machine design for this policy allows changes to occur within
  80                         the dialog while a file is read-only -- the okay button is disabled until
  81                         a read-write input is given.  When the file is made read-write the dialog
  82                         will then be in the correct state (as if the file had always been
  83                         read-write).
  84                         Note: This scheme supports the relabelling of Cancel to Close
  85                         and vice versa.
  86                         This is based on the value of the bool state of the Button::CANCEL.
  87                         true == Cancel, false == Close
  88                  */
  89                 OkCancelReadOnlyPolicy,
  90
  91                 /** Ok, Apply and Cancel buttons for dialogs where read-only operation
  92                         is blocked.
  93                         Repeated Apply are not allowed.  Likewise,  Ok cannot follow Apply without
  94                         some valid input. That is, the dialog contents must change between
  95                         each Apply or Apply and Ok.
  96                         The state machine design for this policy allows changes to occur within
  97                         the dialog while a file is read-only -- the Ok+Apply buttons are disabled
  98                         until a read-write input is given.  When the file is made read-write the
  99                         dialog will then be in the correct state (as if the file had always been
 100                         read-write).
 101                         Note: This scheme supports the relabelling of Cancel to Close
 102                         and vice versa.
 103                         This is based on the value of the bool state of the Button::CANCEL.
 104                         true == Cancel, false == Close
 105                  */
 106                 NoRepeatedApplyReadOnlyPolicy,
 107
 108                 /** Ok, Apply and Cancel buttons for dialogs where read-only
 109                         operation is blocked.
 110                         Repeated Apply is allowed.  Likewise,  Ok can follow Apply.
 111                         The state machine design for this policy allows changes to occur within
 112                         the dialog while a file is read-only -- the Ok+Apply buttons are disabled
 113                         until a read-write input is given.  When the file is made read-write the
 114                         dialog will then be in the correct state (as if the file had always been
 115                         read-write).
 116                         Note: This scheme supports the relabelling of Cancel to Close
 117                         and vice versa.
 118                         This is based on the value of the bool state of the Button::CANCEL.
 119                         true == Cancel, false == Close
 120                  */
 121                 OkApplyCancelReadOnlyPolicy,
 122
 123                 /** Ok, Apply and Cancel buttons for dialogs where repeated
 124  *    Apply is allowed.
 125                         Note: This scheme supports the relabelling of Cancel to Close
 126                         and vice versa.
 127                         This is based on the value of the bool state of the Button::CANCEL.
 128                         true == Cancel, false == Close
 129                  */
 130                 OkApplyCancelPolicy,
 131
 132                 /** Ok, Apply and Cancel buttons for dialogs with no repeated Apply.
 133                         Note: This scheme supports the relabelling of Cancel to Close
 134                         and vice versa.
 135                         This is based on the value of the bool state of the Button::CANCEL.
 136                         true == Cancel, false == Close
 137                  */
 138                 NoRepeatedApplyPolicy,
 139
 140                 /** Defines the policy used by the Preferences dialog.
 141                         Four buttons: Ok (Save), Apply, Cancel/Close, Restore.
 142                         Note: This scheme supports the relabelling of Cancel to Close
 143                         and vice versa.
 144                         This is based on the value of the bool state of the Button::CANCEL.
 145                         true == Cancel, false == Close
 146                  */
 147                 PreferencesPolicy,
 148
 149                 /** Defines the policy used by dialogs that are forced to support a button
 150                         controller when they either don't have a use for one or are not ready to
 151                         use one.  This may be useful when testing a new button policy but wishing
 152                         to minimise problems to users by supplying an anything-goes policy via a
 153                         preprocessor directive.
 154                  */
 155                 IgnorantPolicy,
 156         };
 157
 158         /// Constructor
 159         explicit ButtonPolicy(Policy policy);
 160         /// Destructor
 161         ~ButtonPolicy();
 162         ///
 163         void setPolicy(Policy policy);
 164
 165         /** The various possible state names.
 166             Not all state-machines have this many states.  However, we need
 167             to define them all here so we can share the code.
 168         */
 169         enum State {
 170                 ///
 171                 INITIAL = 0,
 172                 ///
 173                 VALID,
 174                 ///
 175                 INVALID,
 176                 ///
 177                 APPLIED,
 178                 ///
 179                 RO_INITIAL,
 180                 ///
 181                 RO_VALID,
 182                 ///
 183                 RO_INVALID,
 184                 ///
 185                 RO_APPLIED,
 186                 ///
 187                 BOGUS = 55
 188         };
 189
 190         /// The various button types.
 191         enum Button {
 192                 ///
 193                 CLOSE    = 0,  // Not a real button, but effectively !CANCEL
 194                 ///
 195                 OKAY     = 1,
 196                 ///
 197                 APPLY    = 2,
 198                 ///
 199                 CANCEL   = 4,
 200                 ///
 201                 RESTORE  = 8
 202         };
 203         ///
 204         static const Button ALL_BUTTONS =
 205                 Button(OKAY | APPLY | CANCEL | RESTORE);
 206
 207         /** State machine inputs.
 208             All the policies so far have both CANCEL and HIDE always going to
 209             INITIAL. This won't necessarily be true for all [future] policies
 210             though so I'll leave those two as distinct inputs rather than merge
 211             them.  For example, a dialog that doesn't update it's input fields
 212             when reshown after being hidden needs a policy where CANCEL and
 213             HIDE are treated differently.
 214          */
 215         enum SMInput {
 216                 /// the dialog contents are now valid
 217                 SMI_VALID = 0,
 218                 /// the dialog contents are now invalid
 219                 SMI_INVALID,
 220                 /// an apply-and-hide action has happened
 221                 SMI_OKAY,
 222                 /// an apply action has happened
 223                 SMI_APPLY,
 224                 /// a cancel action has happened
 225                 SMI_CANCEL,
 226                 /// a restore action has happened
 227                 SMI_RESTORE,
 228                 /// the dialog has been hidden
 229                 SMI_HIDE,
 230                 /// the dialog contents are read-only
 231                 SMI_READ_ONLY,
 232                 /// the dialog contents can be modified
 233                 SMI_READ_WRITE,
 234                 /// the state of the dialog contents has not changed
 235                 SMI_NOOP,
 236                 /// for internal use
 237                 SMI_TOTAL
 238         };
 239
 240         /// Trigger a transition with this input.
 241         void input(SMInput);
 242         /** Activation status of a button.
 243             We assume that we haven't gotten into an undefined state.
 244             This is reasonable since we can only reach states defined
 245             in the state machine and they should all have been defined in
 246             the outputs_ variable.  Perhaps we can do something at compile
 247             time to check that all the states have corresponding outputs.
 248          */
 249         bool buttonStatus(Button) const;
 250         /// Are we in a read-only state?
 251         bool isReadOnly() const;
 252
 253 private:
 254         /// noncopyable
 255         ButtonPolicy(ButtonPolicy const &);
 256         void operator=(ButtonPolicy const &);
 257
 258         /// pimpl
 259         class Private;
 260         Private * d;
 261 };
 262
 263
 264 } // namespace frontend
 265 } // namespace lyx
 266
 267 #endif