Add Parameters

In a typical scenario a dialog box will return one or more values back to the calling window. The Dialog Window Template will result in a dialog class that has no parameters. This section describes the design pattern of adding parameters to the dialog.

Contents

• Add Parameters to the Dialog
• Add Reference Parameters to the Dialog

Add Parameters to the Dialog

When the calling window is not concerned with the actual result of the dialog, any parameters to the dialog can be passed by value. This section describes this design pattern.

1. Change the constructor for the dialog class

   Add the parameter/parameters that you need to the dialog implementation.

   /// <summary>
   /// Default Constructor.
   /// </summary>
   public dlgExchange(SalNumber amount)
   {
       this.amount = amount;
   
       // Assign global reference.
       App.dlgExchange = this;
       // This call is required by the Windows Form Designer.
       InitializeComponent();
   }

   Figure 1: Dialog constructor which takes a parameter

2. Update the static ModalDialog method

   Each dialog class has a static method ModalDialog that can be called to create the dialog. This method needs to be updated with the same parameters.

   /// <summary>
   /// Shows the modal dialog.
   /// </summary>
   /// <param name="owner"></param>
   /// <returns></returns>
   public static SalNumber ModalDialog(Control owner, SalNumber amount)
   {
       dlgExchange dlg = new dlgExchange(amount);
       SalNumber ret = dlg.ShowDialog(owner);
       return ret;
   }

   Figure 2: Parameter amount added to the ModalDialog method

Add Reference Parameters to the Dialog

For parameters where a value update is of interest for the calling window we use reference parameters in combination with the normal dialog return value. In this case the recommended implementation shall be added to the ModalDialog method. Note here that when we add a ref variable to ModalDialog, the corresponding parameter that you add to the constructor is not set as ref. This is because the ModalDialog implementation is what a developer normally would implement locally when calling the dialog. Calling the constructor with reference variables would not work as the constructor method has gone out of scope before the dialog is closed.

/// <summary>
/// Shows the modal dialog.
/// </summary>
/// <param name="owner"></param>
/// <param name="amount"</param>
/// <param name="campaignCode"</param>
/// <returns></returns>

public static SalNumber ModalDialog(Control owner, SalNumber amount, ref SalString campaignCode)
{
    dlgExchange dlg = new dlgExchange(amount, campaignCode);
    SalNumber ret = dlg.ShowDialog(owner);

    // Verify the dialog result to see if the user ended with OK or Cancel
    if (ret == Sys.IDOK)
    {
        campaignCode = dlg.campaignCode;
    }
    return ret;
}

Figure 3: Example of adding ref to ModalDialog method parameter in order to pass results back to the calling window.

Note: The Application Forms framework runs on the PPJ framework and for a dialog box this means that there are some aspects to consider that may fall outside a standard MS project. The return value for a cDialogBox class is default SalNumber, i.e. we do not use the normal DialogResult constants, but rather Sys.IDOK and Sys.IDCANCEL.