unoawt: added missing documentation of the new Wizard API

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
 {