libyui-qt  2.43.5
/usr/src/RPM/BUILD/libyui-qt-2.43.5/src/YQWizard.h
00001 /*
00002   Copyright (C) 2000-2012 Novell, Inc
00003   This library is free software; you can redistribute it and/or modify
00004   it under the terms of the GNU Lesser General Public License as
00005   published by the Free Software Foundation; either version 2.1 of the
00006   License, or (at your option) version 3.0 of the License. This library
00007   is distributed in the hope that it will be useful, but WITHOUT ANY
00008   WARRANTY; without even the implied warranty of MERCHANTABILITY or
00009   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
00010   License for more details. You should have received a copy of the GNU
00011   Lesser General Public License along with this library; if not, write
00012   to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
00013   Floor, Boston, MA 02110-1301 USA
00014 */
00015 
00016 
00017 /*-/
00018 
00019   File:       YQWizard.h
00020 
00021   Author:     Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 
00026 #ifndef YQWizard_h
00027 #define YQWizard_h
00028 
00029 #include <string>
00030 #include <vector>
00031 
00032 #include <qpixmap.h>
00033 #include <qstringlist.h>
00034 #include "QY2ListView.h"
00035 #include <QGridLayout>
00036 #include <QSplitter>
00037 #include <qlabel.h>
00038 #include <QMenu>
00039 #include <qevent.h>
00040 #include <yui/YWizard.h>
00041 #include "YQWizardButton.h"
00042 
00043 using std::vector;
00044 
00045 class QGridLayout;
00046 class QFrame;
00047 class QSplitter;
00048 class QLabel;
00049 class QMenuBar;
00050 class QPushButton;
00051 class QSpacerItem;
00052 class QToolButton;
00053 class QStackedWidget;
00054 class YReplacePoint;
00055 class QTreeWidgetItem;
00056 class YQAlignment;
00057 class YQReplacePoint;
00058 class QY2ListView;
00059 class QY2HelpDialog;
00060 
00061 
00062 class YQWizard : public QSplitter, public YWizard
00063 {
00064     Q_OBJECT
00065 
00066 protected:
00067     class Step;
00068     class TreeItem;
00069 
00070 public:
00071     /**
00072      * Constructor.
00073      **/
00074     YQWizard( YWidget *         parent,
00075               const std::string &       backButtonLabel,
00076               const std::string &       abortButtonLabel,
00077               const std::string &       nextButtonLabel,
00078               YWizardMode       wizardMode = YWizardMode_Standard );
00079 
00080     /**
00081      * Destructor.
00082      **/
00083     virtual ~YQWizard();
00084 
00085     /**
00086      * Returns a descriptive label of this dialog instance for debugging.
00087      *
00088      * Reimplemented from YWidget.
00089      **/
00090     virtual std::string debugLabel() const;
00091 
00092     enum Direction { Forward, Backward };
00093 
00094     /**
00095      * Returns the current direction of wizard operations - going forward or
00096      * going backward. This can be used to maintain a consistent direction when
00097      * assigning default buttons to a dialog.
00098      **/
00099     Direction direction() const { return _direction; }
00100 
00101     //
00102     // Wizard basics
00103     //
00104 
00105     /**
00106      * Return internal widgets.
00107      *
00108      * Implemented from YWizard.
00109      **/
00110     virtual YQWizardButton * backButton()  const { return _backButton;  }
00111     virtual YQWizardButton * abortButton() const { return _abortButton; }
00112     virtual YQWizardButton * nextButton()  const { return _nextButton;  }
00113 
00114     virtual YReplacePoint * contentsReplacePoint() const { return _contentsReplacePoint; }
00115 
00116     /**
00117      * Set the label of one of the wizard buttons (backButton(), abortButton(),
00118      * nextButton() ) if that button is non-null.
00119      *
00120      * Implemented from YWizard.
00121      **/
00122     virtual void setButtonLabel( YPushButton * button, const std::string & newLabel );
00123 
00124     /**
00125      * Set the help text.
00126      *
00127      * Implemented from YWizard.
00128      **/
00129     virtual void setHelpText( const std::string & helpText );
00130 
00131     /**
00132      * Set the dialog icon. An empty icon name clears the current icon.
00133      *
00134      * Implemented from YWizard.
00135      **/
00136     virtual void setDialogIcon( const std::string & iconName );
00137 
00138     /**
00139      * Set the dialog title shown in window manager's title bar.
00140      * An empty std::string clears the current text.
00141      *
00142      * Implemented from YWizard.
00143      **/
00144     virtual void setDialogTitle( const std::string & titleText );
00145 
00146 
00147     /**
00148      * Set the dialog heading.
00149      *
00150      * Implemented from YWizard.
00151      **/
00152     virtual void setDialogHeading( const std::string & headingText );
00153 
00154 
00155     //
00156     // Steps handling
00157     //
00158 
00159     /**
00160      * Add a step for the steps panel on the side bar.
00161      * This only adds the step to the internal list of steps.
00162      * The display is only updated upon calling updateSteps().
00163      *
00164      * Implemented from YWizard.
00165      **/
00166     virtual void addStep( const std::string & text, const std::string & id );
00167 
00168     /**
00169      * Add a step heading for the steps panel on the side bar.
00170      * This only adds the heading to the internal list of steps.
00171      * The display is only updated upon calling updateSteps().
00172      *
00173      * Implemented from YWizard.
00174      **/
00175     virtual void addStepHeading( const std::string & text );
00176 
00177     /**
00178      * Return list of pointers to steps.
00179      * Not needed outside copySteps() function
00180      *
00181      **/
00182     QList<YQWizard::Step*> stepsList() { return _stepsList; }
00183 
00184     /**
00185      * Create a copy of given wizard's steps set (names & IDs)
00186      * Populates _stepsList structure of current wizard
00187      *
00188      **/
00189     void copySteps( YQWizard *wizard);
00190 
00191     /**
00192      * Delete all steps and step headings from the internal lists.
00193      * The display is only updated upon calling updateSteps().
00194      *
00195      * Implemented from YWizard.
00196      **/
00197     virtual void deleteSteps();
00198 
00199     /**
00200      * Set the current step. This also triggers updateSteps() if necessary.
00201      *
00202      * Implemented from YWizard.
00203      **/
00204     virtual void setCurrentStep( const std::string & id );
00205 
00206     /**
00207      * Return QString ID of currently active step
00208      *
00209      **/
00210     QString currentStep() { return _currentStepID; };
00211 
00212     /**
00213      * Update the steps display: Reflect the internal steps and heading lists
00214      * in the layout.
00215      *
00216      * Implemented from YWizard.
00217      **/
00218     virtual void updateSteps();
00219 
00220 
00221     //
00222     // Tree handling
00223     //
00224 
00225     /**
00226      * Add a tree item. If "parentID" is an empty std::string, it will be a root
00227      * item. 'text' is the text that will be displayed in the tree, 'id' the ID
00228      * with which this newly created item can be referenced - and that will be
00229      * returned when the user clicks on a tree item.
00230      *
00231      * Implemented from YWizard.
00232      **/
00233     virtual void addTreeItem( const std::string & parentID,
00234                               const std::string & text,
00235                               const std::string & id    );
00236 
00237     /**
00238      * Select the tree item with the specified ID, if such an item exists.
00239      *
00240      * Implemented from YWizard.
00241      **/
00242     virtual void selectTreeItem( const std::string & id );
00243 
00244     /**
00245      * Returns the current tree selection or an empty std::string if nothing is
00246      * selected or there is no tree.
00247      *
00248      * Implemented from YWizard.
00249      **/
00250     virtual std::string currentTreeSelection();
00251 
00252     /**
00253      * Delete all tree items.
00254      *
00255      * Implemented from YWizard.
00256      **/
00257     virtual void deleteTreeItems();
00258 
00259 
00260     //
00261     // Menu handling
00262     //
00263 
00264     /**
00265      * Add a menu to the menu bar. If the menu bar is not visible yet, it will
00266      * be made visible. 'text' is the user-visible text for the menu bar
00267      * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
00268      * later addMenuEntry() etc. calls.
00269      *
00270      * Implemented from YWizard.
00271      **/
00272     virtual void addMenu( const std::string & text,
00273                           const std::string & id );
00274 
00275     /**
00276      * Add a submenu to the menu with ID 'parentMenuID'.
00277      *
00278      * Implemented from YWizard.
00279      **/
00280     virtual void addSubMenu( const std::string & parentMenuID,
00281                              const std::string & text,
00282                              const std::string & id );
00283 
00284     /**
00285      * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
00286      * be returned by UI::UserInput() etc. when a user activates this menu entry.
00287      *
00288      * Implemented from YWizard.
00289      **/
00290     virtual void addMenuEntry( const std::string & parentMenuID,
00291                                const std::string & text,
00292                                const std::string & id );
00293 
00294     /**
00295      * Add a menu separator to a menu.
00296      *
00297      * Implemented from YWizard.
00298      **/
00299     virtual void addMenuSeparator( const std::string & parentMenuID );
00300 
00301     /**
00302      * Delete all menus and hide the menu bar.
00303      *
00304      * Implemented from YWizard.
00305      **/
00306     virtual void deleteMenus();
00307 
00308 
00309     //
00310     // Misc
00311     //
00312 
00313     /**
00314      * Show a "Release Notes" button above the "Help" button in the steps panel
00315      * with the specified label that will return the specified id to
00316      * UI::UserInput() when clicked.
00317      *
00318      * The button (or the wizard) will assume ownership of the id and delete it
00319      * in the destructor.
00320      *
00321      * Implemented from YWizard.
00322      **/
00323     virtual void showReleaseNotesButton( const std::string & label,
00324                                          const std::string & id );
00325 
00326     /**
00327      * Hide an existing "Release Notes" button.
00328      *
00329      * Implemented from YWizard.
00330      **/
00331     virtual void hideReleaseNotesButton();
00332 
00333     /**
00334      * Retranslate internal buttons that are not accessible from the outside:
00335      * - [Help]
00336      * - [Steps]
00337      * - [Tree]
00338      *
00339      * Implemented from YWizard.
00340      **/
00341     virtual void retranslateInternalButtons();
00342 
00343     /**
00344      * Event filter.
00345      *
00346      * Reimplemented from QWidget.
00347      **/
00348     virtual bool eventFilter( QObject * obj, QEvent * ev );
00349 
00350     /**
00351      * Return this wizard's work area (the pane right of the side bar).
00352      * This should not be needed outside of YQMainWinDock.
00353      **/
00354     QWidget * workArea() const { return _workArea; }
00355 
00356 
00357     //
00358     // Geometry management
00359     //
00360 
00361     /**
00362      * Preferred width of the widget.
00363      *
00364      * Reimplemented from YWidget.
00365      **/
00366     virtual int preferredWidth();
00367 
00368     /**
00369      * Preferred height of the widget.
00370      *
00371      * Reimplemented from YWidget.
00372      **/
00373     virtual int preferredHeight();
00374 
00375     /**
00376      * Set the new size of the widget.
00377      *
00378      * Reimplemented from YWidget.
00379      **/
00380     virtual void setSize( int newWidth, int newHeight );
00381 
00382     /**
00383      * Returns true if the wizard should follow the first wizard with steps
00384      **/
00385     bool isSecondary() const;
00386 
00387 signals:
00388 
00389     /**
00390      * Emitted when the "Back" or "Cancel" button is clicked.
00391      **/
00392     void backClicked();
00393 
00394     /**
00395      * Emitted when the "Abort" button is clicked.
00396      **/
00397     void abortClicked();
00398 
00399     /**
00400      * Emitted when the "Next" or "OK" button is clicked.
00401      *
00402      * Notice: As long as this signal is connected, the wizard will no longer
00403      * send button events to the UI. Rather, the connected QObject has to take
00404      * care to propagate those events.
00405      * This is used in YQPatternSelector, for example.
00406      **/
00407     void nextClicked();
00408 
00409 
00410 public slots:
00411 
00412     /**
00413      * Adapt the size of the client area (the ReplacePoint(`id(`contents)) to
00414      * fit in its current space.
00415      **/
00416     void resizeClientArea();
00417 
00418     /**
00419      * Show the current help text.
00420      *
00421      * This is useful only if it is obscured by any wizard steps, but it can
00422      * safely be called at any time.
00423      **/
00424     void showHelp();
00425 
00426     /**
00427      * Show the current wizard steps, if there are any. If there are none,
00428      * nothing happens.
00429      **/
00430     void showSteps();
00431 
00432     /**
00433      * Show the current selection tree in the side panel, if there is any. If
00434      * there is none, nothing happens.
00435      **/
00436     void showTree();
00437 
00438 protected slots:
00439 
00440     /**
00441      * Internal notification that the "Back" button has been clicked.
00442      **/
00443     void slotBackClicked();
00444 
00445     /**
00446      * Internal notification that the "Abort" button has been clicked.
00447      **/
00448     void slotAbortClicked();
00449 
00450     /**
00451      * Internal notification that the "Next" button has been clicked.
00452      **/
00453     void slotNextClicked();
00454 
00455     /**
00456      * Propagate button clicked event of release notes button to the
00457      * application.
00458      **/
00459     void releaseNotesClicked();
00460 
00461     /**
00462      * Internal notification that [Space] or [Return] has been pressed on a
00463      * tree item.
00464      * If the item has an ID, that ID will be returned to UI::UserInput().
00465      **/
00466     void sendTreeEvent( QTreeWidgetItem * item );
00467 
00468     /**
00469      * Internal notification that the tree selection has changed.
00470      *
00471      * If the currently selected item has an ID, that ID will be returned to
00472      * UI::UserInput().
00473      **/
00474     void treeSelectionChanged();
00475 
00476     /**
00477      * Internal notification that a menu item with numeric ID 'numID' has been
00478      * activated.
00479      **/
00480     void sendMenuEvent( QAction *action );
00481 
00482 protected:
00483 
00484     // Layout functions
00485 
00486     void layoutTitleBar         ( QWidget * parent );
00487     QLayout *layoutSideBar      ( QWidget * parent );
00488     void layoutSideBarButtonBox ( QWidget * parent, QPushButton * button );
00489     void layoutStepsPanel();
00490     void layoutTreePanel();
00491     QWidget *layoutWorkArea     ( QWidget * parent );
00492     void layoutClientArea       ( QWidget * parent );
00493     QLayout *layoutButtonBox    ( QWidget * parent );
00494 
00495     /**
00496      * Destroy the button box's buttons
00497      **/
00498     void destroyButtons();
00499 
00500     /**
00501      * Update all step - use appropriate icons and colors
00502      **/
00503     void updateStepStates();
00504 
00505     /**
00506      * Send a wizard event with the specified ID.
00507      **/
00508     void sendEvent( const std::string & id );
00509 
00510     /**
00511      * Notification that a signal is being connected.
00512      *
00513      * Reimplemented from QObject.
00514      **/
00515     void connectNotify ( const char * signal );
00516 
00517     /**
00518      * Notification that a signal is being disconnected.
00519      *
00520      * Reimplemented from QObject.
00521      **/
00522     void disconnectNotify ( const char * signal );
00523 
00524     /**
00525      * Set a button's label.
00526      **/
00527     void setButtonLabel( YQWizardButton * button, const QString & newLabel );
00528 
00529     /**
00530      * Enable or disable a button.
00531      **/
00532     void enableButton( YQWizardButton * button, bool enabled );
00533 
00534     /**
00535      * Set the keyboard focus to a button.
00536      **/
00537     void setButtonFocus( YQWizardButton * button );
00538 
00539     /**
00540      * Find a step with the specified ID. Returns 0 if there is no such step.
00541      **/
00542     YQWizard::Step * findStep( const QString & id );
00543 
00544     /**
00545      * Find a tree item with the specified ID. Tree items without IDs cannot be
00546      * found at all.
00547      * Returns the item or 0 if no such item found.
00548      **/
00549     YQWizard::TreeItem * findTreeItem( const std::string & id );
00550 
00551 
00552     //
00553     // Data members
00554     //
00555 
00556     std::string _backButtonLabel;
00557     std::string _abortButtonLabel;
00558     std::string _nextButtonLabel;
00559 
00560     bool        _stepsEnabled;
00561     bool        _stepsRegistered;
00562     bool        _treeEnabled;
00563     bool        _protectNextButton;
00564     bool        _stepsDirty;
00565     bool        _sendButtonEvents;
00566     Direction   _direction;
00567 
00568     QString     _currentStepID;
00569     QString     _qHelpText;
00570 
00571     QY2HelpDialog *     _helpDlg;
00572 
00573     QStackedWidget *    _sideBar;
00574     QWidget     *       _stepsPanel;
00575     QPushButton *       _releaseNotesButton;
00576     std::string          _releaseNotesButtonId;
00577     QPushButton *       _helpButton;
00578     QPushButton *               _stepsButton;
00579     QPushButton *               _treeButton;
00580     QFrame *                _treePanel;
00581     QY2ListView *               _tree;
00582 
00583     QFrame *            _workArea;
00584     QWidget *           _clientArea;
00585     QMenuBar *                  _menuBar;
00586     QLabel *                _dialogIcon;
00587     QLabel *                _dialogHeading;
00588     YQAlignment *           _contents;
00589     YQWizardButton *        _backButton;
00590     YQWizardButton *        _abortButton;
00591     YQWizardButton *        _nextButton;
00592     YReplacePoint *     _contentsReplacePoint;
00593 
00594     QList<YQWizard::Step*>      _stepsList;
00595     QHash<QString,YQWizard::Step*>      _stepsIDs;
00596     QHash<QString,YQWizard::TreeItem*>  _treeIDs;
00597     QHash<QString,QMenu*>               _menuIDs;
00598     QHash<QAction*, std::string>                _menuEntryIDs;
00599 
00600     QIcon _previousWindowIcon;
00601 
00602 private:
00603     static YQWizard *main_wizard;
00604 
00605 protected:
00606 
00607     /**
00608      * Helper class to represent a wizard step internally
00609      **/
00610     class Step
00611     {
00612     public:
00613 
00614         Step( const QString & name = "", const QString & id = "" )
00615             : _name( name )
00616             , _statusLabel( 0 )
00617             , _nameLabel(0)
00618             , _enabled( true )
00619             , _idList( id )
00620             , _status( Unset )
00621         {}
00622 
00623         /**
00624          * Destructor. Intentionally not deleting the widgets.
00625          **/
00626         virtual ~Step();
00627 
00628         virtual bool isHeading() const { return false; }
00629 
00630         enum Status { Unset, Todo, Current, Done };
00631 
00632         QString  name()         const { return _name;           }
00633         QLabel * statusLabel()  const { return _statusLabel;    }
00634         QLabel * nameLabel()    const { return _nameLabel;      }
00635         bool     isEnabled()    const { return _enabled;        }
00636         const QStringList & id() const { return _idList;        }
00637         void addID( const QString & id ) { _idList.append( id ); }
00638         virtual bool hasID( const QString & id ) { return _idList.indexOf( id ) != -1; }
00639 
00640         void setStatusLabel( QLabel * label )   { _statusLabel = label; }
00641         void setNameLabel  ( QLabel * label )   { _nameLabel   = label; }
00642         void setEnabled( bool enabled )         { _enabled = enabled; }
00643 
00644         void deleteLabels();
00645 
00646         /**
00647          * Set text color and status icon for one wizard step
00648          **/
00649         void setStatus( Status s );
00650 
00651     protected:
00652 
00653         QString         _name;
00654         QLabel *        _statusLabel;
00655         QLabel *        _nameLabel;
00656         bool            _enabled;
00657         QStringList     _idList;
00658         Status          _status;
00659 
00660     private:
00661         Q_DISABLE_COPY(Step);
00662     };
00663 
00664 
00665     /**
00666      * Helper class to represent a wizard step heading internally
00667      **/
00668     class StepHeading: public Step
00669     {
00670     public:
00671 
00672         StepHeading( const QString & name = "" )
00673             : Step( name, "" )
00674             {}
00675 
00676         virtual ~StepHeading() {}
00677         virtual bool isHeading() const { return true; }
00678         virtual bool hasID( const QString & id ) { return false; }
00679 
00680     private:
00681         Q_DISABLE_COPY(StepHeading);
00682     };
00683 
00684 
00685     /**
00686      * Helper class for wizard tree item
00687      **/
00688     class TreeItem: public QY2ListViewItem
00689     {
00690     public:
00691         TreeItem( QY2ListView *         parent,
00692                   const QString &       text,
00693                   const QString &       id )
00694             : QY2ListViewItem( parent, text )
00695             , _id( id )
00696             {}
00697 
00698         TreeItem( YQWizard::TreeItem *  parent,
00699                   const QString &       text,
00700                   const QString &       id )
00701             : QY2ListViewItem( parent, text )
00702             , _id( id )
00703             {}
00704 
00705         virtual QString text(int index) const { return QTreeWidgetItem::text(index); }
00706         QString text() const { return QTreeWidgetItem::text(0); }
00707         QString id()   const { return _id; }
00708 
00709     private:
00710         QString _id;
00711     };
00712 
00713 }; // class YQWizard
00714 
00715 
00716 
00717 #endif // YQWizard_h
 All Classes Functions Variables