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