DialogResult

While many dialog boxes have the ControlBox, MaximizeBox, MinimizeBox, and ShowInTaskBar properties set to false, the previous example left ControlBox set to the default value of true. The Control box allows the user to close the dialog by clicking on the X in the upper-righthand corner. If the ControlBox is suppressed in a modal dialog box that has no other controls that close the form, then there is no obvious way for the user to close the dialog or end the application, short of killing the application in Task Manager. (The user can press Alt+F4 to close any form or dialog box, or press Escape to close a modal dialog. The developer can always stop debugging.)

Dialog boxes typically have one or more buttons for accepting the user's interaction and/or terminating itself. These buttons will often be assigned the purpose of causing the dialog box to send a standard message, such as OK, Cancel, Yes, or No. At other times, there may be a custom Text property on the button, such as Update Database. In any case, the Click event for the button can be handled, code can be executed, and a result can be sent to the parent form.

A property of every modal form or dialog called DialogResult allows you to set or retrieve a return value when it is closed. The property can be set programmatically at runtime. The valid values of the DialogResult property are members of the DialogResult enumeration, detailed in Table 6-4. The value is set programmatically, typically by a button control on the form. This will also have the effect of closing the modal form, unless it is set to None, in which case the form will continue to run.

To demonstrate terminating a dialog box and passing the return value to the parent form, add some controls and code to the example shown previously. Add a Label control named lblReturn to the parent form. Set its Text property to blank. Go to the code editing window for the parent form and add the highlighted line of code in Example 6-3 (C#) or Example 6-4 (VB.NET) to the event handlers shown previously in Example 6-1 and Example 6-2, respectively.

Example 6-3. Returning DialogResult in C#

private void btnCreate_Click(object sender, System.EventArgs e) { Form dlg = new dlgTest( ); dlg.Text = "Dialog Test"; dlg.FormBorderStyle=FormBorderStyle.FixedDialog; dlg.BackColor = System.Drawing.Color.Azure; dlg.ControlBox = true; dlg.MaximizeBox = false; dlg.MinimizeBox = false; dlg.ShowInTaskbar = false; dlg.Icon = new Icon("info.ico"); dlg.Size = new Size(100,50); dlg.StartPosition = FormStartPosition.CenterScreen; dlg.ShowDialog( ); // Show the return value lblReturn.Text = dlg.DialogResult.ToString( ); }

Example 6-4. Returning DialogResult in VB.NET

Private Sub btnCreate_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles btnCreate.Click dim dlg as New dlgTest dlg.Text = "Dialog Test" dlg.FormBorderStyle=FormBorderStyle.FixedDialog dlg.BackColor = System.Drawing.Color.Azure dlg.ControlBox = true dlg.MaximizeBox = false dlg.MinimizeBox = false dlg.ShowInTaskbar = false dlg.Icon = new Icon("info.ico") dlg.Size = new Size(100,50) dlg.StartPosition = FormStartPosition.CenterScreen dlg.ShowDialog( ) ' Show the return value lblReturn.Text = dlg.DialogResult.ToString( ) End Sub

As you have seen before, the ShowDialog method displays the dialog box modally. When the dialog box is terminated, it is no longer visible on the screen, but the form object dlg still exists. This allows you to retrieve the DialogResult property from the dialog box.

Move to the design window for the dialog box. Add two buttons, named btnOK and btnCancel. Set their Text properties to Do It! and Cancel, respectively.

Double-click on the Do It! button. This will bring the cursor to a code skeleton for the Button Click event handler. Enter the appropriate line of code:

DialogResult = DialogResult.OK;

DialogResult = DialogResult.OK

Double-click on the Cancel button and add the appropriate line:

DialogResult = DialogResult.Cancel;

DialogResult = DialogResult.Cancel

When this project is now run, you will see something similar to Figure 6-4.

Figure 6-4. Dialog box with buttons

Clicking on the Do It! button will yield the result shown in Figure 6-5.

Figure 6-5. Dialog box return value

Clicking on the Cancel button will display Cancel on the parent form. Clicking on the Close button (X) in the upper-right corner of the dialog box, or selecting Close from the system menu exposed by clicking on the icon in the titlebar, or pressing Alt+F4 will return DialogResult.Cancel.

You can combine the call to the ShowDialog method with a test of the DialogResult property. For example, you can combine a call to ShowDialog with a switch block in C#:

switch (dlg.ShowDialog( )) { case DialogResult.Abort: lblReturn.Text = "Abort, Abort"; break; case DialogResult.Cancel: lblReturn.Text = "You have cancelled."; break; case DialogResult.OK: lblReturn.Text = "I'm OK, You're OK"; break; default: lblReturn.Text = "Whatever..."; break; }

or a select case block in VB.NET:

select case dlg.ShowDialog( ) case DialogResult.Abort lblReturn.Text = "Abort, Abort" case DialogResult.Cancel lblReturn.Text = "You have cancelled." case DialogResult.OK lblReturn.Text = "I'm OK, You're OK" case else lblReturn.Text = "Whatever..." end select