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