This page describes some ways to add specific functionality to a wizard.
To customize a wizard in the required manner, an instance of the wizard dialog
can override methods and call public functions in its base class. In the API documentation
of cWizardDialogBox
you can read more about all the methods used to
customize a wizard.
A typical customization used in many wizards is to check whether the
Next operation should be enabled, and to execute
some functionality when leaving a wizard step by clicking the
Next button. To do these customizations the wizard
should override the virtual method vrtWizardNext
.
public override SalBoolean vrtWizardNext(SalNumber nWhat, SalString sStep) { return this.WizardNext(nWhat, sStep); }
Figure 1. Override method vrtWizardNext
from
cWizardDialog
. This method should call a specific WizardNext
implemented in your wizard.
A good pattern to follow is to implement the customization logic in a new
WizardNext
method, rather than in the overriden method vrtWizardNext
.
This is also how the code in a ported wizard is constructed. The method takes the
parameters nWhat
and sStep
. The nWhat
parameter
takes the value METHOD_Inquire
or METHOD_Execute
. When
nWhat
equals METHOD_Inquire
the wizard should return true
if the Next operation should be available and false
otherwise.
public new SalBoolean WizardNext(SalNumber nWhat, SalString sStep) { #region Local Variables SalBoolean sAbort = false; #endregion #region Actions using (new SalContext(this)) { if (nWhat == Ifs.Fnd.ApplicationForms.Const.METHOD_Inquire) { if (sStep == "StepOne") { return m_nCurrentPage + 1 < m_nTotalPages; } else if (sStep == "StepTwo") { if (dfsSourceCompanyId.Text == Ifs.Fnd.ApplicationForms.Const.strNULL) { return false; } } else { return m_nCurrentPage + 1 < m_nTotalPages; } } } #endregion }
Figure 2. Sample of an implementation of the WizardNext
method. The parameter nWhat
is validated. When the value is
METHOD_Inquire
, perform logic and return true to enable the
Next operation or false to disable it. The name
of the next wizard step is available in the sStep
parameter.
In the method WizardNext
, when the nWhat
parameter
equals METHOD_Execute
, you execute logic required before you leave
the current wizard step. The sStep
parameter contains the name of the
step that will be activated after this function returns.
if (nWhat == Ifs.Fnd.ApplicationForms.Const.METHOD_Execute) { if (sStep == "StepTwo") { if (AllFieldsValidate(sStep)) { return true; } } else if (sStep == "StepThree") { PackSelectedLangauges(); if (AllFieldsValidate(sStep)) { return true; } } return false; }
Figure 3. When nWhat
equals METHOD_Execute
the wizard should return true if the Next operation
was successfully performed and false otherwise.
The List button in the wizard is used to show a List of Values dialog. By default the List button is enabled when an editable data item in the wizard with a LOV reference gets the input focus, and the Show List property on the wizard is set to true. Clicking the List button will open up the List of Value dialog for the focused data item.
It is possible to override the default behavior of the
List button by overriding the virtual method
vrtWizardList
. This method is called by the framework. The method takes
the nWhat
in parameter that can have the values Const.METHOD_Inquire
or Const.METHOD_Execute
. When nWhat is Const.METHOD_Inquire
return true if the List button should be available and false otherwise. When nWhat
is Const.METHOD_Execute
the framework opens the List of Value dialog.
When overriding it is possible to make all required changes before and after the
LOV dialog is shown. To show the LOV dialog send the message Const.PM_DataItemLov
to the focused field in the wizard.
To override the framework functionality for the Finish button the vrtWizardFinish
method should be overridden. This method takes two parameters. The first is
nWhat
that can have the values Const.METHOD_Inquire
or
Const.METHOD_Execute
. The second parameter is sStep
which
contains the name of the currently active wizard step. When nWhat
is
Const.METHOD_Inquire
return true if the Finish
button should be available and false otherwise. When nWhat is Const.METHOD_Execute
you add the extra functionality to be executed when the user chooses Finish. A good
pattern to follow is to implement the customization logic in a new WizardFinish
method, rather than in the overridden method vrtWizardFinish
. See
example below.
public override SalBoolean vrtWizardFinish(SalNumber nWhat, SalString sStep) { return this.WizardFinish(nWhat, sStep); }
Figure 4. Override method vrtWizardFinish
and
call a new WizardNext
method implemented in your wizard.
public new SalBoolean WizardFinish(SalNumber nWhat, SalString sStep) { #region Actions using (new SalContext(this)) { if (nWhat == Ifs.Fnd.ApplicationForms.Const.METHOD_Inquire) { return WizardIsLastStep(); } if (nWhat == Ifs.Fnd.ApplicationForms.Const.METHOD_Execute) { if (Sal.IsNull(dfsFileNameFinish)) { Ifs.Fnd.ApplicationForms.Int.AlertBox(Properties.Resources.TEXT_FileNameMissing, Ifs.Fnd.ApplicationForms.Properties.Resources.CAPTION_Error, Ifs.Fnd.ApplicationForms.Const.CRITICAL_Ok); return false; } Sal.WaitCursor(true); if (!(ReadAndWriteFile())) { Ifs.Fnd.ApplicationForms.Int.AlertBox(Properties.Resources.TEXT_MergeWizWriteError, Ifs.Fnd.ApplicationForms.Properties.Resources.CAPTION_Error, Ifs.Fnd.ApplicationForms.Const.CRITICAL_Ok); Vis.FileClose(hSrcHandleWrite); return false; } Sal.WaitCursor(false); return Sal.EndDialog(this, 0); } } return false; #endregion }
Figure 5. In this example the Finish button is enabled if it is the last wizard step. When the Finish button is pressed some logic to read and write a file is executed.
To change the behavior of a wizard there are a lot more methods to override than
are described above. Please see the API documentation of the cWizardDialog
for more details.