1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef SVTOOLS_INC_ROADMAPWIZARD_HXX 25 #define SVTOOLS_INC_ROADMAPWIZARD_HXX 26 27 #include "svtools/svtdllapi.h" 28 #include <svtools/wizardmachine.hxx> 29 30 //........................................................................ 31 namespace svt 32 { 33 //........................................................................ 34 35 struct RoadmapWizardImpl; 36 class RoadmapWizard; 37 38 struct RoadmapWizardTypes 39 { 40 public: 41 typedef sal_Int16 PathId; 42 typedef ::std::vector< WizardTypes::WizardState > WizardPath; 43 typedef TabPage* (* RoadmapPageFactory)( RoadmapWizard& ); 44 }; 45 46 //==================================================================== 47 //= RoadmapWizard 48 //==================================================================== 49 /** is - no, not a wizard for a raodmap, but the base class for wizards 50 <em>supporting</em> a roadmap. 51 52 The basic new concept introduced is a <em>path</em>:<br/> 53 A <em>path</em> is a sequence of states, which are to be executed in a linear order. 54 Elements in the path can be skipped, depending on choices the user makes. 55 56 In the most simple wizards, you will have only one path consisting of <code>n</code> elements, 57 which are to be visited successively. 58 59 In a slightly more complex wizard, you will have one linear path, were certain 60 steps might be skipped due to user input. For instance, the user may decide to not specify 61 certain aspects of the to-be-created object (e.g. by unchecking a check box), 62 and the wizard then will simply disable the step which corresponds to this step. 63 64 In a yet more advanced wizards, you will have several paths of length <code>n1</code> and 65 <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code> 66 is at least 1), and an arbitrary number of other states. 67 */ 68 class SVT_DLLPUBLIC RoadmapWizard : public OWizardMachine, public RoadmapWizardTypes 69 { 70 private: 71 RoadmapWizardImpl* m_pImpl; 72 73 public: 74 RoadmapWizard( 75 Window* _pParent, 76 const ResId& _rRes, 77 sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP 78 ); 79 RoadmapWizard( 80 Window* _pParent, 81 const WinBits i_nStyle, 82 sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP 83 ); 84 ~RoadmapWizard( ); 85 86 void SetRoadmapBitmap( const BitmapEx& _rBitmap ); 87 const BitmapEx& GetRoadmapBitmap( ) const; 88 89 void SetRoadmapHelpId( const rtl::OString& _rId ); 90 const rtl::OString& GetRoadmapHelpId() const; 91 92 void SetRoadmapInteractive( sal_Bool _bInteractive ); 93 sal_Bool IsRoadmapInteractive(); 94 virtual void Resize(); 95 virtual void StateChanged( StateChangedType nStateChange ); 96 97 // returns whether a given state is enabled 98 bool isStateEnabled( WizardState _nState ) const; 99 100 // WizardDialog overridables 101 virtual bool canAdvance() const; 102 virtual void updateTravelUI(); 103 104 protected: 105 /** declares a valid path in the wizard 106 107 The very first path which is declared is automatically activated. 108 109 Note that all paths which are declared must have the very first state in 110 common. Also note that due to a restriction of the very base class (<type>WizardDialog</type>), 111 this common first state must be 0. 112 113 You cannot declare new paths once the wizard started, so it's recommended that 114 you do all declarations within your derivee's constructor. 115 116 @see activatePath 117 118 @param _nId 119 the unique id you wish to give this path. This id can later on be used 120 to refer to the path which you just declared 121 122 @param _nFirstState 123 the first state in this path. Must not be WZS_INVALID_STATE.<br/> 124 Declare an arbitrary number of states after this one, and terminate the sequence 125 with a WZS_INVALID_STATE. 126 */ 127 void declarePath( PathId _nPathId, WizardState _nFirstState, ... ); 128 void declarePath( PathId _nPathId, const WizardPath& _lWizardStates); 129 130 /** provides basic information about a state 131 132 The given display name is used in the default implementation of getStateDisplayName, 133 and the given factory is used in the default implementation of createPage. 134 */ 135 void describeState( WizardState _nState, const String& _rStateDisplayName, RoadmapPageFactory _pPageFactory ); 136 137 /** activates a path which has previously been declared with <member>declarePath</member> 138 139 You can only activate paths which share the first <code>k</code> states with the path 140 which is previously active (if any), where <code>k</code> is the index of the 141 current state within the current path. 142 143 <example> 144 Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after 145 step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>, 146 and after this, you finish in state <code>5</code>.<br/> 147 Now if the first path is active, and your current state is <code>1</code>, then you can 148 easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/> 149 However, if your current state is <code>2</code>, then you can not switch to the second 150 path anymore. 151 </example> 152 153 @param _nPathId 154 the id of the path. The path must have been declared (under this id) with 155 <member>declarePath</member> before it can be activated. 156 157 @param _bDecideForIt 158 If <TRUE/>, the path will be completely activated, even if it is a conflicting path 159 (i.e. there is another path which shares the first <code>k</code> states with 160 the to-be-activated path.)<br/> 161 If <FALSE/>, then the new path is checked for conflicts with other paths. If such 162 conflicts exists, the path is not completely activated, but only up to the point 163 where it does <em>not</em> conflict.<br/> 164 With the paths in the example above, if you activate the second path (when both are 165 already declared), then only steps <code>0</code> and <code>1</code> are activated, 166 since they are common to both paths. 167 */ 168 void activatePath( PathId _nPathId, bool _bDecideForIt = false ); 169 170 /** determine the next state to travel from the given one 171 172 This method (which is declared in <type>OWizardMachine</type> and overwritten here) 173 ensures that traveling happens along the active path. 174 175 @see activatePath 176 */ 177 virtual WizardState determineNextState( WizardState _nCurrentState ) const; 178 179 /** en- or disables a state 180 181 In the wizard's roadmap, states to travel to can be freely chosen. To prevent 182 users from selecting a state which is currently not available, you can declare this 183 state as being disabled. 184 185 A situation where you need this may be when you have a checkbox which, when checked 186 by the user, enables a page with additional settings. As long as this checkbox is 187 not checked, the respective state would be disabled. 188 189 Note that in theory, you can declare multiple paths, instead of disabling states. 190 For instance, if you have a path where one state can be potentially disabled, then 191 you could declare a second path, which does not contain this state. However, the 192 disadvantage is that then, not the complete path would be visible in the roadmap, 193 but only all steps up to the point where the both paths diverge.<br/> 194 Another disadvantage is that the number of needed paths grows exponentially with 195 the number of states which can be potentially disabled. 196 197 @see declarePath 198 */ 199 void enableState( WizardState _nState, bool _bEnable = true ); 200 201 /** returns true if and only if the given state is known in at least one declared path 202 */ 203 bool knowsState( WizardState _nState ) const; 204 205 // OWizardMachine overriables 206 virtual void enterState( WizardState _nState ); 207 208 /** returns a human readable name for a given state 209 210 There is a default implementation for this method, which returns the display name 211 as given in a call to describeState. If there is no description for the given state, 212 this is worth an assertion in a non-product build, and then an empty string is 213 returned. 214 */ 215 virtual String getStateDisplayName( WizardState _nState ) const; 216 217 /** creates a page for a given state 218 219 This member is inherited from OWizardMachine, and default-implemented in this class 220 for all states which have been described using describeState. 221 */ 222 virtual TabPage* createPage( WizardState _nState ); 223 224 /** asks for a new label of the wizard page 225 226 */ 227 void updateRoadmapItemLabel( WizardState _nState ); 228 229 protected: 230 #if OSL_DEBUG_LEVEL > 0 231 const sal_Char* checkInvariants() const; 232 friend const char* CheckInvariants( const void* pVoid ); 233 #endif 234 235 private: 236 SVT_DLLPRIVATE void ResizeFixedLine(); 237 238 DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, void* ); 239 240 /** updates the roadmap control to show the given path, as far as possible 241 (modulo conflicts with other paths) 242 */ 243 SVT_DLLPRIVATE void implUpdateRoadmap( ); 244 245 private: 246 SVT_DLLPRIVATE void impl_construct(); 247 }; 248 249 //........................................................................ 250 } // namespace svt 251 //........................................................................ 252 253 #endif // OOO_SVTOOLS_INC_ROADMAPWIZARD_HXX 254