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 <QGridLayout>
  32 #include <qlabel.h>
  33 #include <QMenu>
  34 #include <qevent.h>
  35 #include <YWizard.h>
  36 #include "YQWizardButton.h"
  37
  38 #include <string>
  39 #include <vector>
  40
  41 class QGridLayout;
  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 QStackedWidget;
  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 protected slots:
 395
 396     /**
 397      * Internal notification that the "Back" button has been clicked.
 398      **/
 399     void slotBackClicked();
 400
 401     /**
 402      * Internal notification that the "Abort" button has been clicked.
 403      **/
 404     void slotAbortClicked();
 405
 406     /**
 407      * Internal notification that the "Next" button has been clicked.
 408      **/
 409     void slotNextClicked();
 410
 411     /**
 412      * Propagate button clicked event of release notes button to the
 413      * application.
 414      **/
 415     void releaseNotesClicked();
 416
 417     /**
 418      * Internal notification that [Space] or [Return] has been pressed on a
 419      * tree item.
 420      * If the item has an ID, that ID will be returned to UI::UserInput().
 421      **/
 422     void sendTreeEvent( QTreeWidgetItem * item );
 423
 424     /**
 425      * Internal notification that the tree selection has changed.
 426      *
 427      * If the currently selected item has an ID, that ID will be returned to
 428      * UI::UserInput().
 429      **/
 430     void treeSelectionChanged();
 431
 432     /**
 433      * Internal notification that a menu item with numeric ID 'numID' has been
 434      * activated.
 435      **/
 436     void sendMenuEvent( int numID );
 437
 438
 439 protected:
 440
 441     // Layout functions
 442
 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     QWidget *layoutWorkArea     ( QWidget * parent );
 450     void layoutClientArea( QWidget * parent );
 451     QLayout *layoutButtonBox( QWidget * parent );
 452
 453     /**
 454      * Destroy the button box's buttons
 455      **/
 456     void destroyButtons();
 457
 458     /**
 459      * Update all step - use appropriate icons and colors
 460      **/
 461     void updateStepStates();
 462
 463     /**
 464      * Send a wizard event with the specified ID.
 465      **/
 466     void sendEvent( const string & id );
 467
 468     /**
 469      * Notification that a signal is being connected.
 470      *
 471      * Reimplemented from QObject.
 472      **/
 473     void connectNotify ( const char * signal );
 474
 475     /**
 476      * Notification that a signal is being disconnected.
 477      *
 478      * Reimplemented from QObject.
 479      **/
 480     void disconnectNotify ( const char * signal );
 481
 482     /**
 483      * Set a button's label.
 484      **/
 485     void setButtonLabel( YQWizardButton * button, const QString & newLabel );
 486
 487     /**
 488      * Enable or disable a button.
 489      **/
 490     void enableButton( YQWizardButton * button, bool enabled );
 491
 492     /**
 493      * Set the keyboard focus to a button.
 494      **/
 495     void setButtonFocus( YQWizardButton * button );
 496
 497     /**
 498      * Find a step with the specified ID. Returns 0 if there is no such step.
 499      **/
 500     YQWizard::Step * findStep( const QString & id );
 501
 502     /**
 503      * Find a tree item with the specified ID. Tree items without IDs cannot be
 504      * found at all.
 505      * Returns the item or 0 if no such item found.
 506      **/
 507     YQWizard::TreeItem * findTreeItem( const string & id );
 508
 509
 510     //
 511     // Data members
 512     //
 513
 514     string      _backButtonLabel;
 515     string      _abortButtonLabel;
 516     string      _nextButtonLabel;
 517
 518     bool        _stepsEnabled;
 519     bool        _treeEnabled;
 520     bool        _protectNextButton;
 521     bool        _stepsDirty;
 522     bool        _sendButtonEvents;
 523     Direction   _direction;
 524
 525     QString     _currentStepID;
 526     QString     _qHelpText;
 527
 528
 529     QStackedWidget *    _sideBar;
 530     QWidget     *       _stepsPanel;
 531     QPushButton *       _releaseNotesButton;
 532     string               _releaseNotesButtonId;
 533     QPushButton *       _helpButton;
 534     QPushButton *               _stepsButton;
 535     QPushButton *               _treeButton;
 536     Q3HBox *                _treePanel;
 537     QY2ListView *               _tree;
 538
 539     QWidget *           _clientArea;
 540     QMenuBar *                  _menuBar;
 541     QLabel *                _dialogIcon;
 542     QLabel *                _dialogHeading;
 543     YQAlignment *           _contents;
 544     YQWizardButton *        _backButton;
 545     YQWizardButton *        _abortButton;
 546     YQWizardButton *        _nextButton;
 547     YReplacePoint *     _contentsReplacePoint;
 548
 549     Q3PtrList<YQWizard::Step>   _stepsList;
 550     Q3Dict<YQWizard::Step>      _stepsIDs;
 551     Q3Dict<YQWizard::TreeItem>  _treeIDs;
 552     Q3Dict<Q3PopupMenu>         _menuIDs;
 553     vector<string>              _menuEntryIDs;
 554
 555
 556 protected:
 557
 558     /**
 559      * Helper class to represent a wizard step internally
 560      **/
 561     class Step
 562     {
 563     public:
 564
 565         Step( const QString & name = "", const QString & id = "" )
 566             : _name( name )
 567             , _statusLabel( 0 )
 568             , _nameLabel(0)
 569             , _enabled( true )
 570             , _idList( id )
 571             , _status( Unset )
 572         {}
 573
 574         /**
 575          * Destructor. Intentionally not deleting the widgets.
 576          **/
 577         virtual ~Step() {}
 578
 579         virtual bool isHeading() const { return false; }
 580
 581         enum Status { Unset, Todo, Current, Done };
 582
 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; }
 590
 591         void setStatusLabel( QLabel * label )   { _statusLabel = label; }
 592         void setNameLabel  ( QLabel * label )   { _nameLabel   = label; }
 593         void setEnabled( bool enabled )         { _enabled = enabled; }
 594
 595         /**
 596          * Set text color and status icon for one wizard step
 597          **/
 598         void setStatus( Status s );
 599
 600     protected:
 601
 602         QString         _name;
 603         QLabel *        _statusLabel;
 604         QLabel *        _nameLabel;
 605         bool            _enabled;
 606         QStringList     _idList;
 607         Status          _status;
 608     };
 609
 610
 611     /**
 612      * Helper class to represent a wizard step heading internally
 613      **/
 614     class StepHeading: public Step
 615     {
 616     public:
 617
 618         StepHeading( const QString & name = "" )
 619             : Step( name, "" )
 620             {}
 621
 622         virtual ~StepHeading() {}
 623         virtual bool isHeading() const { return true; }
 624         virtual bool hasID( const QString & id ) { return false; }
 625     };
 626
 627
 628     /**
 629      * Helper class for wizard tree item
 630      **/
 631     class TreeItem: public QY2ListViewItem
 632     {
 633     public:
 634         TreeItem( QY2ListView *         parent,
 635                   const QString &       text,
 636                   const QString &       id )
 637             : QY2ListViewItem( parent, text )
 638             , _id( id )
 639             {}
 640
 641         TreeItem( YQWizard::TreeItem *  parent,
 642                   const QString &       text,
 643                   const QString &       id )
 644             : QY2ListViewItem( parent, text )
 645             , _id( id )
 646             {}
 647
 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; }
 651
 652     private:
 653         QString _id;
 654     };
 655
 656 }; // class YQWizard
 657
 658
 659
 660 #endif // YQWizard_h