4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
9 * Full author contact details are available in file CREDITS.
11 * Provides a state machine implementation of the various button policies
12 * used by the dialogs.
15 #ifndef BUTTONPOLICY_H
16 #define BUTTONPOLICY_H
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.
26 Policy | ReadOnly | Apply Button | Repeated Apply
27 ========================================================================
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 OkApplyCancelAutoReadOnly | Y | Y | Y
35 Preferences | N | Y | No (Ok-Close)
36 Ignorant | N/A | N/A | N/A
37 ========================================================================
40 The name of the policy
42 Does the policy treat read-only docs differently to read-write docs?
43 This usually means that when an SMI_READ_ONLY input arrives then
44 all the buttons are disabled except Cancel/Close. The state
45 machine tracks the inputs (valid/invalid) and has states for all
46 combinations. When an SMI_READ_WRITE input arrives the appropriate
47 machine state is entered (just as if the document had always been
49 NOTE: If a dialog doesn't care about the read-only status of a document
50 (and uses an appropriate policy) it can never get into a read-only state
51 so isReadOnly() can only ever return false even though the document may
54 Simply means that it is alright to use the Apply button multiple times
55 without requiring a change of the dialog contents. If no repeating is
56 allowed the Ok+Apply buttons are deactivated. The Preferences dialog
57 has its own special version of repeated apply handling because its Ok
58 button is actually a Save button -- it is always reasonable to Save the
59 preferences if the dialog has changed since the last save.
61 The IgnorantPolicy is a special case that allows anything.
68 // The various poicies
70 /** Ok and Cancel buttons for dialogs with read-only operation.
71 Note: This scheme supports the relabelling of Cancel to Close and
73 This is based on the value of the bool state of the Button::CANCEL.
74 true == Cancel, false == Close
79 /** Ok and Cancel buttons for dialogs where read-only operation is blocked.
80 The state machine design for this policy allows changes to occur within
81 the dialog while a file is read-only -- the okay button is disabled until
82 a read-write input is given. When the file is made read-write the dialog
83 will then be in the correct state (as if the file had always been
85 Note: This scheme supports the relabelling of Cancel to Close
87 This is based on the value of the bool state of the Button::CANCEL.
88 true == Cancel, false == Close
90 OkCancelReadOnlyPolicy,
92 /** Ok, Apply and Cancel buttons for dialogs where read-only operation
94 Repeated Apply are not allowed. Likewise, Ok cannot follow Apply without
95 some valid input. That is, the dialog contents must change between
96 each Apply or Apply and Ok.
97 The state machine design for this policy allows changes to occur within
98 the dialog while a file is read-only -- the Ok+Apply buttons are disabled
99 until a read-write input is given. When the file is made read-write the
100 dialog will then be in the correct state (as if the file had always been
102 Note: This scheme supports the relabelling of Cancel to Close
104 This is based on the value of the bool state of the Button::CANCEL.
105 true == Cancel, false == Close
107 NoRepeatedApplyReadOnlyPolicy,
109 /** Ok, Apply and Cancel buttons for dialogs where read-only
110 operation is blocked.
111 Repeated Apply is allowed. Likewise, Ok can follow Apply.
112 The state machine design for this policy allows changes to occur within
113 the dialog while a file is read-only -- the Ok+Apply buttons are disabled
114 until a read-write input is given. When the file is made read-write the
115 dialog will then be in the correct state (as if the file had always been
117 Note: This scheme supports the relabelling of Cancel to Close
119 This is based on the value of the bool state of the Button::CANCEL.
120 true == Cancel, false == Close
122 OkApplyCancelReadOnlyPolicy,
124 /** Ok, Apply and Cancel buttons for dialogs where repeated
126 Note: This scheme supports the relabelling of Cancel to Close
128 This is based on the value of the bool state of the Button::CANCEL.
129 true == Cancel, false == Close
133 /** Ok, Apply and Cancel buttons for dialogs with no repeated Apply.
134 Note: This scheme supports the relabelling of Cancel to Close
136 This is based on the value of the bool state of the Button::CANCEL.
137 true == Cancel, false == Close
139 NoRepeatedApplyPolicy,
141 /** Ok, Apply and Cancel buttons and an AutoApply checkbox.
142 Note: This scheme supports the relabelling of Cancel to Close
144 This is based on the value of the bool state of the Button::CANCEL.
145 true == Cancel, false == Close
147 OkApplyCancelAutoReadOnlyPolicy,
149 /** Defines the policy used by the Preferences dialog.
150 Four buttons: Ok (Save), Apply, Cancel/Close, Restore.
151 Note: This scheme supports the relabelling of Cancel to Close
153 This is based on the value of the bool state of the Button::CANCEL.
154 true == Cancel, false == Close
158 /** Defines the policy used by dialogs that are forced to support a button
159 controller when they either don't have a use for one or are not ready to
160 use one. This may be useful when testing a new button policy but wishing
161 to minimise problems to users by supplying an anything-goes policy via a
162 preprocessor directive.
168 explicit ButtonPolicy(Policy policy);
172 void setPolicy(Policy policy);
174 /** The various possible state names.
175 Not all state-machines have this many states. However, we need
176 to define them all here so we can share the code.
205 /// The various button types.
208 CLOSE = 0, // Not a real button, but effectively !CANCEL
218 AUTOAPPLY = 16 // This is usually a checkbox
221 static const Button ALL_BUTTONS =
222 Button(OKAY | APPLY | CANCEL | RESTORE | AUTOAPPLY);
224 /** State machine inputs.
225 All the policies so far have both CANCEL and HIDE always going to
226 INITIAL. This won't necessarily be true for all [future] policies
227 though so I'll leave those two as distinct inputs rather than merge
228 them. For example, a dialog that doesn't update it's input fields
229 when reshown after being hidden needs a policy where CANCEL and
230 HIDE are treated differently.
233 /// the dialog contents are now valid
235 /// the dialog contents are now invalid
237 /// an apply-and-hide action has happened
239 /// an apply action has happened
241 /// a cancel action has happened
243 /// a restore action has happened
247 /// the dialog has been hidden
249 /// the dialog contents are read-only
251 /// the dialog contents can be modified
253 /// the state of the dialog contents has not changed
259 /// Trigger a transition with this input.
261 /** Activation status of a button.
262 We assume that we haven't gotten into an undefined state.
263 This is reasonable since we can only reach states defined
264 in the state machine and they should all have been defined in
265 the outputs_ variable. Perhaps we can do something at compile
266 time to check that all the states have corresponding outputs.
268 bool buttonStatus(Button) const;
269 /// Are we in a read-only state?
270 bool isReadOnly() const;
274 ButtonPolicy(ButtonPolicy const &);
275 void operator=(ButtonPolicy const &);
283 } // namespace frontend