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