src/YQWizard.h

   1 /*---------------------------------------------------------------------\
   2 |                                                                      |
   3 |                      __   __    ____ _____ ____                      |
   4 |                      \ \ / /_ _/ ___|_   _|___ \                     |
   5 |                       \ V / _` \___ \ | |   __) |                    |
   6 |                        | | (_| |___) || |  / __/                     |
   7 |                        |_|\__,_|____/ |_| |_____|                    |
   8 |                                                                      |
   9 |                               core system                            |
  10 |                                                    (c) SuSE Linux AG |
  11 \----------------------------------------------------------------------/
  12
  13   File:       YQWizard.h
  14
  15   Author:     Stefan Hundhammer <sh@suse.de>
  16
  17 /-*/
  18
  19
  20 #ifndef YQWizard_h
  21 #define YQWizard_h
  22
  23 #include <string>
  24 #include <q3vbox.h>
  25 #include <qpixmap.h>
  26 #include <q3ptrlist.h>
  27 #include <qstringlist.h>
  28 #include <q3dict.h>
  29 #include "QY2ListView.h"
  30 //Added by qt3to4:
  31 #include <q3gridlayout.h>
  32 #include <qlabel.h>
  33 #include <q3popupmenu.h>
  34 #include <qevent.h>
  35 #include <YWizard.h>
  36 #include "YQWizardButton.h"
  37
  38 #include <string>
  39 #include <vector>
  40
  41 class Q3GridLayout;
  42 class QFrame;
  43 class QLabel;
  44 class QMenuBar;
  45 class Q3PopupMenu;
  46 class QPushButton;
  47 class QSpacerItem;
  48 class Q3TextBrowser;
  49 class QToolButton;
  50 class Q3WidgetStack;
  51 class YReplacePoint;
  52 class QTreeWidgetItem;
  53 class YQAlignment;
  54 class YQReplacePoint;
  55 class QY2ListView;
  56
  57
  58 class YQWizard : public QFrame, public YWizard
  59 {
  60     Q_OBJECT
  61
  62 protected:
  63     class Step;
  64     class TreeItem;
  65
  66 public:
  67     /**
  68      * Constructor.
  69      **/
  70     YQWizard( YWidget *         parent,
  71               const string &    backButtonLabel,
  72               const string &    abortButtonLabel,
  73               const string &    nextButtonLabel,
  74               YWizardMode       wizardMode = YWizardMode_Standard );
  75
  76     /**
  77      * Destructor.
  78      **/
  79     virtual ~YQWizard();
  80
  81     /**
  82      * Returns a descriptive label of this dialog instance for debugging.
  83      *
  84      * Reimplemented from YWidget.
  85      **/
  86     virtual string debugLabel();
  87
  88     enum Direction { Forward, Backward };
  89
  90     /**
  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.
  94      **/
  95     Direction direction() const { return _direction; }
  96
  97     //
  98     // Wizard basics
  99     //
 100
 101     /**
 102      * Return internal widgets.
 103      *
 104      * Implemented from YWizard.
 105      **/
 106     virtual YQWizardButton * backButton()  const { return _backButton;  }
 107     virtual YQWizardButton * abortButton() const { return _abortButton; }
 108     virtual YQWizardButton * nextButton()  const { return _nextButton;  }
 109
 110     virtual YReplacePoint * contentsReplacePoint() const { return _contentsReplacePoint; }
 111
 112     /**
 113      * Set the label of one of the wizard buttons (backButton(), abortButton(),
 114      * nextButton() ) if that button is non-null.
 115      *
 116      * Implemented from YWizard.
 117      **/
 118     virtual void setButtonLabel( YPushButton * button, const string & newLabel );
 119
 120     /**
 121      * Set the help text.
 122      *
 123      * Implemented from YWizard.
 124      **/
 125     virtual void setHelpText( const string & helpText );
 126
 127     /**
 128      * Set the dialog icon. An empty icon name clears the current icon.
 129      *
 130      * Implemented from YWizard.
 131      **/
 132     virtual void setDialogIcon( const string & iconName );
 133
 134     /**
 135      * Set the dialog heading.
 136      *
 137      * Implemented from YWizard.
 138      **/
 139     virtual void setDialogHeading( const string & headingText );
 140
 141
 142     //
 143     // Steps handling
 144     //
 145
 146     /**
 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().
 150      *
 151      * Implemented from YWizard.
 152      **/
 153     virtual void addStep( const string & text, const string & id );
 154
 155     /**
 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().
 159      *
 160      * Implemented from YWizard.
 161      **/
 162     virtual void addStepHeading( const string & text );
 163
 164     /**
 165      * Delete all steps and step headings from the internal lists.
 166      * The display is only updated upon calling updateSteps().
 167      *
 168      * Implemented from YWizard.
 169      **/
 170     virtual void deleteSteps();
 171
 172     /**
 173      * Set the current step. This also triggers updateSteps() if necessary.
 174      *
 175      * Implemented from YWizard.
 176      **/
 177     virtual void setCurrentStep( const string & id );
 178
 179     /**
 180      * Update the steps display: Reflect the internal steps and heading lists
 181      * in the layout.
 182      *
 183      * Implemented from YWizard.
 184      **/
 185     virtual void updateSteps();
 186
 187
 188     //
 189     // Tree handling
 190     //
 191
 192     /**
 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.
 197      *
 198      * Implemented from YWizard.
 199      **/
 200     virtual void addTreeItem( const string & parentID,
 201                               const string & text,
 202                               const string & id );
 203
 204     /**
 205      * Select the tree item with the specified ID, if such an item exists.
 206      *
 207      * Implemented from YWizard.
 208      **/
 209     virtual void selectTreeItem( const string & id );
 210
 211     /**
 212      * Returns the current tree selection or an empty string if nothing is
 213      * selected or there is no tree.
 214      *
 215      * Implemented from YWizard.
 216      **/
 217     virtual std::string currentTreeSelection();
 218
 219     /**
 220      * Delete all tree items.
 221      *
 222      * Implemented from YWizard.
 223      **/
 224     virtual void deleteTreeItems();
 225
 226
 227     //
 228     // Menu handling
 229     //
 230
 231     /**
 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.
 236      *
 237      * Implemented from YWizard.
 238      **/
 239     virtual void addMenu( const string & text,
 240                           const string & id );
 241
 242     /**
 243      * Add a submenu to the menu with ID 'parentMenuID'.
 244      *
 245      * Implemented from YWizard.
 246      **/
 247     virtual void addSubMenu( const string & parentMenuID,
 248                              const string & text,
 249                              const string & id );
 250
 251     /**
 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.
 254      *
 255      * Implemented from YWizard.
 256      **/
 257     virtual void addMenuEntry( const string & parentMenuID,
 258                                const string & text,
 259                                const string & id );
 260
 261     /**
 262      * Add a menu separator to a menu.
 263      *
 264      * Implemented from YWizard.
 265      **/
 266     virtual void addMenuSeparator( const string & parentMenuID );
 267
 268     /**
 269      * Delete all menus and hide the menu bar.
 270      *
 271      * Implemented from YWizard.
 272      **/
 273     virtual void deleteMenus();
 274
 275
 276     //
 277     // Misc
 278     //
 279
 280     /**
 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.
 284      *
 285      * The button (or the wizard) will assume ownership of the id and delete it
 286      * in the destructor.
 287      *
 288      * Implemented from YWizard.
 289      **/
 290     virtual void showReleaseNotesButton( const string & label,
 291                                          const string & id );
 292
 293     /**
 294      * Hide an existing "Release Notes" button.
 295      *
 296      * Implemented from YWizard.
 297      **/
 298     virtual void hideReleaseNotesButton();
 299
 300     /**
 301      * Retranslate internal buttons that are not accessible from the outside:
 302      * - [Help]
 303      * - [Steps]
 304      * - [Tree]
 305      *
 306      * Implemented from YWizard.
 307      **/
 308     virtual void retranslateInternalButtons();
 309
 310     /**
 311      * Event filter.
 312      *
 313      * Reimplemented from QWidget.
 314      **/
 315     virtual bool eventFilter( QObject * obj, QEvent * ev );
 316
 317     //
 318     // Geometry management
 319     //
 320
 321     /**
 322      * Preferred width of the widget.
 323      *
 324      * Reimplemented from YWidget.
 325      **/
 326     virtual int preferredWidth();
 327
 328     /**
 329      * Preferred height of the widget.
 330      *
 331      * Reimplemented from YWidget.
 332      **/
 333     virtual int preferredHeight();
 334
 335     /**
 336      * Set the new size of the widget.
 337      *
 338      * Reimplemented from YWidget.
 339      **/
 340     virtual void setSize( int newWidth, int newHeight );
 341
 342
 343 signals:
 344
 345     /**
 346      * Emitted when the "Back" or "Cancel" button is clicked.
 347      **/
 348     void backClicked();
 349
 350     /**
 351      * Emitted when the "Abort" button is clicked.
 352      **/
 353     void abortClicked();
 354
 355     /**
 356      * Emitted when the "Next" or "OK" button is clicked.
 357      *
 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.
 362      **/
 363     void nextClicked();
 364
 365
 366 public slots:
 367
 368     /**
 369      * Adapt the size of the client area (the ReplacePoint(`id(`contents)) to
 370      * fit in its current space.
 371      **/
 372     void resizeClientArea();
 373
 374     /**
 375      * Show the current help text.
 376      *
 377      * This is useful only if it is obscured by any wizard steps, but it can
 378      * safely be called at any time.
 379      **/
 380     void showHelp();
 381
 382     /**
 383      * Show the current wizard steps, if there are any. If there are none,
 384      * nothing happens.
 385      **/
 386     void showSteps();
 387
 388     /**
 389      * Show the current selection tree in the side panel, if there is any. If
 390      * there is none, nothing happens.
 391      **/
 392     void showTree();
 393
 394     /**
 395      * Set a widget's background pixmap to a gradient pixmap and set the
 396      * widget's height (fixed) to that pixmap's height.
 397      **/
 398     static void setGradient( QWidget * widget, const QPixmap & pixmap );
 399
 400     /**
 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'.
 404      **/
 405     static void setBottomCroppedGradient( QWidget * widget,
 406                                           const QPixmap & pixmap,
 407                                           int croppedHeight );
 408
 409     /**
 410      * Bottom-crop a pixmap: Return a pixmap with the bottom 'croppedHeight'
 411      * pixels.
 412      **/
 413     static QPixmap bottomCropPixmap( const QPixmap & pixmap, int croppedHeight );
 414
 415     /**
 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!
 419      **/
 420     static QColor pixelColor( const QPixmap & pixmap, int x, int y, const QColor & defaultColor );
 421
 422
 423 protected slots:
 424
 425     /**
 426      * Internal notification that the "Back" button has been clicked.
 427      **/
 428     void slotBackClicked();
 429
 430     /**
 431      * Internal notification that the "Abort" button has been clicked.
 432      **/
 433     void slotAbortClicked();
 434
 435     /**
 436      * Internal notification that the "Next" button has been clicked.
 437      **/
 438     void slotNextClicked();
 439
 440     /**
 441      * Propagate button clicked event of release notes button to the
 442      * application.
 443      **/
 444     void releaseNotesClicked();
 445
 446     /**
 447      * Internal notification that [Space] or [Return] has been pressed on a
 448      * tree item.
 449      * If the item has an ID, that ID will be returned to UI::UserInput().
 450      **/
 451     void sendTreeEvent( QTreeWidgetItem * item );
 452
 453     /**
 454      * Internal notification that the tree selection has changed.
 455      *
 456      * If the currently selected item has an ID, that ID will be returned to
 457      * UI::UserInput().
 458      **/
 459     void treeSelectionChanged();
 460
 461     /**
 462      * Internal notification that a menu item with numeric ID 'numID' has been
 463      * activated.
 464      **/
 465     void sendMenuEvent( int numID );
 466
 467
 468 protected:
 469
 470     // Layout functions
 471
 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 );
 481
 482
 483     /**
 484      * Load gradient pixmaps
 485      **/
 486     void loadGradientPixmaps();
 487
 488     /**
 489      * Load step status icons
 490      **/
 491     void loadStepsIcons();
 492
 493     /**
 494      * Destroy the button box's buttons
 495      **/
 496     void destroyButtons();
 497
 498     /**
 499      * Update all step - use appropriate icons and colors
 500      **/
 501     void updateStepStates();
 502
 503     /**
 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.
 507      *
 508      * The bottom gradient widget is returned as a reference for other
 509      * background pixmaps.
 510      **/
 511     void addGradientColumn( QWidget * parent, int width = 8 );
 512
 513     /**
 514      * Send a wizard event with the specified ID.
 515      **/
 516     void sendEvent( const string & id );
 517
 518     /**
 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.
 521      **/
 522     bool highColorDisplay() const;
 523
 524     /**
 525      * Notification that a signal is being connected.
 526      *
 527      * Reimplemented from QObject.
 528      **/
 529     void connectNotify ( const char * signal );
 530
 531     /**
 532      * Notification that a signal is being disconnected.
 533      *
 534      * Reimplemented from QObject.
 535      **/
 536     void disconnectNotify ( const char * signal );
 537
 538     /**
 539      * Set a button's label.
 540      **/
 541     void setButtonLabel( YQWizardButton * button, const QString & newLabel );
 542
 543     /**
 544      * Enable or disable a button.
 545      **/
 546     void enableButton( YQWizardButton * button, bool enabled );
 547
 548     /**
 549      * Set the keyboard focus to a button.
 550      **/
 551     void setButtonFocus( YQWizardButton * button );
 552
 553     /**
 554      * Set text color and status icon for one wizard step
 555      **/
 556     void setStepStatus( YQWizard::Step * step, const QPixmap & icon, const QColor & color );
 557
 558     /**
 559      * Find a step with the specified ID. Returns 0 if there is no such step.
 560      **/
 561     YQWizard::Step * findStep( const QString & id );
 562
 563     /**
 564      * Find a tree item with the specified ID. Tree items without IDs cannot be
 565      * found at all.
 566      * Returns the item or 0 if no such item found.
 567      **/
 568     YQWizard::TreeItem * findTreeItem( const string & id );
 569
 570
 571     //
 572     // Data members
 573     //
 574
 575     string      _backButtonLabel;
 576     string      _abortButtonLabel;
 577     string      _nextButtonLabel;
 578
 579     bool        _stepsEnabled;
 580     bool        _treeEnabled;
 581     bool        _protectNextButton;
 582     bool        _stepsDirty;
 583     bool        _sendButtonEvents;
 584     Direction   _direction;
 585
 586     QPixmap     _titleBarGradientPixmap;
 587     QPixmap     _topGradientPixmap;
 588     QColor      _gradientCenterColor;
 589     QColor      _gradientTopColor;
 590     QPixmap     _bottomGradientPixmap;
 591
 592     QPixmap     _stepCurrentIcon;
 593     QPixmap     _stepToDoIcon;
 594     QPixmap     _stepDoneIcon;
 595
 596     QColor      _stepCurrentColor;
 597     QColor      _stepToDoColor;
 598     QColor      _stepDoneColor;
 599
 600     QString     _currentStepID;
 601
 602
 603     Q3WidgetStack *     _sideBar;
 604     Q3VBox *                _stepsPanel;
 605     Q3VBox *                    _stepsBox;
 606     Q3GridLayout *                  _stepsGrid;
 607     QPushButton *               _releaseNotesButton;
 608     string                          _releaseNotesButtonId;
 609     QPushButton *               _helpButton;
 610     Q3HBox *                _helpPanel;
 611     Q3TextBrowser *             _helpBrowser;
 612     QPushButton *               _stepsButton;
 613     QPushButton *               _treeButton;
 614     Q3HBox *                _treePanel;
 615     QY2ListView *               _tree;
 616
 617     Q3VBox *            _clientArea;
 618     QWidget *               _menuBarBox;
 619     QMenuBar *                  _menuBar;
 620     QLabel *                _dialogIcon;
 621     QLabel *                _dialogHeading;
 622     YQAlignment *           _contents;
 623     YQWizardButton *        _backButton;
 624     QSpacerItem *           _backButtonSpacer;
 625     YQWizardButton *        _abortButton;
 626     YQWizardButton *        _nextButton;
 627     YReplacePoint *     _contentsReplacePoint;
 628
 629     Q3PtrList<YQWizard::Step>   _stepsList;
 630     Q3Dict<YQWizard::Step>      _stepsIDs;
 631     Q3Dict<YQWizard::TreeItem>  _treeIDs;
 632     Q3Dict<Q3PopupMenu>         _menuIDs;
 633     vector<string>              _menuEntryIDs;
 634
 635
 636 protected:
 637
 638     /**
 639      * Helper class to represent a wizard step internally
 640      **/
 641     class Step
 642     {
 643     public:
 644
 645         Step( const QString & name = "", const QString & id = "" )
 646             : _name( name )
 647             , _statusLabel( 0 )
 648             , _nameLabel(0)
 649             , _enabled( true )
 650             , _idList( id )
 651         {}
 652
 653         /**
 654          * Destructor. Intentionally not deleting the widgets.
 655          **/
 656         virtual ~Step() {}
 657
 658         virtual bool isHeading() const { return false; }
 659
 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(); }
 667
 668         void setStatusLabel( QLabel * label )   { _statusLabel = label; }
 669         void setNameLabel  ( QLabel * label )   { _nameLabel   = label; }
 670         void setEnabled( bool enabled )         { _enabled = enabled; }
 671
 672     protected:
 673
 674         QString         _name;
 675         QLabel *        _statusLabel;
 676         QLabel *        _nameLabel;
 677         bool            _enabled;
 678         QStringList     _idList;
 679     };
 680
 681
 682     /**
 683      * Helper class to represent a wizard step heading internally
 684      **/
 685     class StepHeading: public Step
 686     {
 687     public:
 688
 689         StepHeading( const QString & name = "" )
 690             : Step( name, "" )
 691             {}
 692
 693         virtual ~StepHeading() {}
 694         virtual bool isHeading() const { return true; }
 695         virtual bool hasID( const QString & id ) { return false; }
 696     };
 697
 698
 699     /**
 700      * Helper class for wizard tree item
 701      **/
 702     class TreeItem: public QY2ListViewItem
 703     {
 704     public:
 705         TreeItem( QY2ListView *         parent,
 706                   const QString &       text,
 707                   const QString &       id )
 708             : QY2ListViewItem( parent, text )
 709             , _id( id )
 710             {}
 711
 712         TreeItem( YQWizard::TreeItem *  parent,
 713                   const QString &       text,
 714                   const QString &       id )
 715             : QY2ListViewItem( parent, text )
 716             , _id( id )
 717             {}
 718
 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; }
 722
 723     private:
 724         QString _id;
 725     };
 726
 727 }; // class YQWizard
 728
 729
 730
 731 #endif // YQWizard_h