1 /*---------------------------------------------------------------------\
3 | __ __ ____ _____ ____ |
4 | \ \ / /_ _/ ___|_ _|___ \ |
5 | \ V / _` \___ \ | | __) | |
6 | | | (_| |___) || | / __/ |
7 | |_|\__,_|____/ |_| |_____| |
11 \----------------------------------------------------------------------/
15 Author: Stefan Hundhammer <sh@suse.de>
26 #include <q3ptrlist.h>
27 #include <qstringlist.h>
29 #include "QY2ListView.h"
31 #include <QGridLayout>
36 #include "YQWizardButton.h"
52 class QTreeWidgetItem;
58 class YQWizard : public QFrame, public YWizard
70 YQWizard( YWidget * parent,
71 const string & backButtonLabel,
72 const string & abortButtonLabel,
73 const string & nextButtonLabel,
74 YWizardMode wizardMode = YWizardMode_Standard );
82 * Returns a descriptive label of this dialog instance for debugging.
84 * Reimplemented from YWidget.
86 virtual string debugLabel();
88 enum Direction { Forward, Backward };
91 * Returns the current direction of wizard operations - going forward or
92 * going backward. This can be used to maintain a consistent direction when
93 * assigning default buttons to a dialog.
95 Direction direction() const { return _direction; }
102 * Return internal widgets.
104 * Implemented from YWizard.
106 virtual YQWizardButton * backButton() const { return _backButton; }
107 virtual YQWizardButton * abortButton() const { return _abortButton; }
108 virtual YQWizardButton * nextButton() const { return _nextButton; }
110 virtual YReplacePoint * contentsReplacePoint() const { return _contentsReplacePoint; }
113 * Set the label of one of the wizard buttons (backButton(), abortButton(),
114 * nextButton() ) if that button is non-null.
116 * Implemented from YWizard.
118 virtual void setButtonLabel( YPushButton * button, const string & newLabel );
123 * Implemented from YWizard.
125 virtual void setHelpText( const string & helpText );
128 * Set the dialog icon. An empty icon name clears the current icon.
130 * Implemented from YWizard.
132 virtual void setDialogIcon( const string & iconName );
135 * Set the dialog heading.
137 * Implemented from YWizard.
139 virtual void setDialogHeading( const string & headingText );
147 * Add a step for the steps panel on the side bar.
148 * This only adds the step to the internal list of steps.
149 * The display is only updated upon calling updateSteps().
151 * Implemented from YWizard.
153 virtual void addStep( const string & text, const string & id );
156 * Add a step heading for the steps panel on the side bar.
157 * This only adds the heading to the internal list of steps.
158 * The display is only updated upon calling updateSteps().
160 * Implemented from YWizard.
162 virtual void addStepHeading( const string & text );
165 * Delete all steps and step headings from the internal lists.
166 * The display is only updated upon calling updateSteps().
168 * Implemented from YWizard.
170 virtual void deleteSteps();
173 * Set the current step. This also triggers updateSteps() if necessary.
175 * Implemented from YWizard.
177 virtual void setCurrentStep( const string & id );
180 * Update the steps display: Reflect the internal steps and heading lists
183 * Implemented from YWizard.
185 virtual void updateSteps();
193 * Add a tree item. If "parentID" is an empty string, it will be a root
194 * item. 'text' is the text that will be displayed in the tree, 'id' the ID
195 * with which this newly created item can be referenced - and that will be
196 * returned when the user clicks on a tree item.
198 * Implemented from YWizard.
200 virtual void addTreeItem( const string & parentID,
205 * Select the tree item with the specified ID, if such an item exists.
207 * Implemented from YWizard.
209 virtual void selectTreeItem( const string & id );
212 * Returns the current tree selection or an empty string if nothing is
213 * selected or there is no tree.
215 * Implemented from YWizard.
217 virtual std::string currentTreeSelection();
220 * Delete all tree items.
222 * Implemented from YWizard.
224 virtual void deleteTreeItems();
232 * Add a menu to the menu bar. If the menu bar is not visible yet, it will
233 * be made visible. 'text' is the user-visible text for the menu bar
234 * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
235 * later addMenuEntry() etc. calls.
237 * Implemented from YWizard.
239 virtual void addMenu( const string & text,
243 * Add a submenu to the menu with ID 'parentMenuID'.
245 * Implemented from YWizard.
247 virtual void addSubMenu( const string & parentMenuID,
252 * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
253 * be returned by UI::UserInput() etc. when a user activates this menu entry.
255 * Implemented from YWizard.
257 virtual void addMenuEntry( const string & parentMenuID,
262 * Add a menu separator to a menu.
264 * Implemented from YWizard.
266 virtual void addMenuSeparator( const string & parentMenuID );
269 * Delete all menus and hide the menu bar.
271 * Implemented from YWizard.
273 virtual void deleteMenus();
281 * Show a "Release Notes" button above the "Help" button in the steps panel
282 * with the specified label that will return the specified id to
283 * UI::UserInput() when clicked.
285 * The button (or the wizard) will assume ownership of the id and delete it
288 * Implemented from YWizard.
290 virtual void showReleaseNotesButton( const string & label,
294 * Hide an existing "Release Notes" button.
296 * Implemented from YWizard.
298 virtual void hideReleaseNotesButton();
301 * Retranslate internal buttons that are not accessible from the outside:
306 * Implemented from YWizard.
308 virtual void retranslateInternalButtons();
313 * Reimplemented from QWidget.
315 virtual bool eventFilter( QObject * obj, QEvent * ev );
318 // Geometry management
322 * Preferred width of the widget.
324 * Reimplemented from YWidget.
326 virtual int preferredWidth();
329 * Preferred height of the widget.
331 * Reimplemented from YWidget.
333 virtual int preferredHeight();
336 * Set the new size of the widget.
338 * Reimplemented from YWidget.
340 virtual void setSize( int newWidth, int newHeight );
346 * Emitted when the "Back" or "Cancel" button is clicked.
351 * Emitted when the "Abort" button is clicked.
356 * Emitted when the "Next" or "OK" button is clicked.
358 * Notice: As long as this signal is connected, the wizard will no longer
359 * send button events to the UI. Rather, the connected QObject has to take
360 * care to propagate those events.
361 * This is used in YQPatternSelector, for example.
369 * Adapt the size of the client area (the ReplacePoint(`id(`contents)) to
370 * fit in its current space.
372 void resizeClientArea();
375 * Show the current help text.
377 * This is useful only if it is obscured by any wizard steps, but it can
378 * safely be called at any time.
383 * Show the current wizard steps, if there are any. If there are none,
389 * Show the current selection tree in the side panel, if there is any. If
390 * there is none, nothing happens.
397 * Internal notification that the "Back" button has been clicked.
399 void slotBackClicked();
402 * Internal notification that the "Abort" button has been clicked.
404 void slotAbortClicked();
407 * Internal notification that the "Next" button has been clicked.
409 void slotNextClicked();
412 * Propagate button clicked event of release notes button to the
415 void releaseNotesClicked();
418 * Internal notification that [Space] or [Return] has been pressed on a
420 * If the item has an ID, that ID will be returned to UI::UserInput().
422 void sendTreeEvent( QTreeWidgetItem * item );
425 * Internal notification that the tree selection has changed.
427 * If the currently selected item has an ID, that ID will be returned to
430 void treeSelectionChanged();
433 * Internal notification that a menu item with numeric ID 'numID' has been
436 void sendMenuEvent( int numID );
443 void layoutTitleBar ( QWidget * parent );
444 QLayout *layoutSideBar ( QWidget * parent );
445 void layoutSideBarButtonBox ( QWidget * parent, QPushButton * button );
446 void layoutStepsPanel();
447 void layoutHelpPanel();
448 void layoutTreePanel();
449 QLayout *layoutWorkArea ( QFrame * parentHBox );
450 void layoutClientArea( QWidget * parent );
451 QLayout *layoutButtonBox( QWidget * parent );
454 * Destroy the button box's buttons
456 void destroyButtons();
459 * Update all step - use appropriate icons and colors
461 void updateStepStates();
464 * Send a wizard event with the specified ID.
466 void sendEvent( const string & id );
469 * Notification that a signal is being connected.
471 * Reimplemented from QObject.
473 void connectNotify ( const char * signal );
476 * Notification that a signal is being disconnected.
478 * Reimplemented from QObject.
480 void disconnectNotify ( const char * signal );
483 * Set a button's label.
485 void setButtonLabel( YQWizardButton * button, const QString & newLabel );
488 * Enable or disable a button.
490 void enableButton( YQWizardButton * button, bool enabled );
493 * Set the keyboard focus to a button.
495 void setButtonFocus( YQWizardButton * button );
498 * Find a step with the specified ID. Returns 0 if there is no such step.
500 YQWizard::Step * findStep( const QString & id );
503 * Find a tree item with the specified ID. Tree items without IDs cannot be
505 * Returns the item or 0 if no such item found.
507 YQWizard::TreeItem * findTreeItem( const string & id );
514 string _backButtonLabel;
515 string _abortButtonLabel;
516 string _nextButtonLabel;
520 bool _protectNextButton;
522 bool _sendButtonEvents;
523 Direction _direction;
525 QString _currentStepID;
529 Q3WidgetStack * _sideBar;
530 QWidget * _stepsPanel;
531 QPushButton * _releaseNotesButton;
532 string _releaseNotesButtonId;
533 QPushButton * _helpButton;
534 QPushButton * _stepsButton;
535 QPushButton * _treeButton;
539 QWidget * _clientArea;
541 QLabel * _dialogIcon;
542 QLabel * _dialogHeading;
543 YQAlignment * _contents;
544 YQWizardButton * _backButton;
545 YQWizardButton * _abortButton;
546 YQWizardButton * _nextButton;
547 YReplacePoint * _contentsReplacePoint;
549 Q3PtrList<YQWizard::Step> _stepsList;
550 Q3Dict<YQWizard::Step> _stepsIDs;
551 Q3Dict<YQWizard::TreeItem> _treeIDs;
552 Q3Dict<Q3PopupMenu> _menuIDs;
553 vector<string> _menuEntryIDs;
559 * Helper class to represent a wizard step internally
565 Step( const QString & name = "", const QString & id = "" )
575 * Destructor. Intentionally not deleting the widgets.
579 virtual bool isHeading() const { return false; }
581 enum Status { Unset, Todo, Current, Done };
583 QString name() const { return _name; }
584 QLabel * statusLabel() const { return _statusLabel; }
585 QLabel * nameLabel() const { return _nameLabel; }
586 bool isEnabled() const { return _enabled; }
587 const QStringList & id() const { return _idList; }
588 void addID( const QString & id ) { _idList.append( id ); }
589 virtual bool hasID( const QString & id ) { return _idList.indexOf( id ) != -1; }
591 void setStatusLabel( QLabel * label ) { _statusLabel = label; }
592 void setNameLabel ( QLabel * label ) { _nameLabel = label; }
593 void setEnabled( bool enabled ) { _enabled = enabled; }
596 * Set text color and status icon for one wizard step
598 void setStatus( Status s );
603 QLabel * _statusLabel;
612 * Helper class to represent a wizard step heading internally
614 class StepHeading: public Step
618 StepHeading( const QString & name = "" )
622 virtual ~StepHeading() {}
623 virtual bool isHeading() const { return true; }
624 virtual bool hasID( const QString & id ) { return false; }
629 * Helper class for wizard tree item
631 class TreeItem: public QY2ListViewItem
634 TreeItem( QY2ListView * parent,
635 const QString & text,
637 : QY2ListViewItem( parent, text )
641 TreeItem( YQWizard::TreeItem * parent,
642 const QString & text,
644 : QY2ListViewItem( parent, text )
648 virtual QString text(int index) const { return QTreeWidgetItem::text(index); }
649 QString text() const { return QTreeWidgetItem::text(0); }
650 QString id() const { return _id; }