libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YWizard.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:         YWizard.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YWizard_h
00026 #define YWizard_h
00027 
00028 #include "YWidget.h"
00029 
00030 class YMacroRecorder;
00031 class YWizardPrivate;
00032 class YPushButton;
00033 class YReplacePoint;
00034 
00035 #define YWizardID                       "wizard"
00036 #define YWizardContentsReplacePointID   "contents"
00037 
00038 
00039 enum YWizardMode
00040 {
00041     YWizardMode_Standard,       // Normal wizard (help panel or nothing)
00042     YWizardMode_Steps,          // Steps visible in left side panel
00043     YWizardMode_Tree            // Tree in left side panel
00044 };
00045 
00046 
00047 /**
00048  * A wizard is a more complex frame typically used for multi-step workflows:
00049  *
00050  *    +------------+------------------------------------------------+
00051  *    |            |                                                |
00052  *    |            |                                                |
00053  *    |            |                                                |
00054  *    |            |                                                |
00055  *    |            |                                                |
00056  *    |            |                                                |
00057  *    |            |                                                |
00058  *    |            |                                                |
00059  *    |  Side bar  |                 Content Area                   |
00060  *    |            |                (YReplacePoint)                 |
00061  *    |            |                                                |
00062  *    |            |                                                |
00063  *    |            |                                                |
00064  *    |            |                                                |
00065  *    |            |                                                |
00066  *    |            |                                                |
00067  *    |            |  [Back]           [Abort]              [Next]  |
00068  *    +------------+------------------------------------------------+
00069  *
00070  * The side bar can contain help text, a list of steps that are performed, or
00071  * an embedded tree (much like the YTree widget).
00072  *
00073  * The client application creates the wizard and replaces the widget in the
00074  * content area for each step.
00075  *
00076  * The wizard buttons can theoretically be used to do anything, but good UI
00077  * design will stick to the model above: [Back], [Abort], [Next].
00078  *
00079  * If only two buttons are desired, leave the [Back] button's label emtpy. The
00080  * remaining two buttons will be rearranged accordingly in the button area.
00081  *
00082  * In the last step of a multi-step workflow, the [Next] button's label is
00083  * customarily replaced with a label that indicates that this is the last
00084  * step. [Accept] is recommended for that button label: [Finish] (as sometimes
00085  * used in other environments) by no means clearly indicates that this is the
00086  * positive ending, the final "do it" button. Worse, translations of that are
00087  * often downright miserable: To German, [Finish] gets translated as [Beenden]
00088  * which is the same word as "Quit" (used in menus). This does not at all tell
00089  * the user that that button really performs the requested action the
00090  * multi-step wizard is all about.
00091  **/
00092 class YWizard: public YWidget
00093 {
00094 protected:
00095     /**
00096      * Constructor.
00097      *
00098      * If only two buttons are desired, leave 'backButtonLabel' empty.
00099      **/
00100     YWizard( YWidget *                  parent,
00101              const std::string &        backButtonLabel,
00102              const std::string &        abortButtonLabel,
00103              const std::string &        nextButtonLabel,
00104              YWizardMode                wizardMode = YWizardMode_Standard );
00105 
00106 public:
00107 
00108     /**
00109      * Destructor.
00110      **/
00111     virtual ~YWizard();
00112 
00113     /**
00114      * Returns a descriptive name of this widget class for logging,
00115      * debugging etc.
00116      **/
00117     virtual const char * widgetClass() const { return "YWizard"; }
00118 
00119 
00120     //
00121     // Wizard basics
00122     //
00123 
00124     /**
00125      * Return the wizard mode (what kind of wizard this is):
00126      * YWizardMode_Standard, YWizardMode_Steps, YWizardMode_Tree
00127      **/
00128     YWizardMode wizardMode() const;
00129 
00130     /**
00131      * Return the wizard buttons or 0 if there is no such button.
00132      *
00133      * Derived classes are required to implement this.
00134      **/
00135     virtual YPushButton * backButton()  const = 0;
00136     virtual YPushButton * abortButton() const = 0;
00137     virtual YPushButton * nextButton()  const = 0;
00138 
00139     /**
00140      * Return the internal contents ReplacePoint.
00141      *
00142      * Derived classes are required to implement this.
00143      **/
00144     virtual YReplacePoint * contentsReplacePoint() const = 0;
00145 
00146     /**
00147      * Protect the wizard's "Next" button against disabling.
00148      **/
00149     void protectNextButton( bool protect );
00150 
00151     /**
00152      * Check if the wizard's "Next" button is currently protected against
00153      * disabling.
00154      **/
00155     bool nextButtonIsProtected() const;
00156 
00157     /**
00158      * Set the label of one of the wizard buttons (backButton(), abortButton(),
00159      * nextButton() ) if that button is non-null.
00160      *
00161      * The default implementation simply calls button->setLabel( newLabel ).
00162      **/
00163     virtual void setButtonLabel( YPushButton * button, const std::string & newLabel );
00164 
00165     /**
00166      * Set the help text.
00167      **/
00168     virtual void setHelpText( const std::string & helpText ) = 0;
00169 
00170     /**
00171      * Set the dialog icon. An empty icon name clears the current icon.
00172      **/
00173     virtual void setDialogIcon( const std::string & iconName ) = 0;
00174 
00175     /**
00176      * Set the dialog title shown in the window manager's title bar.
00177        An empty string clears the current title.
00178      **/
00179     virtual void setDialogTitle( const std::string & titleText ) = 0;
00180 
00181     /**
00182      * Set the dialog heading.
00183      **/
00184     virtual void setDialogHeading( const std::string & headingText ) = 0;
00185 
00186 
00187     //
00188     // Steps handling
00189     //
00190 
00191     /**
00192      * Add a step for the steps panel on the side bar.
00193      * This only adds the step to the internal list of steps.
00194      * The display is only updated upon calling updateSteps().
00195      **/
00196     virtual void addStep( const std::string & text, const std::string & id ) = 0;
00197 
00198     /**
00199      * Add a step heading for the steps panel on the side bar.
00200      * This only adds the heading to the internal list of steps.
00201      * The display is only updated upon calling updateSteps().
00202      **/
00203     virtual void addStepHeading( const std::string & text ) = 0;
00204 
00205     /**
00206      * Delete all steps and step headings from the internal lists.
00207      * The display is only updated upon calling updateSteps().
00208      **/
00209     virtual void deleteSteps() = 0;
00210 
00211     /**
00212      * Set the current step. This also triggers updateSteps() if necessary.
00213      **/
00214     virtual void setCurrentStep( const std::string & id ) = 0;
00215 
00216     /**
00217      * Update the steps display: Reflect the internal steps and heading lists
00218      * in the layout.
00219      **/
00220     virtual void updateSteps() = 0;
00221 
00222 
00223     //
00224     // Tree handling
00225     //
00226 
00227     /**
00228      * Add a tree item. If "parentID" is an empty string, it will be a root
00229      * item. 'text' is the text that will be displayed in the tree, 'id' the ID
00230      * with which this newly created item can be referenced - and that will be
00231      * returned when the user clicks on a tree item.
00232      **/
00233     virtual void addTreeItem( const std::string & parentID,
00234                               const std::string & text,
00235                               const std::string & id    ) = 0;
00236 
00237     /**
00238      * Select the tree item with the specified ID, if such an item exists.
00239      **/
00240     virtual void selectTreeItem( const std::string & id ) = 0;
00241 
00242     /**
00243      * Returns the current tree selection or an empty string if nothing is
00244      * selected or there is no tree.
00245      **/
00246     virtual std::string currentTreeSelection() = 0;
00247 
00248     /**
00249      * Delete all tree items.
00250      **/
00251     virtual void deleteTreeItems() = 0;
00252 
00253 
00254     //
00255     // Menu handling
00256     //
00257 
00258     /**
00259      * Add a menu to the menu bar. If the menu bar is not visible yet, it will
00260      * be made visible. 'text' is the user-visible text for the menu bar
00261      * (including keyboard shortcuts marked with '&'), 'id' is the menu ID for
00262      * later addMenuEntry() etc. calls.
00263      **/
00264     virtual void addMenu( const std::string & text,
00265                           const std::string & id ) = 0;
00266 
00267     /**
00268      * Add a submenu to the menu with ID 'parentMenuID'.
00269      **/
00270     virtual void addSubMenu( const std::string & parentMenuID,
00271                              const std::string & text,
00272                              const std::string & id ) = 0;
00273 
00274     /**
00275      * Add a menu entry to the menu with ID 'parentMenuID'. 'id' is what will
00276      * be returned by UI::UserInput() etc. when a user activates this menu entry.
00277      **/
00278     virtual void addMenuEntry( const std::string & parentMenuID,
00279                                const std::string & text,
00280                                const std::string & id ) = 0;
00281 
00282     /**
00283      * Add a menu separator to a menu.
00284      **/
00285     virtual void addMenuSeparator( const std::string & parentMenuID ) = 0;
00286 
00287     /**
00288      * Delete all menus and hide the menu bar.
00289      **/
00290     virtual void deleteMenus() = 0;
00291 
00292     /**
00293      * Show a "Release Notes" button above the "Help" button in the steps panel
00294      * with the specified label that will return the specified id to
00295      * UI::UserInput() when clicked.
00296      **/
00297     virtual void showReleaseNotesButton( const std::string & label,
00298                                          const std::string & id ) = 0;
00299 
00300     //
00301     // Misc
00302     //
00303 
00304     /**
00305      * Hide an existing "Release Notes" button.
00306      **/
00307     virtual void hideReleaseNotesButton() = 0;
00308 
00309     /**
00310      * Retranslate internal buttons that are not accessible from the outside:
00311      * - [Help]
00312      * - [Steps]
00313      * - [Tree]
00314      **/
00315     virtual void retranslateInternalButtons() = 0;
00316 
00317     /**
00318      * NOP command to check if a YWizard is running.
00319      **/
00320     void ping();
00321 
00322 
00323     //
00324     // Property handling
00325     //
00326 
00327     /**
00328      * Get a property.
00329      * Reimplemented from YWidget.
00330      *
00331      * This method may throw YUIPropertyExceptions.
00332      **/
00333     virtual YPropertyValue getProperty( const std::string & propertyName );
00334 
00335     /**
00336      * Return this class's property set.
00337      * This also initializes the property upon the first call.
00338      *
00339      * Reimplemented from YWidget.
00340      **/
00341     virtual const YPropertySet & propertySet();
00342 
00343 
00344 private:
00345 
00346     ImplPtr<YWizardPrivate> priv;
00347 };
00348 
00349 
00350 #endif // YWizard_h
 All Classes Functions Variables Enumerations Friends