diff options
author | Frank Schoenheit [fs] <frank.schoenheit@sun.com> | 2010-05-25 13:00:57 +0200 |
---|---|---|
committer | Frank Schoenheit [fs] <frank.schoenheit@sun.com> | 2010-05-25 13:00:57 +0200 |
commit | 780bcf3625211e970d1b2c3ac610a088fdb02d5e (patch) | |
tree | a05f3c102a9b4bcbccff50ff421c002b81b1e4d7 /offapi/com/sun/star/ui | |
parent | 45a8100e42492335d5423efa2ad512c2ba1dbfca (diff) |
unoawt: added missing documentation of the new Wizard API
Diffstat (limited to 'offapi/com/sun/star/ui')
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/Wizard.idl | 2 | ||||
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/WizardButton.idl | 7 | ||||
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/WizardTravelType.idl | 5 | ||||
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/XWizard.idl | 42 | ||||
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/XWizardController.idl | 28 | ||||
-rw-r--r-- | offapi/com/sun/star/ui/dialogs/XWizardPage.idl | 2 |
6 files changed, 77 insertions, 9 deletions
diff --git a/offapi/com/sun/star/ui/dialogs/Wizard.idl b/offapi/com/sun/star/ui/dialogs/Wizard.idl index 36c0f17dedb5..4e6b13f44ca2 100644 --- a/offapi/com/sun/star/ui/dialogs/Wizard.idl +++ b/offapi/com/sun/star/ui/dialogs/Wizard.idl @@ -38,7 +38,7 @@ interface XWizardController; //================================================================================================================== -/** +/** provides a framework for implementing a wizard dialog. */ service Wizard : XWizard { diff --git a/offapi/com/sun/star/ui/dialogs/WizardButton.idl b/offapi/com/sun/star/ui/dialogs/WizardButton.idl index 3169adeab95c..aeb22910996c 100644 --- a/offapi/com/sun/star/ui/dialogs/WizardButton.idl +++ b/offapi/com/sun/star/ui/dialogs/WizardButton.idl @@ -33,14 +33,19 @@ module com { module sun { module star { module ui { module dialogs { //================================================================================================================== -/** +/** denotes the buttons found in a <type>Wizard</type> */ constants WizardButton { + /// denotes the button used to travel forward through the wizard const short NEXT = 1; + /// denotes the button used to travel backward through the wizard const short PREVIOUS = 2; + /// denotes the button used to finish the wizard const short FINISH = 3; + /// denotes the button used to cancel the wizard const short CANCEL = 4; + /// denotes the button used to request help const short HELP = 5; }; diff --git a/offapi/com/sun/star/ui/dialogs/WizardTravelType.idl b/offapi/com/sun/star/ui/dialogs/WizardTravelType.idl index 9efd822ffe33..271a006346b7 100644 --- a/offapi/com/sun/star/ui/dialogs/WizardTravelType.idl +++ b/offapi/com/sun/star/ui/dialogs/WizardTravelType.idl @@ -33,12 +33,15 @@ module com { module sun { module star { module ui { module dialogs { //================================================================================================================== -/** +/** denotes ways to leave a <type>Wizard</type>'s page */ constants WizardTravelType { + /// indicates the wizard page is left due to forward traveling through the wizard const short FORWARD = 1; + /// indicates the wizard page is left due to backward traveling through the wizard const short BACKWARD = 2; + /// indicates the wizard page is left since the wizard is about to be finished const short FINISH = 3; }; diff --git a/offapi/com/sun/star/ui/dialogs/XWizard.idl b/offapi/com/sun/star/ui/dialogs/XWizard.idl index a3aa93b9cc62..d894c85db1fd 100644 --- a/offapi/com/sun/star/ui/dialogs/XWizard.idl +++ b/offapi/com/sun/star/ui/dialogs/XWizard.idl @@ -38,7 +38,45 @@ module com { module sun { module star { module ui { module dialogs { interface XWizardPage; -/** +/** is the main interface implemented by the <type>Wizard</type> 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 <quot><code>...</code></quot> indicating that the order of steps is undecided.</p> + + <p>An <type>XWizardController</type> can declare a certain path as active path by calling the <member>activatePath</member> + 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 <member>enablePage</member> 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 <member>XWizardController::canAdvance</member> and <member>XWizardPage::canAdvance</member> + methods. More sophisticated wizard logic, however, will need manual calls to the <member>enableButton</member> 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 */ interface XWizard { @@ -111,7 +149,7 @@ interface XWizard /** 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> + <p>For instance, the <em>Next</em> button is disabled if the current page's <member>XWizardPage::canAdvance</member> 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 diff --git a/offapi/com/sun/star/ui/dialogs/XWizardController.idl b/offapi/com/sun/star/ui/dialogs/XWizardController.idl index e38bcb1a5f1f..abcec1ce6ef6 100644 --- a/offapi/com/sun/star/ui/dialogs/XWizardController.idl +++ b/offapi/com/sun/star/ui/dialogs/XWizardController.idl @@ -33,20 +33,36 @@ module com { module sun { module star { module ui { module dialogs { -interface XWizard; - //================================================================================================================== -/** +/** is the interface of a client-provided controller of a custom <type>Wizard</type>. */ interface XWizardController { + /** creates a page + + <p>Wizard pages are created on demand, when the respective page is reached during traveling through the + wizard. Effectively, this means the method is called at most once for each possible page ID.</p> + + @param ParentWindow + the parent window to use for the page window + @param PageId + the ID of the page. + @return + the requested page. + */ XWizardPage createPage( [in] ::com::sun::star::awt::XWindow ParentWindow, [in] short PageId ); + /** provides the title of a page given by ID + + <p>The page titles are displayed in the wizard's roadmap.</p> + */ string getPageTitle( [in] short PageId ); boolean canAdvance(); + /** called when a new page in the wizard is being activated + */ void onActivatePage( [in] short PageId ); /** called when the current page is about to be left @@ -61,8 +77,14 @@ interface XWizardController */ boolean confirmDeactivatePage( [in] short PageId, [in] short Reason ); + /** called when a page in the wizard is being deactivated + */ void onDeactivatePage( [in] short PageId ); + /** called when the wizard is about to be finished. + + <p>This method allows the controller to do any final checks, and ultimatively veto finishing the wizard.</p> + */ boolean confirmFinish(); }; diff --git a/offapi/com/sun/star/ui/dialogs/XWizardPage.idl b/offapi/com/sun/star/ui/dialogs/XWizardPage.idl index 7c49db499214..50f3212e1cf2 100644 --- a/offapi/com/sun/star/ui/dialogs/XWizardPage.idl +++ b/offapi/com/sun/star/ui/dialogs/XWizardPage.idl @@ -35,7 +35,7 @@ module com { module sun { module star { module ui { module dialogs { //================================================================================================================== -/** +/** is a single page of a <type>Wizard</type> */ interface XWizardPage : ::com::sun::star::lang::XComponent { |