libyui-qt  2.42.4
 All Classes Functions Variables
YQWizard.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: YQWizard.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 
26 #ifndef YQWizard_h
27 #define YQWizard_h
28 
29 #include <string>
30 #include <vector>
31 
32 #include <qpixmap.h>
33 #include <qstringlist.h>
34 #include "QY2ListView.h"
35 #include <QGridLayout>
36 #include <QSplitter>
37 #include <qlabel.h>
38 #include <QMenu>
39 #include <qevent.h>
40 #include <yui/YWizard.h>
41 #include "YQWizardButton.h"
42 
43 using std::vector;
44 
45 class QGridLayout;
46 class QFrame;
47 class QSplitter;
48 class QLabel;
49 class QMenuBar;
50 class QPushButton;
51 class QSpacerItem;
52 class QToolButton;
53 class QStackedWidget;
54 class YReplacePoint;
55 class QTreeWidgetItem;
56 class YQAlignment;
57 class YQReplacePoint;
58 class QY2ListView;
59 class QY2HelpDialog;
60 
61 
62 class YQWizard : public QSplitter, public YWizard
63 {
64  Q_OBJECT
65 
66 protected:
67  class Step;
68  class TreeItem;
69 
70 public:
71  /**
72  * Constructor.
73  **/
74  YQWizard( YWidget * parent,
75  const std::string & backButtonLabel,
76  const std::string & abortButtonLabel,
77  const std::string & nextButtonLabel,
78  YWizardMode wizardMode = YWizardMode_Standard );
79 
80  /**
81  * Destructor.
82  **/
83  virtual ~YQWizard();
84 
85  /**
86  * Returns a descriptive label of this dialog instance for debugging.
87  *
88  * Reimplemented from YWidget.
89  **/
90  virtual std::string debugLabel() const;
91 
92  enum Direction { Forward, Backward };
93 
94  /**
95  * Returns the current direction of wizard operations - going forward or
96  * going backward. This can be used to maintain a consistent direction when
97  * assigning default buttons to a dialog.
98  **/
99  Direction direction() const { return _direction; }
100 
101  //
102  // Wizard basics
103  //
104 
105  /**
106  * Return internal widgets.
107  *
108  * Implemented from YWizard.
109  **/
110  virtual YQWizardButton * backButton() const { return _backButton; }
111  virtual YQWizardButton * abortButton() const { return _abortButton; }
112  virtual YQWizardButton * nextButton() const { return _nextButton; }
113 
114  virtual YReplacePoint * contentsReplacePoint() const { return _contentsReplacePoint; }
115 
116  /**
117  * Set the label of one of the wizard buttons (backButton(), abortButton(),
118  * nextButton() ) if that button is non-null.
119  *
120  * Implemented from YWizard.
121  **/
122  virtual void setButtonLabel( YPushButton * button, const std::string & newLabel );
123 
124  /**
125  * Set the help text.
126  *
127  * Implemented from YWizard.
128  **/
129  virtual void setHelpText( const std::string & helpText );
130 
131  /**
132  * Set the dialog icon. An empty icon name clears the current icon.
133  *
134  * Implemented from YWizard.
135  **/
136  virtual void setDialogIcon( const std::string & iconName );
137 
138  /**
139  * Set the dialog title shown in window manager's title bar.
140  * An empty std::string clears the current text.
141  *
142  * Implemented from YWizard.
143  **/
144  virtual void setDialogTitle( const std::string & titleText );
145 
146 
147  /**
148  * Set the dialog heading.
149  *
150  * Implemented from YWizard.
151  **/
152  virtual void setDialogHeading( const std::string & headingText );
153 
154 
155  //
156  // Steps handling
157  //
158 
159  /**
160  * Add a step for the steps panel on the side bar.
161  * This only adds the step to the internal list of steps.
162  * The display is only updated upon calling updateSteps().
163  *
164  * Implemented from YWizard.
165  **/
166  virtual void addStep( const std::string & text, const std::string & id );
167 
168  /**
169  * Add a step heading for the steps panel on the side bar.
170  * This only adds the heading to the internal list of steps.
171  * The display is only updated upon calling updateSteps().
172  *
173  * Implemented from YWizard.
174  **/
175  virtual void addStepHeading( const std::string & text );
176 
177  /**
178  * Return list of pointers to steps.
179  * Not needed outside copySteps() function
180  *
181  **/
182  QList<YQWizard::Step*> stepsList() { return _stepsList; }
183 
184  /**
185  * Create a copy of given wizard's steps set (names & IDs)
186  * Populates _stepsList structure of current wizard
187  *
188  **/
189  void copySteps( YQWizard *wizard);
190 
191  /**
192  * Delete all steps and step headings from the internal lists.
193  * The display is only updated upon calling updateSteps().
194  *
195  * Implemented from YWizard.
196  **/
197  virtual void deleteSteps();
198 
199  /**
200  * Set the current step. This also triggers updateSteps() if necessary.
201  *
202  * Implemented from YWizard.
203  **/
204  virtual void setCurrentStep( const std::string & id );
205 
206  /**
207  * Return QString ID of currently active step
208  *
209  **/
210  QString currentStep() { return _currentStepID; };
211 
212  /**
213  * Update the steps display: Reflect the internal steps and heading lists
214  * in the layout.
215  *
216  * Implemented from YWizard.
217  **/
218  virtual void updateSteps();
219 
220 
221  //
222  // Tree handling
223  //
224 
225  /**
226  * Add a tree item. If "parentID" is an empty std::string, it will be a root
227  * item. 'text' is the text that will be displayed in the tree, 'id' the ID
228  * with which this newly created item can be referenced - and that will be
229  * returned when the user clicks on a tree item.
230  *
231  * Implemented from YWizard.
232  **/
233  virtual void addTreeItem( const std::string & parentID,
234  const std::string & text,
235  const std::string & id );
236 
237  /**
238  * Select the tree item with the specified ID, if such an item exists.
239  *
240  * Implemented from YWizard.
241  **/
242  virtual void selectTreeItem( const std::string & id );
243 
244  /**
245  * Returns the current tree selection or an empty std::string if nothing is
246  * selected or there is no tree.
247  *
248  * Implemented from YWizard.
249  **/
250  virtual std::string currentTreeSelection();
251 
252  /**
253  * Delete all tree items.
254  *
255  * Implemented from YWizard.
256  **/
257  virtual void deleteTreeItems();
258 
259 
260  //
261  // Menu handling
262  //
263 
264  /**
265  * Add a menu to the menu bar. If the menu bar is not visible yet, it will
266  * be made visible. 'text' is the user-visible text for the menu bar
267  * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
268  * later addMenuEntry() etc. calls.
269  *
270  * Implemented from YWizard.
271  **/
272  virtual void addMenu( const std::string & text,
273  const std::string & id );
274 
275  /**
276  * Add a submenu to the menu with ID 'parentMenuID'.
277  *
278  * Implemented from YWizard.
279  **/
280  virtual void addSubMenu( const std::string & parentMenuID,
281  const std::string & text,
282  const std::string & id );
283 
284  /**
285  * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
286  * be returned by UI::UserInput() etc. when a user activates this menu entry.
287  *
288  * Implemented from YWizard.
289  **/
290  virtual void addMenuEntry( const std::string & parentMenuID,
291  const std::string & text,
292  const std::string & id );
293 
294  /**
295  * Add a menu separator to a menu.
296  *
297  * Implemented from YWizard.
298  **/
299  virtual void addMenuSeparator( const std::string & parentMenuID );
300 
301  /**
302  * Delete all menus and hide the menu bar.
303  *
304  * Implemented from YWizard.
305  **/
306  virtual void deleteMenus();
307 
308 
309  //
310  // Misc
311  //
312 
313  /**
314  * Show a "Release Notes" button above the "Help" button in the steps panel
315  * with the specified label that will return the specified id to
316  * UI::UserInput() when clicked.
317  *
318  * The button (or the wizard) will assume ownership of the id and delete it
319  * in the destructor.
320  *
321  * Implemented from YWizard.
322  **/
323  virtual void showReleaseNotesButton( const std::string & label,
324  const std::string & id );
325 
326  /**
327  * Hide an existing "Release Notes" button.
328  *
329  * Implemented from YWizard.
330  **/
331  virtual void hideReleaseNotesButton();
332 
333  /**
334  * Retranslate internal buttons that are not accessible from the outside:
335  * - [Help]
336  * - [Steps]
337  * - [Tree]
338  *
339  * Implemented from YWizard.
340  **/
341  virtual void retranslateInternalButtons();
342 
343  /**
344  * Event filter.
345  *
346  * Reimplemented from QWidget.
347  **/
348  virtual bool eventFilter( QObject * obj, QEvent * ev );
349 
350  /**
351  * Return this wizard's work area (the pane right of the side bar).
352  * This should not be needed outside of YQMainWinDock.
353  **/
354  QWidget * workArea() const { return _workArea; }
355 
356 
357  //
358  // Geometry management
359  //
360 
361  /**
362  * Preferred width of the widget.
363  *
364  * Reimplemented from YWidget.
365  **/
366  virtual int preferredWidth();
367 
368  /**
369  * Preferred height of the widget.
370  *
371  * Reimplemented from YWidget.
372  **/
373  virtual int preferredHeight();
374 
375  /**
376  * Set the new size of the widget.
377  *
378  * Reimplemented from YWidget.
379  **/
380  virtual void setSize( int newWidth, int newHeight );
381 
382  /**
383  * Returns true if the wizard should follow the first wizard with steps
384  **/
385  bool isSecondary() const;
386 
387 signals:
388 
389  /**
390  * Emitted when the "Back" or "Cancel" button is clicked.
391  **/
392  void backClicked();
393 
394  /**
395  * Emitted when the "Abort" button is clicked.
396  **/
397  void abortClicked();
398 
399  /**
400  * Emitted when the "Next" or "OK" button is clicked.
401  *
402  * Notice: As long as this signal is connected, the wizard will no longer
403  * send button events to the UI. Rather, the connected QObject has to take
404  * care to propagate those events.
405  * This is used in YQPatternSelector, for example.
406  **/
407  void nextClicked();
408 
409 
410 public slots:
411 
412  /**
413  * Adapt the size of the client area (the ReplacePoint(`id(`contents)) to
414  * fit in its current space.
415  **/
416  void resizeClientArea();
417 
418  /**
419  * Show the current help text.
420  *
421  * This is useful only if it is obscured by any wizard steps, but it can
422  * safely be called at any time.
423  **/
424  void showHelp();
425 
426  /**
427  * Show the current wizard steps, if there are any. If there are none,
428  * nothing happens.
429  **/
430  void showSteps();
431 
432  /**
433  * Show the current selection tree in the side panel, if there is any. If
434  * there is none, nothing happens.
435  **/
436  void showTree();
437 
438 protected slots:
439 
440  /**
441  * Internal notification that the "Back" button has been clicked.
442  **/
443  void slotBackClicked();
444 
445  /**
446  * Internal notification that the "Abort" button has been clicked.
447  **/
448  void slotAbortClicked();
449 
450  /**
451  * Internal notification that the "Next" button has been clicked.
452  **/
453  void slotNextClicked();
454 
455  /**
456  * Propagate button clicked event of release notes button to the
457  * application.
458  **/
459  void releaseNotesClicked();
460 
461  /**
462  * Internal notification that [Space] or [Return] has been pressed on a
463  * tree item.
464  * If the item has an ID, that ID will be returned to UI::UserInput().
465  **/
466  void sendTreeEvent( QTreeWidgetItem * item );
467 
468  /**
469  * Internal notification that the tree selection has changed.
470  *
471  * If the currently selected item has an ID, that ID will be returned to
472  * UI::UserInput().
473  **/
474  void treeSelectionChanged();
475 
476  /**
477  * Internal notification that a menu item with numeric ID 'numID' has been
478  * activated.
479  **/
480  void sendMenuEvent( QAction *action );
481 
482 protected:
483 
484  // Layout functions
485 
486  void layoutTitleBar ( QWidget * parent );
487  QLayout *layoutSideBar ( QWidget * parent );
488  void layoutSideBarButtonBox ( QWidget * parent, QPushButton * button );
489  void layoutStepsPanel();
490  void layoutTreePanel();
491  QWidget *layoutWorkArea ( QWidget * parent );
492  void layoutClientArea ( QWidget * parent );
493  QLayout *layoutButtonBox ( QWidget * parent );
494 
495  /**
496  * Destroy the button box's buttons
497  **/
498  void destroyButtons();
499 
500  /**
501  * Update all step - use appropriate icons and colors
502  **/
503  void updateStepStates();
504 
505  /**
506  * Send a wizard event with the specified ID.
507  **/
508  void sendEvent( const std::string & id );
509 
510  /**
511  * Notification that a signal is being connected.
512  *
513  * Reimplemented from QObject.
514  **/
515  void connectNotify ( const char * signal );
516 
517  /**
518  * Notification that a signal is being disconnected.
519  *
520  * Reimplemented from QObject.
521  **/
522  void disconnectNotify ( const char * signal );
523 
524  /**
525  * Set a button's label.
526  **/
527  void setButtonLabel( YQWizardButton * button, const QString & newLabel );
528 
529  /**
530  * Enable or disable a button.
531  **/
532  void enableButton( YQWizardButton * button, bool enabled );
533 
534  /**
535  * Set the keyboard focus to a button.
536  **/
537  void setButtonFocus( YQWizardButton * button );
538 
539  /**
540  * Find a step with the specified ID. Returns 0 if there is no such step.
541  **/
542  YQWizard::Step * findStep( const QString & id );
543 
544  /**
545  * Find a tree item with the specified ID. Tree items without IDs cannot be
546  * found at all.
547  * Returns the item or 0 if no such item found.
548  **/
549  YQWizard::TreeItem * findTreeItem( const std::string & id );
550 
551 
552  //
553  // Data members
554  //
555 
556  std::string _backButtonLabel;
557  std::string _abortButtonLabel;
558  std::string _nextButtonLabel;
559 
560  bool _stepsEnabled;
561  bool _stepsRegistered;
562  bool _treeEnabled;
563  bool _protectNextButton;
564  bool _stepsDirty;
565  bool _sendButtonEvents;
566  Direction _direction;
567 
568  QString _currentStepID;
569  QString _qHelpText;
570 
571  QY2HelpDialog * _helpDlg;
572 
573  QStackedWidget * _sideBar;
574  QWidget * _stepsPanel;
575  QPushButton * _releaseNotesButton;
576  std::string _releaseNotesButtonId;
577  QPushButton * _helpButton;
578  QPushButton * _stepsButton;
579  QPushButton * _treeButton;
580  QFrame * _treePanel;
581  QY2ListView * _tree;
582 
583  QFrame * _workArea;
584  QWidget * _clientArea;
585  QMenuBar * _menuBar;
586  QLabel * _dialogIcon;
587  QLabel * _dialogHeading;
588  YQAlignment * _contents;
589  YQWizardButton * _backButton;
590  YQWizardButton * _abortButton;
591  YQWizardButton * _nextButton;
592  YReplacePoint * _contentsReplacePoint;
593 
594  QList<YQWizard::Step*> _stepsList;
595  QHash<QString,YQWizard::Step*> _stepsIDs;
596  QHash<QString,YQWizard::TreeItem*> _treeIDs;
597  QHash<QString,QMenu*> _menuIDs;
598  QHash<QAction*, std::string> _menuEntryIDs;
599 
600  QIcon _previousWindowIcon;
601 
602 private:
603  static YQWizard *main_wizard;
604 
605 protected:
606 
607  /**
608  * Helper class to represent a wizard step internally
609  **/
610  class Step
611  {
612  public:
613 
614  Step( const QString & name = "", const QString & id = "" )
615  : _name( name )
616  , _statusLabel( 0 )
617  , _nameLabel(0)
618  , _enabled( true )
619  , _idList( id )
620  , _status( Unset )
621  {}
622 
623  /**
624  * Destructor. Intentionally not deleting the widgets.
625  **/
626  virtual ~Step();
627 
628  virtual bool isHeading() const { return false; }
629 
630  enum Status { Unset, Todo, Current, Done };
631 
632  QString name() const { return _name; }
633  QLabel * statusLabel() const { return _statusLabel; }
634  QLabel * nameLabel() const { return _nameLabel; }
635  bool isEnabled() const { return _enabled; }
636  const QStringList & id() const { return _idList; }
637  void addID( const QString & id ) { _idList.append( id ); }
638  virtual bool hasID( const QString & id ) { return _idList.indexOf( id ) != -1; }
639 
640  void setStatusLabel( QLabel * label ) { _statusLabel = label; }
641  void setNameLabel ( QLabel * label ) { _nameLabel = label; }
642  void setEnabled( bool enabled ) { _enabled = enabled; }
643 
644  void deleteLabels();
645 
646  /**
647  * Set text color and status icon for one wizard step
648  **/
649  void setStatus( Status s );
650 
651  protected:
652 
653  QString _name;
654  QLabel * _statusLabel;
655  QLabel * _nameLabel;
656  bool _enabled;
657  QStringList _idList;
658  Status _status;
659 
660  private:
661  Q_DISABLE_COPY(Step);
662  };
663 
664 
665  /**
666  * Helper class to represent a wizard step heading internally
667  **/
668  class StepHeading: public Step
669  {
670  public:
671 
672  StepHeading( const QString & name = "" )
673  : Step( name, "" )
674  {}
675 
676  virtual ~StepHeading() {}
677  virtual bool isHeading() const { return true; }
678  virtual bool hasID( const QString & id ) { return false; }
679 
680  private:
681  Q_DISABLE_COPY(StepHeading);
682  };
683 
684 
685  /**
686  * Helper class for wizard tree item
687  **/
688  class TreeItem: public QY2ListViewItem
689  {
690  public:
691  TreeItem( QY2ListView * parent,
692  const QString & text,
693  const QString & id )
694  : QY2ListViewItem( parent, text )
695  , _id( id )
696  {}
697 
698  TreeItem( YQWizard::TreeItem * parent,
699  const QString & text,
700  const QString & id )
701  : QY2ListViewItem( parent, text )
702  , _id( id )
703  {}
704 
705  virtual QString text(int index) const { return QTreeWidgetItem::text(index); }
706  QString text() const { return QTreeWidgetItem::text(0); }
707  QString id() const { return _id; }
708 
709  private:
710  QString _id;
711  };
712 
713 }; // class YQWizard
714 
715 
716 
717 #endif // YQWizard_h