libyui
3.0.10
|
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