1 /*---------------------------------------------------------------------\
3 | __ __ ____ _____ ____ |
4 | \ \ / /_ _/ ___|_ _|___ \ |
5 | \ V / _` \___ \ | | __) | |
6 | | | (_| |___) || | / __/ |
7 | |_|\__,_|____/ |_| |_____| |
11 \----------------------------------------------------------------------/
15 Author: Stefan Hundhammer <sh@suse.de>
25 #include <q3ptrlist.h>
26 #include <qstringlist.h>
28 #include "QY2ListView.h"
30 #include <q3gridlayout.h>
32 #include <q3popupmenu.h>
35 #include "YQWizardButton.h"
57 class YQWizard : public QFrame, public YWizard
69 YQWizard( YWidget * parent,
70 const string & backButtonLabel,
71 const string & abortButtonLabel,
72 const string & nextButtonLabel,
73 YWizardMode wizardMode = YWizardMode_Standard );
81 * Returns a descriptive label of this dialog instance for debugging.
83 * Reimplemented from YWidget.
85 virtual string debugLabel();
87 enum Direction { Forward, Backward };
90 * Returns the current direction of wizard operations - going forward or
91 * going backward. This can be used to maintain a consistent direction when
92 * assigning default buttons to a dialog.
94 Direction direction() const { return _direction; }
101 * Return internal widgets.
103 * Implemented from YWizard.
105 virtual YQWizardButton * backButton() const { return _backButton; }
106 virtual YQWizardButton * abortButton() const { return _abortButton; }
107 virtual YQWizardButton * nextButton() const { return _nextButton; }
109 virtual YReplacePoint * contentsReplacePoint() const { return _contentsReplacePoint; }
112 * Set the label of one of the wizard buttons (backButton(), abortButton(),
113 * nextButton() ) if that button is non-null.
115 * Implemented from YWizard.
117 virtual void setButtonLabel( YPushButton * button, const string & newLabel );
122 * Implemented from YWizard.
124 virtual void setHelpText( const string & helpText );
127 * Set the dialog icon. An empty icon name clears the current icon.
129 * Implemented from YWizard.
131 virtual void setDialogIcon( const string & iconName );
134 * Set the dialog heading.
136 * Implemented from YWizard.
138 virtual void setDialogHeading( const string & headingText );
146 * Add a step for the steps panel on the side bar.
147 * This only adds the step to the internal list of steps.
148 * The display is only updated upon calling updateSteps().
150 * Implemented from YWizard.
152 virtual void addStep( const string & text, const string & id );
155 * Add a step heading for the steps panel on the side bar.
156 * This only adds the heading to the internal list of steps.
157 * The display is only updated upon calling updateSteps().
159 * Implemented from YWizard.
161 virtual void addStepHeading( const string & text );
164 * Delete all steps and step headings from the internal lists.
165 * The display is only updated upon calling updateSteps().
167 * Implemented from YWizard.
169 virtual void deleteSteps();
172 * Set the current step. This also triggers updateSteps() if necessary.
174 * Implemented from YWizard.
176 virtual void setCurrentStep( const string & id );
179 * Update the steps display: Reflect the internal steps and heading lists
182 * Implemented from YWizard.
184 virtual void updateSteps();
192 * Add a tree item. If "parentID" is an empty string, it will be a root
193 * item. 'text' is the text that will be displayed in the tree, 'id' the ID
194 * with which this newly created item can be referenced - and that will be
195 * returned when the user clicks on a tree item.
197 * Implemented from YWizard.
199 virtual void addTreeItem( const string & parentID,
204 * Select the tree item with the specified ID, if such an item exists.
206 * Implemented from YWizard.
208 virtual void selectTreeItem( const string & id );
211 * Returns the current tree selection or an empty string if nothing is
212 * selected or there is no tree.
214 * Implemented from YWizard.
216 virtual string currentTreeSelection();
219 * Delete all tree items.
221 * Implemented from YWizard.
223 virtual void deleteTreeItems();
231 * Add a menu to the menu bar. If the menu bar is not visible yet, it will
232 * be made visible. 'text' is the user-visible text for the menu bar
233 * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
234 * later addMenuEntry() etc. calls.
236 * Implemented from YWizard.
238 virtual void addMenu( const string & text,
242 * Add a submenu to the menu with ID 'parentMenuID'.
244 * Implemented from YWizard.
246 virtual void addSubMenu( const string & parentMenuID,
251 * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
252 * be returned by UI::UserInput() etc. when a user activates this menu entry.
254 * Implemented from YWizard.
256 virtual void addMenuEntry( const string & parentMenuID,
261 * Add a menu separator to a menu.
263 * Implemented from YWizard.
265 virtual void addMenuSeparator( const string & parentMenuID );
268 * Delete all menus and hide the menu bar.
270 * Implemented from YWizard.
272 virtual void deleteMenus();
280 * Show a "Release Notes" button above the "Help" button in the steps panel
281 * with the specified label that will return the specified id to
282 * UI::UserInput() when clicked.
284 * The button (or the wizard) will assume ownership of the id and delete it
287 * Implemented from YWizard.
289 virtual void showReleaseNotesButton( const string & label,
293 * Hide an existing "Release Notes" button.
295 * Implemented from YWizard.
297 virtual void hideReleaseNotesButton();
300 * Retranslate internal buttons that are not accessible from the outside:
305 * Implemented from YWizard.
307 virtual void retranslateInternalButtons();
312 * Reimplemented from QWidget.
314 virtual bool eventFilter( QObject * obj, QEvent * ev );
317 // Geometry management
321 * Preferred width of the widget.
323 * Reimplemented from YWidget.
325 virtual int preferredWidth();
328 * Preferred height of the widget.
330 * Reimplemented from YWidget.
332 virtual int preferredHeight();
335 * Set the new size of the widget.
337 * Reimplemented from YWidget.
339 virtual void setSize( int newWidth, int newHeight );
345 * Emitted when the "Back" or "Cancel" button is clicked.
350 * Emitted when the "Abort" button is clicked.
355 * Emitted when the "Next" or "OK" button is clicked.
357 * Notice: As long as this signal is connected, the wizard will no longer
358 * send button events to the UI. Rather, the connected QObject has to take
359 * care to propagate those events.
360 * This is used in YQPatternSelector, for example.
368 * Adapt the size of the client area (the ReplacePoint(`id(`contents)) to
369 * fit in its current space.
371 void resizeClientArea();
374 * Show the current help text.
376 * This is useful only if it is obscured by any wizard steps, but it can
377 * safely be called at any time.
382 * Show the current wizard steps, if there are any. If there are none,
388 * Show the current selection tree in the side panel, if there is any. If
389 * there is none, nothing happens.
394 * Set a widget's background pixmap to a gradient pixmap and set the
395 * widget's height (fixed) to that pixmap's height.
397 static void setGradient( QWidget * widget, const QPixmap & pixmap );
400 * Set a widget's background to the lower portion (the bottom
401 * 'croppedHeight' pixels) of a pixmap and set the widget's height (fixed)
402 * to that 'croppedHeight'.
404 static void setBottomCroppedGradient( QWidget * widget,
405 const QPixmap & pixmap,
409 * Bottom-crop a pixmap: Return a pixmap with the bottom 'croppedHeight'
412 static QPixmap bottomCropPixmap( const QPixmap & pixmap, int croppedHeight );
415 * Return the color of pixel( x, y ) of a pixmap.
416 * If pixmap is null defaultColor is returned.
417 * This is a _very_ expensive operation!
419 static QColor pixelColor( const QPixmap & pixmap, int x, int y, const QColor & defaultColor );
425 * Internal notification that the "Back" button has been clicked.
427 void slotBackClicked();
430 * Internal notification that the "Abort" button has been clicked.
432 void slotAbortClicked();
435 * Internal notification that the "Next" button has been clicked.
437 void slotNextClicked();
440 * Propagate button clicked event of release notes button to the
443 void releaseNotesClicked();
446 * Internal notification that [Space] or [Return] has been pressed on a
448 * If the item has an ID, that ID will be returned to UI::UserInput().
450 void sendTreeEvent( Q3ListViewItem * item );
453 * Internal notification that the tree selection has changed.
455 * If the currently selected item has an ID, that ID will be returned to
458 void treeSelectionChanged();
461 * Internal notification that a menu item with numeric ID 'numID' has been
464 void sendMenuEvent( int numID );
471 void layoutTitleBar ( QWidget * parent );
472 void layoutSideBar ( QWidget * parent );
473 void layoutSideBarButtonBox ( QWidget * parent, QPushButton * button );
474 void layoutStepsPanel();
475 void layoutHelpPanel();
476 void layoutTreePanel();
477 void layoutWorkArea ( QFrame * parentHBox );
478 void layoutClientArea( QWidget * parent );
479 void layoutButtonBox( QWidget * parent );
483 * Load gradient pixmaps
485 void loadGradientPixmaps();
488 * Load step status icons
490 void loadStepsIcons();
493 * Destroy the button box's buttons
495 void destroyButtons();
498 * Update all step - use appropriate icons and colors
500 void updateStepStates();
503 * Add a (left or right) margin of the specified width to a widget,
504 * consisting of a fixed height top gradient , a flexible center part (in
505 * the gradient center color) and a fixed height bottom gradient.
507 * The bottom gradient widget is returned as a reference for other
508 * background pixmaps.
510 void addGradientColumn( QWidget * parent, int width = 8 );
513 * Send a wizard event with the specified ID.
515 void sendEvent( const string & id );
518 * Returns 'true' if the application is running on a high-color display,
519 * i.e., on an X visual with more than 8 bit depth.
521 bool highColorDisplay() const;
524 * Notification that a signal is being connected.
526 * Reimplemented from QObject.
528 void connectNotify ( const char * signal );
531 * Notification that a signal is being disconnected.
533 * Reimplemented from QObject.
535 void disconnectNotify ( const char * signal );
538 * Set a button's label.
540 void setButtonLabel( YQWizardButton * button, const QString & newLabel );
543 * Enable or disable a button.
545 void enableButton( YQWizardButton * button, bool enabled );
548 * Set the keyboard focus to a button.
550 void setButtonFocus( YQWizardButton * button );
553 * Set text color and status icon for one wizard step
555 void setStepStatus( YQWizard::Step * step, const QPixmap & icon, const QColor & color );
558 * Find a step with the specified ID. Returns 0 if there is no such step.
560 YQWizard::Step * findStep( const QString & id );
563 * Find a tree item with the specified ID. Tree items without IDs cannot be
565 * Returns the item or 0 if no such item found.
567 YQWizard::TreeItem * findTreeItem( const string & id );
574 string _backButtonLabel;
575 string _abortButtonLabel;
576 string _nextButtonLabel;
580 bool _protectNextButton;
582 bool _sendButtonEvents;
583 Direction _direction;
585 QPixmap _titleBarGradientPixmap;
586 QPixmap _topGradientPixmap;
587 QColor _gradientCenterColor;
588 QColor _gradientTopColor;
589 QPixmap _bottomGradientPixmap;
591 QPixmap _stepCurrentIcon;
592 QPixmap _stepToDoIcon;
593 QPixmap _stepDoneIcon;
595 QColor _stepCurrentColor;
596 QColor _stepToDoColor;
597 QColor _stepDoneColor;
599 QString _currentStepID;
602 Q3WidgetStack * _sideBar;
603 Q3VBox * _stepsPanel;
605 Q3GridLayout * _stepsGrid;
606 QPushButton * _releaseNotesButton;
607 string _releaseNotesButtonId;
608 QPushButton * _helpButton;
610 Q3TextBrowser * _helpBrowser;
611 QPushButton * _stepsButton;
612 QPushButton * _treeButton;
616 Q3VBox * _clientArea;
617 QWidget * _menuBarBox;
619 QLabel * _dialogIcon;
620 QLabel * _dialogHeading;
621 YQAlignment * _contents;
622 YQWizardButton * _backButton;
623 QSpacerItem * _backButtonSpacer;
624 YQWizardButton * _abortButton;
625 YQWizardButton * _nextButton;
626 YReplacePoint * _contentsReplacePoint;
628 Q3PtrList<YQWizard::Step> _stepsList;
629 Q3Dict<YQWizard::Step> _stepsIDs;
630 Q3Dict<YQWizard::TreeItem> _treeIDs;
631 Q3Dict<Q3PopupMenu> _menuIDs;
632 vector<string> _menuEntryIDs;
638 * Helper class to represent a wizard step internally
644 Step( const QString & name = "", const QString & id = "" )
653 * Destructor. Intentionally not deleting the widgets.
657 virtual bool isHeading() const { return false; }
659 QString name() const { return _name; }
660 QLabel * statusLabel() const { return _statusLabel; }
661 QLabel * nameLabel() const { return _nameLabel; }
662 bool isEnabled() const { return _enabled; }
663 const QStringList & id() const { return _idList; }
664 void addID( const QString & id ) { _idList.append( id ); }
665 virtual bool hasID( const QString & id ) { return _idList.find( id ) != _idList.end(); }
667 void setStatusLabel( QLabel * label ) { _statusLabel = label; }
668 void setNameLabel ( QLabel * label ) { _nameLabel = label; }
669 void setEnabled( bool enabled ) { _enabled = enabled; }
674 QLabel * _statusLabel;
682 * Helper class to represent a wizard step heading internally
684 class StepHeading: public Step
688 StepHeading( const QString & name = "" )
692 virtual ~StepHeading() {}
693 virtual bool isHeading() const { return true; }
694 virtual bool hasID( const QString & id ) { return false; }
699 * Helper class for wizard tree item
701 class TreeItem: public QY2ListViewItem
704 TreeItem( QY2ListView * parent,
705 const QString & text,
707 : QY2ListViewItem( parent, text )
711 TreeItem( YQWizard::TreeItem * parent,
712 const QString & text,
714 : QY2ListViewItem( parent, text )
718 virtual QString text(int index) const { return Q3ListViewItem::text(index); }
719 QString text() const { return Q3ListViewItem::text(0); }
720 QString id() const { return _id; }