Dialog Boxes | Application Development Using C# and .NET

for RuBoard

Dialog boxes provide a more elaborate way for a user to interact with a Windows application. A dialog box can provide a number of controls to facilitate data input. The code in the previous section illustrated use of a simple message box dialog that allowed the user to answer a yes or no question. This kind of dialog can be created using the MessageBox class. You can implement more general dialog boxes by creating forms for them.

We will illustrate a number of dialogs through a graphical user interface to our Acme Travel Agency case study. As usual, the case study code is in the CaseStudy folder for this chapter. Let's begin by examining a simple dialog that is used for adding a new hotel to our list of hotels. Build and run the case study. In the main form click the "Add..." button. ^[4] The "New Hotel" dialog is brought up, as illustrated in Figure 6-21.

^[4] The three dots are a Windows UI style that indicates the program will not carry out the action immediately but will prompt the user for additional input, typically through a dialog box.

Figure 6-21. Dialog box for adding a new hotel.

graphics/06fig21.gif

The user can now enter data. Clicking the OK button will cause the information to be accepted. Clicking the Cancel button will cause the new data to be ignored. This dialog box (like the message box in the previous section) is a modal dialog, which means that the user cannot work elsewhere in the application until the dialog is closed. If you try do something else on the main form while the "New Hotel" dialog is open for example, click another buttonyou will hear a beep. The other kind of dialog is modeless , which will allow the user to work elsewhere in the application while the dialog is open.

Dialog boxes normally have special characteristics as forms. For example, they typically do not have a system menu, they have no minimize or maximize buttons , and they have a border that does not permit them to be resized. You can examine these features with the "New Hotel" dialog.

Continuing the demonstration, enter some data for a new hotel and click OK. You will now be brought back to the main form, and your new hotel will be shown in the list of hotels, as illustrated in Figure 6-22. The main form also illustrates some additional GUI features, such as a list box for displaying a list of hotels and a multiline text box that can display text that is too long to fit on one line.

Figure 6-22. Main form for hotel administration.

graphics/06fig22.gif

.NET Dialog Documentation

Dialogs are explained clearly in the Documentation in the .NET Framework. Look in "Dialog Boxes in Windows Forms" under "Introduction to Windows Forms." It is noteworthy that the principles of dialog boxes are the same in all .NET languages. This is in sharp contrast to the days before .NET, where, for example, dialogs in Visual Basic and in Microsoft Foundation Classes were totally different. Figure 6-23 shows the entry point to this documentation.

Figure 6-23. Documentation on dialog boxes using the .NET Framework.

graphics/06fig23.gif

Dialog Box Demonstration

We will demonstrate the implementation details of a dialog box by creating a dialog to change hotel information in a simplified version of our case study. Do your work in the folder Demo\HotelAdmin . The starter code is backed up in the folder HotelAdmin\Step1 in the main folder for this chapter. The completed program is in HotelAdmin\Step3 . You may run either the case study or the Step 3 solution to see what the completed dialog should look like. In the main form select a hotel by clicking in the list box of hotels. Then click on the "Change..." button. This brings up the "Change Hotel Information" dialog, as illustrated in Figure 6-24. Notice that the City and Hotel Name are grayed out. These items are read-only and cannot be changed. The user can enter new information for the Rooms and Rate.

Figure 6-24. Dialog for changing hotel information.

graphics/06fig24.gif

Creating a Modal Dialog

The first part of our demonstration illustrates how to create a modal dialog box. We show how to set properties appropriately for the dialog and how to return a dialog result through use of OK and Cancel buttons.

Build and run the starter application. The "Add..." and "Delete" buttons work, but there is only a stub for "Change...", which brings up an empty form. This form is ordinary, with system menu, minimize and maximize buttons, resizability, and so on.
Open up ChangeHotelDialog.cs in Design mode. In the Properties window, change the FormBorderStyle property to FixedDialog .
Set the ControlBox , MinimizeBox , and MaximizeBox properties to False . If you like, you may build and run the application at this point. The dialog now is not resizable, and there is no system menu and no "X" in top right to close the window. ^[5]

^[5] You may use Alt+F4 to close the window.
The next job is to enter labels and text boxes for the hotel information, plus OK and Cancel buttons. You may practice using the Toolbox to add these controls. Alternatively, you may copy and paste from NewHotelDialog.cs (open both files in Design mode).

If you used copy and paste, the controls will have proper Name and Text properties. Otherwise, assign values as shown in Table 6-2.

Table 6-2. Property Values for Textboxes and Buttons for ChangeHotelDialog.cs

Name	Text
`txtCity`	(blank)
`txtHotelName`	(blank)
`txtNumberRooms`	(blank)
`txtRate`	(blank)
`cmdOK`	OK
`cmdCancel`	Cancel

Change the ReadOnly property of txtCity and txtHotelName to true .
Resize the form to better fit the controls we have added.
Set the DialogResult property of the OK button to OK. Similarly set the property of the Cancel button to Cancel. Save ChangeHotelDialog.cs .
In MainAdminForm.cs , add temporary code to the cmdChange_Click handler to display "OK" or "Cancel" in the Messages text box, depending on whether the dialog was closed by clicking OK or Cancel. Notice that a dialog is brought up by the method ShowDialog in place of Show , which is used for ordinary forms. ShowDialog returns a result as an enum of type DialogResult .
```
 private void cmdChange_Click(object sender,                               System.EventArgs e)  {     ChangeHotelDialog dlg = new ChangeHotelDialog();  DialogResult status = dlg.ShowDialog();   if (status == DialogResult.OK)   {   txtMessages.Text = "OK";   }   else   {   txtMessages.Text = "Cancel";   }  } 
```
Build and test. You should now be able to bring up the dialog from the menu, and either the OK or Cancel button will close the dialog, and a corresponding message will be displayed. You can verify that the dialog is modal by trying to click elsewhere in the application. The program is now at Step 2.

Passing Information Between Parent Form and a Dialog

The second part of our demonstration shows how to pass information to a dialog and how to retrieve information from a dialog. The .NET Framework classes do not provide a built-in mechanism for this purpose, but there is a design pattern you can follow. You create a property in the dialog class for each piece of information you wish to pass between the parent form and the dialog.

In our example we implement write-only ^[6] properties for City and HotelName and read-write properties for Rate and NumberRooms .

^[6] The properties are write-only from the perspective of the dialog class, because we pass information a dialog instance. The corresponding controls are read-only, because the user is not allowed to enter new information.

Add code to ChangeHotelDialog.cs to implement these properties.

 public string City  {     set     {        txtCity.Text = value;     }  }  public string HotelName  {     set     {        txtHotelName.Text = value;     }  }  public int NumberRooms  {     get     {        return Convert.ToInt32(txtNumberRooms.Text);     }     set     {     }  }  public decimal Rate  {     get     {        return Convert.ToDecimal(txtRate.Text);     }     set     {        txtRate.Text = value.ToString();     }  }

Now add code to the main form MainAdminForm.cs to set these properties prior to bringing up the dialog and to use the properties if the dialog box closes via an OK. Comment out or delete your previous test code that displays "OK" or "Cancel" in the Messages box.

 private void cmdChange_Click(object sender,                               System.EventArgs e)  {     ChangeHotelDialog dlg = new ChangeHotelDialog();     if (currHotel.HotelName != "")     {  dlg.City = currHotel.City;   dlg.HotelName = currHotel.HotelName;   dlg.NumberRooms = currHotel.NumberRooms;   dlg.Rate = currHotel.Rate;  }     else     {        MessageBox.Show("Please select a hotel",           "Hotel Broker Administration",           MessageBoxButtons.OK,           MessageBoxIcon.Exclamation           );        return;     }     DialogResult status = dlg.ShowDialog();     if (status == DialogResult.OK)     {        string comment = hotelBroker.ChangeRooms(           currHotel.City,           currHotel.HotelName,  dlg.NumberRooms,   dlg.Rate  );        if (comment == "OK")        {           ShowHotelList(hotelBroker.GetHotels());           txtMessages.Text = "Hotel " + currHotel.HotelName              + " has been changed";        }        else           txtMessages.Text = comment;     }  }

The structure currHotel holds the fields of the hotel that is currently selected in the list box. In the next section we will see how to extract information from a list box and how to populate a list box.

Build and test. Your dialog should now be fully operational. Your project should now correspond to HotelAdmin\Step3 .

for RuBoard