offapi/com/sun/star/ui/dialogs/XWizard.idl

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