211 lines
11 KiB
Text
211 lines
11 KiB
Text
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
|
|
/*
|
|
* This file is part of the LibreOffice project.
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
*
|
|
* This file incorporates work covered by the following license notice:
|
|
*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed
|
|
* with this work for additional information regarding copyright
|
|
* ownership. The ASF licenses this file to you under the Apache
|
|
* License, Version 2.0 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
|
|
*/
|
|
|
|
module com { module sun { module star { module ui { module dialogs {
|
|
|
|
|
|
interface XWizardPage;
|
|
|
|
/** is the main interface implemented by the Wizard services.
|
|
|
|
<p>A wizard is a dialog which guides the user through a number of tasks (usually input of data), which the user can
|
|
accomplish either sequentially or out-of-order. For this, a wizard is comprised of a number of tab pages,
|
|
each page representing a single <em>step</em>.</p>
|
|
|
|
<p>Sequential navigation in a wizard is done via a <em>Next</em> and a <em>Back</em> button. Non-sequential navigation
|
|
is done via a roadmap, which is displayed on the left hand side of the wizard dialog, lists all available
|
|
steps, and allows jumping to a certain step (where the creator of the wizard can restrict the available steps
|
|
depending on the current situation in the wizard, see below).</p>
|
|
|
|
<p>A sequence of steps in a wizard dialog is called a <em>path</em>. A given wizard can support one or multiple paths,
|
|
which are declared at the time of construction of the wizard.</p>
|
|
|
|
<p>In the simplest case, where the wizard supports only one path, all available steps are displayed in the roadmap,
|
|
and the user can simply travel through them as desired.</p>
|
|
|
|
<p>If the wizard is more complex, and supports multiple paths, things become more complicated. In a given situation
|
|
of the wizard, where the user is at step <em>k</em> of the current path, the <em>potential</em> or <em>conflicting</em>
|
|
paths are those whose first <em>k</em> steps are the same as in the current path. Obviously, there's at least one
|
|
potential path in every situation: the current one. If there is more than one, then the future steps in the dialog
|
|
are not finally decided. In such a case, the roadmap will display future steps up to the point where the potential
|
|
paths diverge, and then an item <em><code>...</code></em> indicating that the order of steps is undecided.</p>
|
|
|
|
<p>An XWizardController can declare a certain path as active path by calling the activatePath()
|
|
method. Usually, this is done depending on user input. For instance, your wizard could have radio buttons on the
|
|
first page which effectively decide about which path to take in the wizard.</p>
|
|
|
|
<p>Single steps in the wizard can be freely enabled and disabled, using the enablePage() method.
|
|
Disabled pages are skipped during sequential traveling, and not selectable in the roadmap.</p>
|
|
|
|
<p>The state of the <em>Next</em> button in the dialog will be automatically maintained in most situations,
|
|
depending on the results of calls to the XWizardController::canAdvance() and XWizardPage::canAdvance()
|
|
methods. More sophisticated wizard logic, however, will need manual calls to the enableButton() method.
|
|
Also, the <em>Finish</em> button needs to be maintained by the wizard's controller, too, as it cannot be decided
|
|
generically in which situations it should be enabled or disabled.</p>
|
|
|
|
@see XWizardController
|
|
@see XWizardPage
|
|
|
|
@since OOo 3.3
|
|
*/
|
|
interface XWizard
|
|
{
|
|
interface XExecutableDialog;
|
|
|
|
/** is the help URL of the wizard's main window.
|
|
*/
|
|
[attribute] string HelpURL;
|
|
|
|
[attribute, readonly] ::com::sun::star::awt::XWindow
|
|
DialogWindow;
|
|
|
|
/** provides access to the current page of the wizard
|
|
*/
|
|
XWizardPage
|
|
getCurrentPage();
|
|
|
|
/** enables or disables a certain button in the wizard
|
|
|
|
<p>Normally, you will want to use this method for the <em>Finish</em> button only: The <em>Next</em>
|
|
and <em>Back</em> buttons are usually maintained automatically, the <em>Help</em> and <em>Cancel</em>
|
|
buttons are unlikely to ever being disabled.</p>
|
|
|
|
@param WizardButton
|
|
denotes the button to enable or disable, as one of the WizardButton constants. Must not be
|
|
WizardButton::NONE.
|
|
@param Enable
|
|
specifies whether the button should be enabled (`TRUE`) or disabled (`FALSE`)
|
|
*/
|
|
void enableButton( [in] short WizardButton, [in] boolean Enable );
|
|
|
|
/** sets a button in the wizard as default button
|
|
|
|
<p>In general, the default button in a wizard is the one which is activated when the user presses
|
|
the <em>return</em> key while the focus is in a control which does not handle this key itself (such as
|
|
ordinary input controls).</p>
|
|
|
|
<p>You can use this method, for instance, to make the <em>Next</em> button the default button on all pages
|
|
except the last one, where <em>Finish</em> should be defaulted.</p>
|
|
*/
|
|
void setDefaultButton( [in] short WizardButton );
|
|
|
|
/** travels to the next page, if possible
|
|
|
|
<p>Calling this method is equivalent to the user pressing the <em>Next</em> button in the wizard. Consequently,
|
|
the method will fail if in the current state of the wizard, it is not allowed to advance to a next page.</p>
|
|
*/
|
|
boolean travelNext();
|
|
|
|
/** travels to the next page, if possible
|
|
|
|
<p>Calling this method is equivalent to the user pressing the <em>Back</em> button in the wizard.</p>
|
|
*/
|
|
boolean travelPrevious();
|
|
|
|
/** enables or disables the given page
|
|
|
|
<p>You can use this method when not all pages of your wizard are necessarily needed in all cases. For instance,
|
|
assume that your first wizard page contains a check box, which the user can check to enter additional data.
|
|
If you place this data on the second page, then you will want to enable this second page if and only if the
|
|
checkbox is checked.</p>
|
|
|
|
<p>If a page is disabled, it can reached neither by clicking the respective item in the wizard's roadmap,
|
|
nor by sequential traveling. Still, the page's item is displayed in the roadmap, though disabled.</p>
|
|
|
|
@throws ::com::sun::star::container::NoSuchElementException
|
|
if there is no page with the given ID
|
|
@throws ::com::sun::star::util::InvalidStateException
|
|
if the page shall be disabled, but is active currently.
|
|
*/
|
|
void enablePage( [in] short PageID, [in] boolean Enable )
|
|
raises ( ::com::sun::star::container::NoSuchElementException
|
|
, ::com::sun::star::util::InvalidStateException );
|
|
|
|
/** updates the wizard elements which are related to traveling.
|
|
|
|
<p>For instance, the <em>Next</em> button is disabled if the current page's XWizardPage::canAdvance()
|
|
method returns `FALSE`.</p>
|
|
|
|
<p>You usually call this method from within a wizard page whose state changed in a way that it affects the
|
|
user's ability to reach other pages.</p>
|
|
*/
|
|
void updateTravelUI();
|
|
|
|
/** advances to the given page, if possible.
|
|
|
|
<p>Calling this method is equivalent to the user repeatedly pressing the <em>Next</em> button, until the
|
|
given page is reached. Consequently, the method will fail if one of the intermediate pages does not allow
|
|
advancing to the next page.</p>
|
|
*/
|
|
boolean advanceTo( [in] short PageId );
|
|
|
|
/** goes back to the given page, if possible.
|
|
|
|
<p>Calling this method is equivalent to the user repeatedly pressing the <em>Back</em> button, until the
|
|
given page is reached.</p>
|
|
*/
|
|
boolean goBackTo( [in] short PageId );
|
|
|
|
/** activates a path
|
|
|
|
<p>If the wizard has been created with multiple paths of control flow, then this method allows switching to
|
|
another path.</p>
|
|
|
|
<p>You can only activate a path which shares the first <code>k</code> pages with the path
|
|
which is previously active (if any), where <code>k</code> is the index of the current page within the current
|
|
path.</p>
|
|
|
|
<p><strong>Example</strong>: Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code> (with
|
|
the numbers denoting page IDs). This means that after page <code>1</code>, you either continue with page
|
|
<code>2</code> or state <code>4</code>,and after this, you finish in state <code>5</code>.<br/>
|
|
Now if the first path is active, and your current state is <code>1</code>, then you can easily switch to the
|
|
second path, since both paths start with <code>(0,1)</code>.<br/>
|
|
However, if your current state is <code>2</code>, then you can not switch to the second path anymore.</p>
|
|
|
|
@param PathIndex
|
|
the index of the path, as used in the Wizard::createMultiplePathsWizard() constructor.
|
|
@param Final
|
|
<p>If `TRUE`, the path will be completely activated, even if it is a conflicting path (i.e. there is another
|
|
path which shares the first <code>k</code> states with the to-be-activated path.)</p>
|
|
|
|
<p>If `FALSE`, then the new path is checked for conflicts with other paths. If such conflicts exists, the path
|
|
is not completely activated, but only up to the point where it does <em>not</em> conflict.</p>
|
|
|
|
<p>In this latter case, you need another activatePath method (usually triggered by the user doing some decisions
|
|
and entering some data on the reachable pages) before the wizard can actually be finished.</p>
|
|
|
|
<p>With the paths in the example above, if you activate the second path, then only steps <code>0</code> and
|
|
<code>1</code> are activated, since they are common to both paths. Steps <code>2</code>, <code>4</code>,
|
|
and <code>5</code> are not reachable, yet.</p>
|
|
|
|
@throws ::com::sun::star::container::NoSuchElementException
|
|
if there is no path with the given index
|
|
@throws ::com::sun::star::util::InvalidStateException
|
|
if the path cannot be activated in the current state of the wizard.
|
|
*/
|
|
void activatePath( [in] short PathIndex, [in] boolean Final )
|
|
raises ( ::com::sun::star::container::NoSuchElementException
|
|
, ::com::sun::star::util::InvalidStateException );
|
|
};
|
|
|
|
|
|
}; }; }; }; };
|
|
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|