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 __com_sun_star_ui_dialogs_XWizard_idl__ 25#define __com_sun_star_ui_dialogs_XWizard_idl__ 26 27#include <com/sun/star/ui/dialogs/XExecutableDialog.idl> 28#include <com/sun/star/util/InvalidStateException.idl> 29#include <com/sun/star/container/NoSuchElementException.idl> 30#include <com/sun/star/awt/XWindow.idl> 31 32//================================================================================================================== 33module com { module sun { module star { module ui { module dialogs { 34 35//================================================================================================================== 36 37published interface XWizardPage; 38 39/** is the main interface implemented by the <type>Wizard</type> services. 40 41 <p>A wizard is a dialog which guides the user through a number of tasks (usually input of data), which the user can 42 accomplish either sequentially or out-of-order. For this, a wizard is comprised of a number of tab pages, 43 each page representing a single <em>step</em>.</p> 44 45 <p>Sequential navigation in a wizard is done via a <em>Next</em> and a <em>Back</em> button. Non-sequential navigation 46 is done via a roadmap, which is displayed on the left hand side of the wizard dialog, lists all available 47 steps, and allows jumping to a certain step (where the creator of the wizard can restrict the available steps 48 depending on the current situation in the wizard, see below).</p> 49 50 <p>A sequence of steps in a wizard dialog is called a <em>path</em>. A given wizard can support one or multiple paths, 51 which are declared at the time of construction of the wizard.</p> 52 53 <p>In the simplest case, where the wizard supports only one path, all available steps are displayed in the roadmap, 54 and the user can simply travel through them as desired.</p> 55 56 <p>If the wizard is more complex, and supports multiple paths, things become more complicated. In a given situation 57 of the wizard, where the user is at step <em>k</em> of the current path, the <em>potential</em> or <em>conflicting</em> 58 paths are those whose first <em>k</em> steps are the same as in the current path. Obviously, there's at least one 59 potential path in every situation: the current one. If there is more than one, then the future steps in the dialog 60 are not finally decided. In such a case, the roadmap will display future steps up to the point where the potential 61 paths diverge, and then an item <quot><code>...</code></quot> indicating that the order of steps is undecided.</p> 62 63 <p>An <type>XWizardController</type> can declare a certain path as active path by calling the <member>activatePath</member> 64 method. Usually, this is done depending on user input. For instance, your wizard could have radio buttons on the 65 first page which effectively decide about which path to take in the wizard.</p> 66 67 <p>Single steps in the wizard can be freely enabled and disabled, using the <member>enablePage</member> method. 68 Disabled pages are skipped during sequential traveling, and not selectable in the roadmap.</p> 69 70 <p>The state of the <em>Next</em> button in the dialog will be automatically maintained in most situations, 71 depending on the results of calls to the <member>XWizardController::canAdvance</member> and <member>XWizardPage::canAdvance</member> 72 methods. More sophisticated wizard logic, however, will need manual calls to the <member>enableButton</member> method. 73 Also, the <em>Finish</em> button needs to be maintained by the wizard's controller, too, as it cannot be decided 74 generically in which situations it should be enabled or disabled.</p> 75 76 @see XWizardController 77 @see XWizardPage 78 79 @since OpenOffice 3.3 80 */ 81published interface XWizard 82{ 83 interface XExecutableDialog; 84 85 /** is the help URL of the wizard's main window. 86 */ 87 [attribute] string HelpURL; 88 89 [attribute, readonly] ::com::sun::star::awt::XWindow 90 DialogWindow; 91 92 /** provides access to the current page of the wizard 93 */ 94 XWizardPage 95 getCurrentPage(); 96 97 /** enables or disables a certain button in the wizard 98 99 <p>Normally, you will want to use this method for the <em>Finish</em> button only: The <em>Next</em> 100 and <em>Back</em> buttons are usually maintained automatically, the <em>Help</em> and <em>Cancel</em> 101 buttons are unlikely to ever being disabled.</p> 102 103 @param WizardButton 104 denotes the button to enable or disable, as one of the <type>WizardButton</type> constants. Must not be 105 <member>WizardButton::NONE</member>. 106 @param Enable 107 specifies whether the button should be enabled (<TRUE/>) or disabled (<FALSE/>) 108 */ 109 void enableButton( [in] short WizardButton, [in] boolean Enable ); 110 111 /** sets a button in the wizard as default button 112 113 <p>In general, the default button in a wizard is the one which is activated when the user presses 114 the <em>return</em> key while the focus is in a control which does not handle this key itself (such as 115 ordinary input controls).</p> 116 117 <p>You can use this method, for instance, to make the <em>Next</em> button the default button on all pages 118 except the last one, where <em>Finish</em> should be defaulted.</p> 119 */ 120 void setDefaultButton( [in] short WizardButton ); 121 122 /** travels to the next page, if possible 123 124 <p>Calling this method is equivalent to the user pressing the <em>Next</em> button in the wizard. Consequently, 125 the method will fail if in the current state of the wizard, it is not allowed to advance to a next page.</p> 126 */ 127 boolean travelNext(); 128 129 /** travels to the next page, if possible 130 131 <p>Calling this method is equivalent to the user pressing the <em>Back</em> button in the wizard.</p> 132 */ 133 boolean travelPrevious(); 134 135 /** enables or disables the given page 136 137 <p>You can use this method when not all pages of your wizard are necessarily needed in all cases. For instance, 138 assume that your first wizard page contains a check box, which the user can check to enter additional data. 139 If you place this data on the second page, then you will want to enable this second page if and only if the 140 checkbox is checked.</p> 141 142 <p>If a page is disabled, it can reached neither by clicking the respective item in the wizard's roadmap, 143 nor by sequential traveling. Still, the page's item is displayed in the roadmap, though disabled.</p> 144 145 @throws ::com::sun::star::container::NoSuchElementException 146 if there is no page with the given ID 147 @throws ::com::sun::star::util::InvalidStateException 148 if the page shall be disabled, but is active currently. 149 */ 150 void enablePage( [in] short PageID, [in] boolean Enable ) 151 raises ( ::com::sun::star::container::NoSuchElementException 152 , ::com::sun::star::util::InvalidStateException ); 153 154 /** updates the wizard elements which are related to traveling. 155 156 <p>For instance, the <em>Next</em> button is disabled if the current page's <member>XWizardPage::canAdvance</member> 157 method returns <FALSE/>.</p> 158 159 <p>You usually call this method from within a wizard page whose state changed in a way that it affects the 160 user's ability to reach other pages.</p> 161 */ 162 void updateTravelUI(); 163 164 /** advances to the given page, if possible. 165 166 <p>Calling this method is equivalent to the user repeatedly pressing the <em>Next</em> button, until the 167 given page is reached. Consequently, the method will fail if one of the intermediate pages does not allow 168 advancing to the next page.</p> 169 */ 170 boolean advanceTo( [in] short PageId ); 171 172 /** goes back to the given page, if possible. 173 174 <p>Calling this method is equivalent to the user repeatedly pressing the <em>Back</em> button, until the 175 given page is reached.</p> 176 */ 177 boolean goBackTo( [in] short PageId ); 178 179 /** activates a path 180 181 <p>If the wizard has been created with multiple paths of control flow, then this method allows switching to 182 another path.</p> 183 184 <p>You can only activate a path which shares the first <code>k</code> pages with the path 185 which is previously active (if any), where <code>k</code> is the index of the current page within the current 186 path.</p> 187 188 <p><strong>Example</strong>: Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code> (with 189 the numbers denoting page IDs). This means that after page <code>1</code>, you either continue with page 190 <code>2</code> or state <code>4</code>,and after this, you finish in state <code>5</code>.<br/> 191 Now if the first path is active, and your current state is <code>1</code>, then you can easily switch to the 192 second path, since both paths start with <code>(0,1)</code>.<br/> 193 However, if your current state is <code>2</code>, then you can not switch to the second path anymore.</p> 194 195 @param PathIndex 196 the index of the path, as used in the <member>Wizard::createMultiplePathsWizard</member> constructor. 197 @param Final 198 <p>If <TRUE/>, the path will be completely activated, even if it is a conflicting path (i.e. there is another 199 path which shares the first <code>k</code> states with the to-be-activated path.)</p> 200 201 <p>If <FALSE/>, then the new path is checked for conflicts with other paths. If such conflicts exists, the path 202 is not completely activated, but only up to the point where it does <em>not</em> conflict.</p> 203 204 <p>In this latter case, you need another activatePath method (usually triggered by the user doing some decisions 205 and entering some data on the reachable pages) before the wizard can actually be finished.</p> 206 207 <p>With the paths in the example above, if you activate the second path, then only steps <code>0</code> and 208 <code>1</code> are activated, since they are common to both paths. Steps <code>2</code>, <code>4</code>, 209 and <code>5</code> are not reachable, yet.</p> 210 211 @throws ::com::sun::star::container::NoSuchElementException 212 if there is no path with the given index 213 @throws ::com::sun::star::util::InvalidStateException 214 if the path cannot be activated in the current state of the wizard. 215 */ 216 void activatePath( [in] short PathIndex, [in] boolean Final ) 217 raises ( ::com::sun::star::container::NoSuchElementException 218 , ::com::sun::star::util::InvalidStateException ); 219}; 220 221//================================================================================================================== 222 223}; }; }; }; }; 224 225//================================================================================================================== 226 227#endif 228