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

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