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 <boost/utility.hpp>
  25
  26 #include "support/LOstream.h"
  27
  28 /** An abstract base class for button policies.
  29     A state machine implementation of the various button policies used by the
  30     dialogs. Only the policy is implemented here.  Separate ButtonController
  31     classes are needed for each GUI implementation.
  32
  33                 Policy          | ReadOnly | Apply Button | Repeated Apply
  34     ========================================================================
  35     OkCancel                    |       N  |    N         |     -
  36     OkCancelReadOnly            |       Y  |    N         |     -
  37     OkApplyCancel               |       N  |    Y         |     Y
  38     OkApplyCancelReadOnly       |       Y  |    Y         |     Y
  39     NoRepeatedApply             |       N  |    Y         |     N
  40     NoRepeatedApplyReadOnly     |       Y  |    Y         |     N
  41     Preferences                 |       N  |    Y         | No (Ok-Close)
  42     Ignorant                    |      N/A |    N/A       |    N/A
  43     ========================================================================
  44
  45     Policy
  46         The name of the policy
  47     ReadOnly
  48         Does the policy treat read-only docs differently to read-write docs?
  49         This usually means that when an SMI_READ_ONLY input arrives then
  50         all the buttons are disabled except Cancel/Close.  The state
  51         machine tracks the inputs (valid/invalid) and has states for all
  52         combinations. When an SMI_READ_WRITE input arrives the appropriate
  53         machine state is entered (just as if the document had always been
  54         read-write).
  55         NOTE: If a dialog doesn't care about the read-only status of a document
  56         (and uses an appropriate policy) it can never get into a read-only state
  57         so isReadOnly() can only ever return false even though the document may
  58         be read-only.
  59     Repeated Apply
  60         Simply means that it is alright to use the Apply button multiple times
  61         without requiring a change of the dialog contents.  If no repeating is
  62         allowed the Ok+Apply buttons are deactivated.  The Preferences dialog
  63         has its own special version of repeated apply handling because its Ok
  64         button is actually a Save button -- its always reasonable to Save the
  65         preferences if the dialog has changed since the last save.
  66
  67     The IgnorantPolicy is a special case that allows anything.
  68  */
  69 class ButtonPolicy : public noncopyable {
  70 public:
  71         ///
  72         virtual ~ButtonPolicy() {}
  73
  74         /** The various possible state names.
  75             Not all state-machines have this many states.  However, we need
  76             to define them all here so we can share the code.
  77         */
  78         enum State {
  79                 ///
  80                 INITIAL = 0,
  81                 ///
  82                 VALID,
  83                 ///
  84                 INVALID,
  85                 ///
  86                 APPLIED,
  87                 ///
  88                 RO_INITIAL,
  89                 ///
  90                 RO_VALID,
  91                 ///
  92                 RO_INVALID,
  93                 ///
  94                 RO_APPLIED,
  95                 ///
  96                 BOGUS = 55
  97         };
  98
  99         /// The various button types.
 100         enum Button {
 101                 ///
 102                 CLOSE    = 0,  // Not a real button, but effectively !CANCEL
 103                 ///
 104                 OKAY     = 1,
 105                 ///
 106                 APPLY    = 2,
 107                 ///
 108                 CANCEL   = 4,
 109                 ///
 110                 UNDO_ALL = 8
 111         };
 112         ///
 113         static const Button ALL_BUTTONS =
 114                 Button(OKAY | APPLY | CANCEL | UNDO_ALL);
 115
 116         /** State machine inputs.
 117             All the policies so far have both CANCEL and HIDE always going to
 118             INITIAL. This won't necessarily be true for all [future] policies
 119             though so I'll leave those two as distinct inputs rather than merge
 120             them.  For example, a dialog that doesn't update it's input fields
 121             when reshown after being hidden needs a policy where CANCEL and
 122             HIDE are treated differently.
 123          */
 124         enum SMInput {
 125                 ///
 126                 SMI_VALID = 0,
 127                 ///
 128                 SMI_INVALID,
 129                 ///
 130                 SMI_OKAY,
 131                 ///
 132                 SMI_APPLY,
 133                 ///
 134                 SMI_CANCEL,
 135                 ///
 136                 SMI_UNDO_ALL,
 137                 ///
 138                 SMI_HIDE,
 139                 ///
 140                 SMI_READ_ONLY,
 141                 ///
 142                 SMI_READ_WRITE,
 143                 ///
 144                 SMI_TOTAL       // not a real input
 145         };
 146
 147         /// Trigger a transition with this input.
 148         virtual void input(SMInput) = 0;
 149         /// Activation status of a button
 150         virtual bool buttonStatus(Button) const = 0;
 151         /// Are we in a read-only state?
 152         virtual bool isReadOnly() const = 0;
 153
 154         /// Transition map of the state machine.
 155         typedef std::vector<State> StateArray;
 156         ///
 157         typedef std::vector<StateArray> StateMachine;
 158         /// The state outputs are the status of the buttons.
 159         typedef std::vector<int> StateOutputs;
 160 };
 161
 162
 163 inline
 164 std::ostream & operator<<(std::ostream & os, ButtonPolicy::State st)
 165 {
 166         os << int(st);
 167         return os;
 168 }
 169
 170
 171 inline
 172 std::ostream & operator<<(std::ostream & os, ButtonPolicy::SMInput smi)
 173 {
 174         os << int(smi);
 175         return os;
 176 }
 177
 178
 179 //--------------------- Actual Policy Classes -----------------------------
 180
 181 /** Ok and Cancel buttons for dialogs with read-only operation.
 182     Note: This scheme supports the relabelling of Cancel to Close and
 183     vice versa.
 184     This is based on the value of the bool state of the Button::CANCEL.
 185     true == Cancel, false == Close
 186  */
 187 class OkCancelPolicy : public ButtonPolicy {
 188 public:
 189         ///
 190         OkCancelPolicy();
 191         ///
 192         //virtual ~OkCancelPolicy() {}
 193
 194         /// Trigger a transition with this input.
 195         virtual void input(SMInput);
 196         /** Activation status of a button.
 197             We assume that we haven't gotten into an undefined state.
 198             This is reasonable since we can only reach states defined
 199             in the state machine and they should all have been defined in
 200             the outputs_ variable.  Perhaps we can do something at compile
 201             time to check that all the states have corresponding outputs.
 202          */
 203         virtual bool buttonStatus(Button button) const {
 204                 return button & outputs_[state_];
 205         }
 206         /// Are we in a read-only state?
 207         virtual bool isReadOnly() const {
 208                 return false;
 209         }
 210 private:
 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 /** Ok and Cancel buttons for dialogs where read-only operation is blocked.
 220     The state machine design for this policy allows changes to occur within
 221     the dialog while a file is read-only -- the okay button is disabled until
 222     a read-write input is given.  When the file is made read-write the dialog
 223     will then be in the correct state (as if the file had always been
 224     read-write).
 225     Note: This scheme supports the relabelling of Cancel to Close
 226     and vice versa.
 227     This is based on the value of the bool state of the Button::CANCEL.
 228     true == Cancel, false == Close
 229  */
 230 class OkCancelReadOnlyPolicy : public ButtonPolicy {
 231 public:
 232         ///
 233         OkCancelReadOnlyPolicy();
 234         ///
 235         //virtual ~OkCancelReadOnlyPolicy() {}
 236
 237         /// Trigger a transition with this input.
 238         virtual void input(SMInput);
 239         /// Activation status of a button.
 240         virtual bool buttonStatus(Button button) const {
 241                 return button & outputs_[state_];
 242         }
 243         /// Are we in a read-only state?
 244         virtual bool isReadOnly() const {
 245                 return RO_INITIAL == state_
 246                         || RO_VALID == state_
 247                         || RO_INVALID == state_
 248                         || RO_APPLIED == state_;
 249         }
 250 private:
 251         /// Current state.
 252         State state_;
 253         /// Which buttons are active for a given state.
 254         StateOutputs outputs_;
 255         ///
 256         StateMachine state_machine_;
 257 };
 258
 259
 260 /** Ok, Apply and Cancel buttons for dialogs where read-only operation
 261     is blocked.
 262     Repeated Apply are not allowed.  Likewise,  Ok cannot follow Apply without
 263     some valid input. That is, the dialog contents must change between
 264     each Apply or Apply and Ok.
 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
 271     and vice versa.
 272     This is based on the value of the bool state of the Button::CANCEL.
 273     true == Cancel, false == Close
 274  */
 275 class NoRepeatedApplyReadOnlyPolicy : public ButtonPolicy
 276 {
 277 public:
 278         ///
 279         NoRepeatedApplyReadOnlyPolicy();
 280         ///
 281         //virtual ~NoRepeatedApplyReadOnlyPolicy() {}
 282
 283         /// Trigger a transition with this input.
 284         virtual void input(SMInput);
 285         /// Activation status of a button.
 286         virtual bool buttonStatus(Button button) const {
 287                 return button & outputs_[state_];
 288         }
 289         /// Are we in a read-only state?
 290         virtual bool isReadOnly() const {
 291                 return RO_INITIAL == state_
 292                         || RO_VALID == state_
 293                         || RO_INVALID == state_
 294                         || RO_APPLIED == state_;
 295         }
 296 private:
 297         /// Current state.
 298         State state_;
 299         /// Which buttons are active for a given state.
 300         StateOutputs outputs_;
 301         ///
 302         StateMachine state_machine_;
 303 };
 304
 305
 306 /** Ok, Apply and Cancel buttons for dialogs where read-only
 307     operation is blocked.
 308     Repeated Apply is allowed.  Likewise,  Ok can follow Apply.
 309     The state machine design for this policy allows changes to occur within
 310     the dialog while a file is read-only -- the Ok+Apply buttons are disabled
 311     until a read-write input is given.  When the file is made read-write the
 312     dialog will then be in the correct state (as if the file had always been
 313     read-write).
 314     Note: This scheme supports the relabelling of Cancel to Close
 315     and vice versa.
 316     This is based on the value of the bool state of the Button::CANCEL.
 317     true == Cancel, false == Close
 318  */
 319 class OkApplyCancelReadOnlyPolicy : public ButtonPolicy {
 320 public:
 321         ///
 322         OkApplyCancelReadOnlyPolicy();
 323         ///
 324         //virtual ~OkApplyCancelReadOnlyPolicy() {}
 325
 326         /// Trigger a transition with this input.
 327         virtual void input(SMInput);
 328         /// Activation status of a button.
 329         virtual bool buttonStatus(Button button) const {
 330                 return button & outputs_[state_];
 331         }
 332         /// Are we in a read-only state?
 333         virtual bool isReadOnly() const {
 334                 return RO_INITIAL == state_
 335                         || RO_VALID == state_
 336                         || RO_INVALID == state_
 337                         || RO_APPLIED == state_;
 338         }
 339 private:
 340         /// Current state.
 341         State state_;
 342         /// Which buttons are active for a given state.
 343         StateOutputs outputs_;
 344         ///
 345         StateMachine state_machine_;
 346 };
 347
 348
 349 /** Ok, Apply and Cancel buttons for dialogs where repeated Apply is allowed.
 350     Note: This scheme supports the relabelling of Cancel to Close
 351     and vice versa.
 352     This is based on the value of the bool state of the Button::CANCEL.
 353     true == Cancel, false == Close
 354  */
 355 class OkApplyCancelPolicy : public ButtonPolicy {
 356 public:
 357         ///
 358         OkApplyCancelPolicy();
 359         ///
 360         //virtual ~OkApplyCancelPolicy() {}
 361
 362         /// Trigger a transition with this input.
 363         virtual void input(SMInput);
 364         /// Activation status of a button.
 365         virtual bool buttonStatus(Button button) const {
 366                 return button & outputs_[state_];
 367         }
 368         /// Are we in a read-only state?
 369         virtual bool isReadOnly() const {
 370                 return false;
 371         }
 372 private:
 373         /// Current state.
 374         State state_;
 375         /// Which buttons are active for a given state.
 376         StateOutputs outputs_;
 377         ///
 378         StateMachine state_machine_;
 379 };
 380
 381
 382 /** Ok, Apply and Cancel buttons for dialogs with no repeated Apply.
 383     Note: This scheme supports the relabelling of Cancel to Close
 384     and vice versa.
 385     This is based on the value of the bool state of the Button::CANCEL.
 386     true == Cancel, false == Close
 387  */
 388 class NoRepeatedApplyPolicy : public ButtonPolicy {
 389 public:
 390         ///
 391         NoRepeatedApplyPolicy();
 392         ///
 393         //virtual ~NoRepeatedApplyPolicy() {}
 394
 395         /// Trigger a transition with this input.
 396         virtual void input(SMInput);
 397         /// Activation status of a button.
 398         virtual bool buttonStatus(Button button) const {
 399                 return button & outputs_[state_];
 400         }
 401         /// Are we in a read-only state?
 402         virtual bool isReadOnly() const {
 403                 return false;
 404         }
 405 private:
 406         /// Current state.
 407         State state_;
 408         /// Which buttons are active for a given state.
 409         StateOutputs outputs_;
 410         ///
 411         StateMachine state_machine_;
 412 };
 413
 414
 415 /** Defines the policy used by the Preferences dialog.
 416     Four buttons: Ok (Save), Apply, Cancel/Close, Restore.
 417     Note: This scheme supports the relabelling of Cancel to Close
 418     and vice versa.
 419     This is based on the value of the bool state of the Button::CANCEL.
 420     true == Cancel, false == Close
 421  */
 422 class PreferencesPolicy : public ButtonPolicy {
 423 public:
 424         ///
 425         PreferencesPolicy();
 426         ///
 427         //virtual ~PreferencesPolicy() {}
 428
 429         /// Trigger a transition with this input.
 430         virtual void input(SMInput);
 431         /// Activation status of a button.
 432         virtual bool buttonStatus(Button button) const {
 433                 return button & outputs_[state_];
 434         }
 435         /// Are we in a read-only state?
 436         virtual bool isReadOnly() const {
 437                 return false;
 438         }
 439 private:
 440         /// Current state.
 441         State state_;
 442         /// Which buttons are active for a given state.
 443         StateOutputs outputs_;
 444         ///
 445         StateMachine state_machine_;
 446 };
 447
 448
 449 /** Defines the policy used by dialogs that are forced to support a button
 450     controller when they either don't have a use for one or are not ready to
 451     use one.  This may be useful when testing a new button policy but wishing
 452     to minimise problems to users by supplying an anything-goes policy via a
 453     preprocessor directive.
 454  */
 455 class IgnorantPolicy : public ButtonPolicy {
 456 public:
 457         //virtual ~IgnorantPolicy() {}
 458
 459         /// Trigger a transition with this input.
 460         virtual void input(SMInput) {}
 461         /// Activation status of a button.
 462         virtual bool buttonStatus(Button) const {
 463                 return true;
 464         }
 465         /// Are we in a read-only state?
 466         virtual bool isReadOnly() const {
 467                 return false;
 468         }
 469 };
 470
 471 #endif