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