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