libyui  3.10.0
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  * Get the current dialog title shown in the window manager's title bar.
187  **/
188  virtual std::string getDialogTitle() = 0;
189 
190  /**
191  * Set the dialog heading.
192  **/
193  virtual void setDialogHeading( const std::string & headingText ) = 0;
194 
195  /**
196  * Get the dialog heading.
197  **/
198  virtual std::string getDialogHeading() = 0;
199 
200  //
201  // Steps handling
202  //
203 
204  /**
205  * Add a step for the steps panel on the side bar.
206  * This only adds the step to the internal list of steps.
207  * The display is only updated upon calling updateSteps().
208  **/
209  virtual void addStep( const std::string & text, const std::string & id ) = 0;
210 
211  /**
212  * Add a step heading for the steps panel on the side bar.
213  * This only adds the heading to the internal list of steps.
214  * The display is only updated upon calling updateSteps().
215  **/
216  virtual void addStepHeading( const std::string & text ) = 0;
217 
218  /**
219  * Delete all steps and step headings from the internal lists.
220  * The display is only updated upon calling updateSteps().
221  **/
222  virtual void deleteSteps() = 0;
223 
224  /**
225  * Set the current step. This also triggers updateSteps() if necessary.
226  **/
227  virtual void setCurrentStep( const std::string & id ) = 0;
228 
229  /**
230  * Update the steps display: Reflect the internal steps and heading lists
231  * in the layout.
232  **/
233  virtual void updateSteps() = 0;
234 
235 
236  //
237  // Tree handling
238  //
239 
240  /**
241  * Add a tree item. If "parentID" is an empty string, it will be a root
242  * item. 'text' is the text that will be displayed in the tree, 'id' the ID
243  * with which this newly created item can be referenced - and that will be
244  * returned when the user clicks on a tree item.
245  **/
246  virtual void addTreeItem( const std::string & parentID,
247  const std::string & text,
248  const std::string & id ) = 0;
249 
250  /**
251  * Select the tree item with the specified ID, if such an item exists.
252  **/
253  virtual void selectTreeItem( const std::string & id ) = 0;
254 
255  /**
256  * Returns the current tree selection or an empty string if nothing is
257  * selected or there is no tree.
258  **/
259  virtual std::string currentTreeSelection() = 0;
260 
261  /**
262  * Delete all tree items.
263  **/
264  virtual void deleteTreeItems() = 0;
265 
266 
267  //
268  // Menu handling
269  //
270 
271  /**
272  * Add a menu to the menu bar. If the menu bar is not visible yet, it will
273  * be made visible. 'text' is the user-visible text for the menu bar
274  * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
275  * later addMenuEntry() etc. calls.
276  **/
277  virtual void addMenu( const std::string & text,
278  const std::string & id ) = 0;
279 
280  /**
281  * Add a submenu to the menu with ID 'parentMenuID'.
282  **/
283  virtual void addSubMenu( const std::string & parentMenuID,
284  const std::string & text,
285  const std::string & id ) = 0;
286 
287  /**
288  * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
289  * be returned by UI::UserInput() etc. when a user activates this menu entry.
290  **/
291  virtual void addMenuEntry( const std::string & parentMenuID,
292  const std::string & text,
293  const std::string & id ) = 0;
294 
295  /**
296  * Add a menu separator to a menu.
297  **/
298  virtual void addMenuSeparator( const std::string & parentMenuID ) = 0;
299 
300  /**
301  * Delete all menus and hide the menu bar.
302  **/
303  virtual void deleteMenus() = 0;
304 
305  /**
306  * Show a "Release Notes" button above the "Help" button in the steps panel
307  * with the specified label that will return the specified id to
308  * UI::UserInput() when clicked.
309  **/
310  virtual void showReleaseNotesButton( const std::string & label,
311  const std::string & id ) = 0;
312 
313  //
314  // Misc
315  //
316 
317  /**
318  * Hide an existing "Release Notes" button.
319  **/
320  virtual void hideReleaseNotesButton() = 0;
321 
322  /**
323  * Retranslate internal buttons that are not accessible from the outside:
324  * - [Help]
325  * - [Steps]
326  * - [Tree]
327  **/
328  virtual void retranslateInternalButtons() = 0;
329 
330  /**
331  * NOP command to check if a YWizard is running.
332  **/
333  void ping();
334 
335 
336  //
337  // Property handling
338  //
339 
340  /**
341  * Get a property.
342  * Reimplemented from YWidget.
343  *
344  * This method may throw YUIPropertyExceptions.
345  **/
346  virtual YPropertyValue getProperty( const std::string & propertyName );
347 
348  /**
349  * Return this class's property set.
350  * This also initializes the property upon the first call.
351  *
352  * Reimplemented from YWidget.
353  **/
354  virtual const YPropertySet & propertySet();
355 
356 
357 private:
358 
360 };
361 
362 
363 #endif // YWizard_h
YWidget::parent
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271
YWizard::backButton
virtual YPushButton * backButton() const =0
Return the wizard buttons or 0 if there is no such button.
YWizard::currentTreeSelection
virtual std::string currentTreeSelection()=0
Returns the current tree selection or an empty string if nothing is selected or there is no tree.
YWidget
Abstract base class of all UI widgets.
Definition: YWidget.h:54
YWizard::addStepHeading
virtual void addStepHeading(const std::string &text)=0
Add a step heading for the steps panel on the side bar.
YWizard::~YWizard
virtual ~YWizard()
Destructor.
Definition: YWizard.cc:69
YReplacePoint
A placeholder that can have its contents exchanged, using ReplaceWidget.
Definition: YReplacePoint.h:33
YWizard::ping
void ping()
NOP command to check if a YWizard is running.
Definition: YWizard.cc:108
YWizard::addStep
virtual void addStep(const std::string &text, const std::string &id)=0
Add a step for the steps panel on the side bar.
YWizard::deleteTreeItems
virtual void deleteTreeItems()=0
Delete all tree items.
YWizard
A wizard is a more complex frame typically used for multi-step workflows:
Definition: YWizard.h:96
YWizard::updateSteps
virtual void updateSteps()=0
Update the steps display: Reflect the internal steps and heading lists in the layout.
YWizard::widgetClass
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YWizard.h:121
YWizard::getDialogHeading
virtual std::string getDialogHeading()=0
Get the dialog heading.
YWizard::deleteMenus
virtual void deleteMenus()=0
Delete all menus and hide the menu bar.
YPropertySet
A set of properties to check names and types against.
Definition: YProperty.h:197
YWizard::contentsReplacePoint
virtual YReplacePoint * contentsReplacePoint() const =0
Return the internal contents ReplacePoint.
YWizard::addMenuSeparator
virtual void addMenuSeparator(const std::string &parentMenuID)=0
Add a menu separator to a menu.
YWizard::setCurrentStep
virtual void setCurrentStep(const std::string &id)=0
Set the current step.
YWizard::wizardMode
YWizardMode wizardMode() const
Return the wizard mode (what kind of wizard this is): YWizardMode_Standard, YWizardMode_Steps,...
Definition: YWizard.cc:76
YWizard::addSubMenu
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'.
YWizardMode_Standard
@ YWizardMode_Standard
Normal wizard (help panel or nothing)
Definition: YWizard.h:44
YWizard::setDialogIcon
virtual void setDialogIcon(const std::string &iconName)=0
Set the dialog icon.
YWizard::addTreeItem
virtual void addTreeItem(const std::string &parentID, const std::string &text, const std::string &id)=0
Add a tree item.
YWizard::setButtonLabel
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:96
YWizard::retranslateInternalButtons
virtual void retranslateInternalButtons()=0
Retranslate internal buttons that are not accessible from the outside:
YWizardPrivate
Definition: YWizard.cc:35
YWizardMode_TitleOnLeft
@ YWizardMode_TitleOnLeft
Title on the left side.
Definition: YWizard.h:47
ImplPtr< YWizardPrivate >
YWizard::setDialogHeading
virtual void setDialogHeading(const std::string &headingText)=0
Set the dialog heading.
YWizardMode_Tree
@ YWizardMode_Tree
Tree in left side panel.
Definition: YWizard.h:46
YWizard::protectNextButton
void protectNextButton(bool protect)
Protect the wizard's "Next" button against disabling.
Definition: YWizard.cc:89
YWidget::helpText
std::string helpText() const
Return the help text for this widget.
Definition: YWidget.cc:342
YWizardMode_Steps
@ YWizardMode_Steps
Steps visible in left side panel.
Definition: YWizard.h:45
YWizard::YWizard
YWizard(YWidget *parent, const std::string &backButtonLabel, const std::string &abortButtonLabel, const std::string &nextButtonLabel, YWizardMode wizardMode=YWizardMode_Standard)
Constructor.
Definition: YWizard.cc:49
YWizard::getDialogTitle
virtual std::string getDialogTitle()=0
Get the current dialog title shown in the window manager's title bar.
YWizard::nextButtonIsProtected
bool nextButtonIsProtected() const
Check if the wizard's "Next" button is currently protected against disabling.
Definition: YWizard.cc:82
YWizard::addMenuEntry
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'.
YWizard::selectTreeItem
virtual void selectTreeItem(const std::string &id)=0
Select the tree item with the specified ID, if such an item exists.
YWizard::addMenu
virtual void addMenu(const std::string &text, const std::string &id)=0
Add a menu to the menu bar.
YPropertyValue
Transport class for the value of simple properties.
Definition: YProperty.h:104
YWizard::showReleaseNotesButton
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...
YWizard::deleteSteps
virtual void deleteSteps()=0
Delete all steps and step headings from the internal lists.
YWizard::setHelpText
virtual void setHelpText(const std::string &helpText)=0
Set the help text.
YWizard::hideReleaseNotesButton
virtual void hideReleaseNotesButton()=0
Hide an existing "Release Notes" button.
YWizard::setDialogTitle
virtual void setDialogTitle(const std::string &titleText)=0
Set the dialog title shown in the window manager's title bar.
YMacroRecorder
Abstract base class for macro recorders.
Definition: YMacroRecorder.h:38
YWizard::propertySet
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YWizard.cc:115
YWizardMode
YWizardMode
Kind of the wizard layout.
Definition: YWizard.h:42
YWizard::getProperty
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YWizard.cc:133
YPushButton
A push button; may have an icon, and a F-key shortcut.
Definition: YPushButton.h:37