diff options
author | Frank Schoenheit [fs] <frank.schoenheit@sun.com> | 2010-05-21 15:03:31 +0200 |
---|---|---|
committer | Frank Schoenheit [fs] <frank.schoenheit@sun.com> | 2010-05-21 15:03:31 +0200 |
commit | 45a8100e42492335d5423efa2ad512c2ba1dbfca (patch) | |
tree | 2348703746bf7d8a6e1ab698fc8c2fdc4b947486 /offapi/com/sun/star/ui | |
parent | d6dd1c27f9ea664978ceb48825b8e8417cc01e61 (diff) |
unoawt: added more functionality to XWizard
Diffstat (limited to 'offapi/com/sun/star/ui')
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/XWizard.idl | 120 |
1 files changed, 115 insertions, 5 deletions
diff --git a/offapi/com/sun/star/ui/dialogs/XWizard.idl b/offapi/com/sun/star/ui/dialogs/XWizard.idl index 0d6a92cbd164..a3aa93b9cc62 100644 --- a/offapi/com/sun/star/ui/dialogs/XWizard.idl +++ b/offapi/com/sun/star/ui/dialogs/XWizard.idl @@ -28,27 +28,87 @@ #define __com_sun_star_ui_dialogs_XWizard_idl__ #include <com/sun/star/ui/dialogs/XExecutableDialog.idl> +#include <com/sun/star/util/InvalidStateException.idl> +#include <com/sun/star/container/NoSuchElementException.idl> //================================================================================================================== - module com { module sun { module star { module ui { module dialogs { -interface XWizardPage; - //================================================================================================================== +interface XWizardPage; + /** */ interface XWizard { interface XExecutableDialog; + /** is the help URL of the wizard's main window. + */ + [attribute] string HelpURL; + + /** 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 <type>WizardButton</type> constants + @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 <code>Next</code> button is disabled if the current page's <member>XWizardPage::canAdvance</member> @@ -59,11 +119,61 @@ interface XWizard */ 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 ); - XWizardPage - getCurrentPage(); + /** 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 <member>Wizard::createMultiplePathsWizard</member> 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 ); }; //================================================================================================================== |