libyui  3.0.5
 All Classes Functions Variables Enumerations Friends
YWizard.h
1 /*
2  Copyright (C) 2000-2012 Novell, Inc
3  This library is free software; you can redistribute it and/or modify
4  it under the terms of the GNU Lesser General Public License as
5  published by the Free Software Foundation; either version 2.1 of the
6  License, or (at your option) version 3.0 of the License. This library
7  is distributed in the hope that it will be useful, but WITHOUT ANY
8  WARRANTY; without even the implied warranty of MERCHANTABILITY or
9  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10  License for more details. You should have received a copy of the GNU
11  Lesser General Public License along with this library; if not, write
12  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13  Floor, Boston, MA 02110-1301 USA
14 */
15 
16 
17 /*-/
18 
19  File: YWizard.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YWizard_h
26 #define YWizard_h
27 
28 #include "YWidget.h"
29 
30 class YMacroRecorder;
31 class YWizardPrivate;
32 class YPushButton;
33 class YReplacePoint;
34 
35 #define YWizardID "wizard"
36 #define YWizardContentsReplacePointID "contents"
37 
38 
39 enum YWizardMode
40 {
41  YWizardMode_Standard, // Normal wizard (help panel or nothing)
42  YWizardMode_Steps, // Steps visible in left side panel
43  YWizardMode_Tree // Tree in left side panel
44 };
45 
46 
47 /**
48  * A wizard is a more complex frame typically used for multi-step workflows:
49  *
50  * +------------+------------------------------------------------+
51  * | | |
52  * | | |
53  * | | |
54  * | | |
55  * | | |
56  * | | |
57  * | | |
58  * | | |
59  * | Side bar | Content Area |
60  * | | (YReplacePoint) |
61  * | | |
62  * | | |
63  * | | |
64  * | | |
65  * | | |
66  * | | |
67  * | | [Back] [Abort] [Next] |
68  * +------------+------------------------------------------------+
69  *
70  * The side bar can contain help text, a list of steps that are performed, or
71  * an embedded tree (much like the YTree widget).
72  *
73  * The client application creates the wizard and replaces the widget in the
74  * content area for each step.
75  *
76  * The wizard buttons can theoretically be used to do anything, but good UI
77  * design will stick to the model above: [Back], [Abort], [Next].
78  *
79  * If only two buttons are desired, leave the [Back] button's label emtpy. The
80  * remaining two buttons will be rearranged accordingly in the button area.
81  *
82  * In the last step of a multi-step workflow, the [Next] button's label is
83  * customarily replaced with a label that indicates that this is the last
84  * step. [Accept] is recommended for that button label: [Finish] (as sometimes
85  * used in other environments) by no means clearly indicates that this is the
86  * positive ending, the final "do it" button. Worse, translations of that are
87  * often downright miserable: To German, [Finish] gets translated as [Beenden]
88  * which is the same word as "Quit" (used in menus). This does not at all tell
89  * the user that that button really performs the requested action the
90  * multi-step wizard is all about.
91  **/
92 class YWizard: public YWidget
93 {
94 protected:
95  /**
96  * Constructor.
97  *
98  * If only two buttons are desired, leave 'backButtonLabel' empty.
99  **/
101  const std::string & backButtonLabel,
102  const std::string & abortButtonLabel,
103  const std::string & nextButtonLabel,
104  YWizardMode wizardMode = YWizardMode_Standard );
105 
106 public:
107 
108  /**
109  * Destructor.
110  **/
111  virtual ~YWizard();
112 
113  /**
114  * Returns a descriptive name of this widget class for logging,
115  * debugging etc.
116  **/
117  virtual const char * widgetClass() const { return "YWizard"; }
118 
119 
120  //
121  // Wizard basics
122  //
123 
124  /**
125  * Return the wizard mode (what kind of wizard this is):
126  * YWizardMode_Standard, YWizardMode_Steps, YWizardMode_Tree
127  **/
128  YWizardMode wizardMode() const;
129 
130  /**
131  * Return the wizard buttons or 0 if there is no such button.
132  *
133  * Derived classes are required to implement this.
134  **/
135  virtual YPushButton * backButton() const = 0;
136  virtual YPushButton * abortButton() const = 0;
137  virtual YPushButton * nextButton() const = 0;
138 
139  /**
140  * Return the internal contents ReplacePoint.
141  *
142  * Derived classes are required to implement this.
143  **/
144  virtual YReplacePoint * contentsReplacePoint() const = 0;
145 
146  /**
147  * Protect the wizard's "Next" button against disabling.
148  **/
149  void protectNextButton( bool protect );
150 
151  /**
152  * Check if the wizard's "Next" button is currently protected against
153  * disabling.
154  **/
155  bool nextButtonIsProtected() const;
156 
157  /**
158  * Set the label of one of the wizard buttons (backButton(), abortButton(),
159  * nextButton() ) if that button is non-null.
160  *
161  * The default implementation simply calls button->setLabel( newLabel ).
162  **/
163  virtual void setButtonLabel( YPushButton * button, const std::string & newLabel );
164 
165  /**
166  * Set the help text.
167  **/
168  virtual void setHelpText( const std::string & helpText ) = 0;
169 
170  /**
171  * Set the dialog icon. An empty icon name clears the current icon.
172  **/
173  virtual void setDialogIcon( const std::string & iconName ) = 0;
174 
175  /**
176  * Set the dialog title shown in the window manager's title bar.
177  An empty string clears the current title.
178  **/
179  virtual void setDialogTitle( const std::string & titleText ) = 0;
180 
181  /**
182  * Set the dialog heading.
183  **/
184  virtual void setDialogHeading( const std::string & headingText ) = 0;
185 
186 
187  //
188  // Steps handling
189  //
190 
191  /**
192  * Add a step for the steps panel on the side bar.
193  * This only adds the step to the internal list of steps.
194  * The display is only updated upon calling updateSteps().
195  **/
196  virtual void addStep( const std::string & text, const std::string & id ) = 0;
197 
198  /**
199  * Add a step heading for the steps panel on the side bar.
200  * This only adds the heading to the internal list of steps.
201  * The display is only updated upon calling updateSteps().
202  **/
203  virtual void addStepHeading( const std::string & text ) = 0;
204 
205  /**
206  * Delete all steps and step headings from the internal lists.
207  * The display is only updated upon calling updateSteps().
208  **/
209  virtual void deleteSteps() = 0;
210 
211  /**
212  * Set the current step. This also triggers updateSteps() if necessary.
213  **/
214  virtual void setCurrentStep( const std::string & id ) = 0;
215 
216  /**
217  * Update the steps display: Reflect the internal steps and heading lists
218  * in the layout.
219  **/
220  virtual void updateSteps() = 0;
221 
222 
223  //
224  // Tree handling
225  //
226 
227  /**
228  * Add a tree item. If "parentID" is an empty string, it will be a root
229  * item. 'text' is the text that will be displayed in the tree, 'id' the ID
230  * with which this newly created item can be referenced - and that will be
231  * returned when the user clicks on a tree item.
232  **/
233  virtual void addTreeItem( const std::string & parentID,
234  const std::string & text,
235  const std::string & id ) = 0;
236 
237  /**
238  * Select the tree item with the specified ID, if such an item exists.
239  **/
240  virtual void selectTreeItem( const std::string & id ) = 0;
241 
242  /**
243  * Returns the current tree selection or an empty string if nothing is
244  * selected or there is no tree.
245  **/
246  virtual std::string currentTreeSelection() = 0;
247 
248  /**
249  * Delete all tree items.
250  **/
251  virtual void deleteTreeItems() = 0;
252 
253 
254  //
255  // Menu handling
256  //
257 
258  /**
259  * Add a menu to the menu bar. If the menu bar is not visible yet, it will
260  * be made visible. 'text' is the user-visible text for the menu bar
261  * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
262  * later addMenuEntry() etc. calls.
263  **/
264  virtual void addMenu( const std::string & text,
265  const std::string & id ) = 0;
266 
267  /**
268  * Add a submenu to the menu with ID 'parentMenuID'.
269  **/
270  virtual void addSubMenu( const std::string & parentMenuID,
271  const std::string & text,
272  const std::string & id ) = 0;
273 
274  /**
275  * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
276  * be returned by UI::UserInput() etc. when a user activates this menu entry.
277  **/
278  virtual void addMenuEntry( const std::string & parentMenuID,
279  const std::string & text,
280  const std::string & id ) = 0;
281 
282  /**
283  * Add a menu separator to a menu.
284  **/
285  virtual void addMenuSeparator( const std::string & parentMenuID ) = 0;
286 
287  /**
288  * Delete all menus and hide the menu bar.
289  **/
290  virtual void deleteMenus() = 0;
291 
292  /**
293  * Show a "Release Notes" button above the "Help" button in the steps panel
294  * with the specified label that will return the specified id to
295  * UI::UserInput() when clicked.
296  **/
297  virtual void showReleaseNotesButton( const std::string & label,
298  const std::string & id ) = 0;
299 
300  //
301  // Misc
302  //
303 
304  /**
305  * Hide an existing "Release Notes" button.
306  **/
307  virtual void hideReleaseNotesButton() = 0;
308 
309  /**
310  * Retranslate internal buttons that are not accessible from the outside:
311  * - [Help]
312  * - [Steps]
313  * - [Tree]
314  **/
315  virtual void retranslateInternalButtons() = 0;
316 
317  /**
318  * NOP command to check if a YWizard is running.
319  **/
320  void ping();
321 
322 
323  //
324  // Property handling
325  //
326 
327  /**
328  * Get a property.
329  * Reimplemented from YWidget.
330  *
331  * This method may throw YUIPropertyExceptions.
332  **/
333  virtual YPropertyValue getProperty( const std::string & propertyName );
334 
335  /**
336  * Return this class's property set.
337  * This also initializes the property upon the first call.
338  *
339  * Reimplemented from YWidget.
340  **/
341  virtual const YPropertySet & propertySet();
342 
343 
344 private:
345 
347 };
348 
349 
350 #endif // YWizard_h