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 <q3gridlayout.h>
33 #include <q3popupmenu.h>
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.
395 * Set a widget's background pixmap to a gradient pixmap and set the
396 * widget's height (fixed) to that pixmap's height.
398 static void setGradient( QWidget * widget, const QPixmap & pixmap );
401 * Set a widget's background to the lower portion (the bottom
402 * 'croppedHeight' pixels) of a pixmap and set the widget's height (fixed)
403 * to that 'croppedHeight'.
405 static void setBottomCroppedGradient( QWidget * widget,
406 const QPixmap & pixmap,
410 * Bottom-crop a pixmap: Return a pixmap with the bottom 'croppedHeight'
413 static QPixmap bottomCropPixmap( const QPixmap & pixmap, int croppedHeight );
416 * Return the color of pixel( x, y ) of a pixmap.
417 * If pixmap is null defaultColor is returned.
418 * This is a _very_ expensive operation!
420 static QColor pixelColor( const QPixmap & pixmap, int x, int y, const QColor & defaultColor );
426 * Internal notification that the "Back" button has been clicked.
428 void slotBackClicked();
431 * Internal notification that the "Abort" button has been clicked.
433 void slotAbortClicked();
436 * Internal notification that the "Next" button has been clicked.
438 void slotNextClicked();
441 * Propagate button clicked event of release notes button to the
444 void releaseNotesClicked();
447 * Internal notification that [Space] or [Return] has been pressed on a
449 * If the item has an ID, that ID will be returned to UI::UserInput().
451 void sendTreeEvent( QTreeWidgetItem * item );
454 * Internal notification that the tree selection has changed.
456 * If the currently selected item has an ID, that ID will be returned to
459 void treeSelectionChanged();
462 * Internal notification that a menu item with numeric ID 'numID' has been
465 void sendMenuEvent( int numID );
472 void layoutTitleBar ( QWidget * parent );
473 void layoutSideBar ( QWidget * parent );
474 void layoutSideBarButtonBox ( QWidget * parent, QPushButton * button );
475 void layoutStepsPanel();
476 void layoutHelpPanel();
477 void layoutTreePanel();
478 void layoutWorkArea ( QFrame * parentHBox );
479 void layoutClientArea( QWidget * parent );
480 void layoutButtonBox( QWidget * parent );
484 * Load gradient pixmaps
486 void loadGradientPixmaps();
489 * Load step status icons
491 void loadStepsIcons();
494 * Destroy the button box's buttons
496 void destroyButtons();
499 * Update all step - use appropriate icons and colors
501 void updateStepStates();
504 * Add a (left or right) margin of the specified width to a widget,
505 * consisting of a fixed height top gradient , a flexible center part (in
506 * the gradient center color) and a fixed height bottom gradient.
508 * The bottom gradient widget is returned as a reference for other
509 * background pixmaps.
511 void addGradientColumn( QWidget * parent, int width = 8 );
514 * Send a wizard event with the specified ID.
516 void sendEvent( const string & id );
519 * Returns 'true' if the application is running on a high-color display,
520 * i.e., on an X visual with more than 8 bit depth.
522 bool highColorDisplay() const;
525 * Notification that a signal is being connected.
527 * Reimplemented from QObject.
529 void connectNotify ( const char * signal );
532 * Notification that a signal is being disconnected.
534 * Reimplemented from QObject.
536 void disconnectNotify ( const char * signal );
539 * Set a button's label.
541 void setButtonLabel( YQWizardButton * button, const QString & newLabel );
544 * Enable or disable a button.
546 void enableButton( YQWizardButton * button, bool enabled );
549 * Set the keyboard focus to a button.
551 void setButtonFocus( YQWizardButton * button );
554 * Set text color and status icon for one wizard step
556 void setStepStatus( YQWizard::Step * step, const QPixmap & icon, const QColor & color );
559 * Find a step with the specified ID. Returns 0 if there is no such step.
561 YQWizard::Step * findStep( const QString & id );
564 * Find a tree item with the specified ID. Tree items without IDs cannot be
566 * Returns the item or 0 if no such item found.
568 YQWizard::TreeItem * findTreeItem( const string & id );
575 string _backButtonLabel;
576 string _abortButtonLabel;
577 string _nextButtonLabel;
581 bool _protectNextButton;
583 bool _sendButtonEvents;
584 Direction _direction;
586 QPixmap _titleBarGradientPixmap;
587 QPixmap _topGradientPixmap;
588 QColor _gradientCenterColor;
589 QColor _gradientTopColor;
590 QPixmap _bottomGradientPixmap;
592 QPixmap _stepCurrentIcon;
593 QPixmap _stepToDoIcon;
594 QPixmap _stepDoneIcon;
596 QColor _stepCurrentColor;
597 QColor _stepToDoColor;
598 QColor _stepDoneColor;
600 QString _currentStepID;
603 Q3WidgetStack * _sideBar;
604 Q3VBox * _stepsPanel;
606 Q3GridLayout * _stepsGrid;
607 QPushButton * _releaseNotesButton;
608 string _releaseNotesButtonId;
609 QPushButton * _helpButton;
611 Q3TextBrowser * _helpBrowser;
612 QPushButton * _stepsButton;
613 QPushButton * _treeButton;
617 Q3VBox * _clientArea;
618 QWidget * _menuBarBox;
620 QLabel * _dialogIcon;
621 QLabel * _dialogHeading;
622 YQAlignment * _contents;
623 YQWizardButton * _backButton;
624 QSpacerItem * _backButtonSpacer;
625 YQWizardButton * _abortButton;
626 YQWizardButton * _nextButton;
627 YReplacePoint * _contentsReplacePoint;
629 Q3PtrList<YQWizard::Step> _stepsList;
630 Q3Dict<YQWizard::Step> _stepsIDs;
631 Q3Dict<YQWizard::TreeItem> _treeIDs;
632 Q3Dict<Q3PopupMenu> _menuIDs;
633 vector<string> _menuEntryIDs;
639 * Helper class to represent a wizard step internally
645 Step( const QString & name = "", const QString & id = "" )
654 * Destructor. Intentionally not deleting the widgets.
658 virtual bool isHeading() const { return false; }
660 QString name() const { return _name; }
661 QLabel * statusLabel() const { return _statusLabel; }
662 QLabel * nameLabel() const { return _nameLabel; }
663 bool isEnabled() const { return _enabled; }
664 const QStringList & id() const { return _idList; }
665 void addID( const QString & id ) { _idList.append( id ); }
666 virtual bool hasID( const QString & id ) { return _idList.find( id ) != _idList.end(); }
668 void setStatusLabel( QLabel * label ) { _statusLabel = label; }
669 void setNameLabel ( QLabel * label ) { _nameLabel = label; }
670 void setEnabled( bool enabled ) { _enabled = enabled; }
675 QLabel * _statusLabel;
683 * Helper class to represent a wizard step heading internally
685 class StepHeading: public Step
689 StepHeading( const QString & name = "" )
693 virtual ~StepHeading() {}
694 virtual bool isHeading() const { return true; }
695 virtual bool hasID( const QString & id ) { return false; }
700 * Helper class for wizard tree item
702 class TreeItem: public QY2ListViewItem
705 TreeItem( QY2ListView * parent,
706 const QString & text,
708 : QY2ListViewItem( parent, text )
712 TreeItem( YQWizard::TreeItem * parent,
713 const QString & text,
715 : QY2ListViewItem( parent, text )
719 virtual QString text(int index) const { return QTreeWidgetItem::text(index); }
720 QString text() const { return QTreeWidgetItem::text(0); }
721 QString id() const { return _id; }