C#

C# Modal & Modeless Dialog Explained

1. Introduction to C# Dialogs

In C#, Windows Form is a User Interface (UI) that picks up input from the application users. An application can show these forms as either Modal Dialog or Modeless Dialog. Note, a Form can call some other Form and it can go deep nesting. In case of a Modal C# Dialog, the caller gets blocked till the user closes the Modal Dialog. Conversely, the Modeless C# Dialog does not block the caller.

2. About the Example

The example has three Windows Forms. They are:

  1. Main Form
  2. About Form
  3. Person Name Form

The ‘Main Form’ is for collecting the user information. Here, we have two input fields. The Name text box is Read-Only. Age text box gets the Age of a person from the user. The about button will display the ‘About Form’ as Modeless Dialog and the ellipsis button ‘…’ will display the ‘Person Name Form’ as Modal C# Dialog. After collecting the user input in the Modal C# Dialog, the ‘Main Form’ reads the information from it to display the content in the Name text field. The below picture explains the navigation:

Form Navigation of This Example

Form Navigation of This Example

3. Dialog Design and Properties

In this section, we will deal with the dialog design one by one. First, we will create our about dialog. The below steps show how to add an about C# Dialog:

  1. First create a Windows Form Application and name the application as ‘DialogsExample’.
  2. Right Click on the Project Name and Select Add->New Item.

    Add New Form for About Dialog

    Add New Form for About Dialog

  3. From the Add New Item dialog, we must select Windows Form from the template list and then name the file as ‘frmAbout.cs’. The below picture shows these steps:
    Add a Windows Form for the About Dialog

    Add a Windows Form for the About Dialog

     

3.1 The About C# Dialog Design

Now, we can design the About Dialog. The completed C# dialog form in design mode is below:

About Form Design

About Form Design

This About Dialog has only one Control in it. The Label Control displays a text for the user. To add a multi-line text to the Label Control at design time, we must click the down arrow button in the Text Property. From the dropped-down editor, we can type multiple lines of text. The ‘Ctrl + Enter’ combination allows one to come out of the editor. Below picture shows editing a multi-line text through this editor:

Adding Multiple lines of Text to a Label Control at Design Time

Adding Multiple lines of Text to a Label Control at Design Time

3.2 Main Dialog Design

When we created Windows Form Application, by default C# created a Form for us. We will consider it as our Main C# Dialog. This will act as an Application startup Form and it means, when the user launches the application, the Main Dialog pops up. In the Main Dialog we have two Label Controls, two Text Box Controls and two Button Controls. The below picture shows the layout of the Dialog:

The Main Dialog

The Main Dialog

Control marked as 1 is a Button Control. We set its ‘ Text Property’ as an ellipsis ‘…’ and it is a windows standard which informs the user that clicking a button will bring one more dialog to get additional information. When this Button is clicked, we will invoke the Person Name form as Modal dialog. Note, we have not designed this C# Dialog till now.

The Control marked as 2 is also a Button Control. The click in this Button will display the About Form as Modeless Dialog.

Control marked as 3 is a Text Box Control and we named it as ‘txtfmtName’. We set ‘ ReadOnly Property’ of this Control as true. The ‘ ReadOnly Property’ decides a user can enter text in it or Not. When we set this property as true, C# will change the Control’s background color to gray. So we set it back to white after setting the ReadOnly property.

The last edit Control is marked as 4 which will collect age from the user. We accept all other default Properties for this Control.

3.3 Person Name Dialog Design

We will display the Person Name Form as a Modal Dialog from the Main Form. The Modal Dialog stops all user navigation into the Main Form. This means, focus is set only to the Person Name C# Dialog and Main Dialog gets the focus after user closes this Modal dialog. The below picture shows the design of the Person Name Form:

Design of Person Name Form

Design of Person Name Form

  1. This is a Text Control and we named it as ‘txtTitle’.
  2. It is also a Text Control and we named it as ‘txtFname’.
  3. Again a Text Control and we named it as ‘txtMname’.
  4. One more Text Control and we named it as ‘txtLname’.
  5. We named this Button Control as ‘btnCancel’ also set DialogResult Property to Cancel from the possible choices. Based on this DialogResult Property value, C# will set the proper DialogResult Enumeration constant when a user closes the Dialog. In our case, when a user clicks the Cancel Button, the Cancel Enumeration will be set.
  6. We gave ‘btnOK’ as the name for this Button Control. The ‘ DialogResult Property’ is set to OK. Now, we know what value C# returns when a user closes the dialog by clicking the OK Button.
  7. We named our dialog as ‘frmFormatName’. We selected our OK Button as AcceptButton Property. This Property informs C# to call the OK Button handler function when a user hits the Enter Key in the dialog. For CancelButton Property we set our Cancel Button. This Property informs which Button handler to call when a user hits the Esc Key.

4. Display About Form as Modeless C# Dialog

The About Button handler in our Main Form calls the About Form which we designed earlier. We display the About Form as Modeless Dialog and hence user can interact with both the Forms. For Example, they can move both About Form and Main Form. Below is the code:

Note, the show() function will display the About Dialog as Modeless. Moreover, the execution moves to next line after the call. In our case, the show method call is the last statement. If we have more processing after the call to show(), the execution continues even after displaying the About Dialog. The below picture shows the display of About Box:

Main Form Displaying About Form as Modeless Dialog

Main Form Displaying About Form as Modeless Dialog

After the display of About Box as Modeless, we can still reach out with the Main Form. For Example, we can type age in the Age Edit Box or even click the ellipsis button to open the Person Name Dialog. In the above picture, you can see we set Focus to the User Creation Form even though the About Dialog is on the Top. Note, if we click the close button ‘X’ in the Main Form, it also closes the About Dialog.

4. Display Person Name Form as Modal C# Dialog

An application can call a Windows Form as a Modal Dialog. Here, the called Dialog blocks the calling code until user closes it. We will open our Person Name Form as a Modal Dialog from the application’s Main Dialog.

4.1 Formatted Person Name

The Person Name Dialog has four input fields in it. User can feed the input on these text boxes and click OK. The calling main form reads this information which are formatted by the Dialog before it closes. To achieve this, first, we declared a private member variable to hold the formatted person name. The code is below:

4.2 Property to Read Formatted Name

Next, we declared a public property to access that formatted person name. The code calling the dialog as modal waits till user closes it. After that, the Main Form which is the calling code in our case, reads the property to get formatted name. Note, the property is Read-Only. The code is below:

4.3 Modal Dialog’s OK Button Handler

We do not handle the cancel button Click in our example. But, we format the full name of the persons by adding the spaces, a dot and a comma in the Click Event handler for the OK button. Our private member variable stores this formatted information.

4.4 ShowDialog & DialogResult

Finally, from the Application‘s Main Dialog, we call the Person Name Form as a Modal Dialog. The call to the ShowDialog Function will open it as Modal C# Dialog. The return value of ShowDialog call is OK or CANCEL constant from DialogResult Enumeration. Look back, we set ‘ DialogResult’ Property for the OK button as ‘ btnOK’ and for the Cancel button as ‘ btnCancel’.

The main form checks the return value of the ‘ ShowDialog Function’ and when it is ‘ DialogResult.OK’,  it reads the public Property, ‘ FullName’ and then assigns that to the main form’s read only text field. We set ‘blank’ when the user cancels the dialog box. Below is the code:

We completed our example. Now we can run and test it. The below diagram shows the sequence operation:

Displaying a dialog as Modal

Displaying a dialog as Modal

6. Summary

In this example, we created two forms. One form we displayed it as Modeless Dialog and other form we displayed it as Modal Dialog. We saw how Show and Showdialog function can change display as Modal and Modeless. Finally, we looked at the Dialog result and how the caller decides whether user clicked the OK button or Cancel button.

Advertisements

This site uses Akismet to reduce spam. Learn how your comment data is processed.