Manning Windows Forms Programming (phần 6) pps

We could haveattempted to draw a border inside the form using the Control- Paint.DrawBorder3D method, but a Panel provides a much easier solution.The Panel class provides a BorderStyle p

Our focus in this section will be the Panel class This class can contain and tion controls just like the Form class, and supports automated scrolling since it inheritsfrom the ScrollableControl class.2 We will not position controls within a panel

posi-in this chapter, but we will use this class to fix some of the problems we have seen whendrawing directly on the form We will draw our photo directly in a Panel, and solvethe following problems we noticed when drawing directly on the form:

•Our image was off-center vertically for the Scale to Fit display option TheDisplayRectangle property included the vertical space occupied by thescroll bar, which threw our calculations off Here, we will use the panel’s Dis- playRectangle property, so that the image will be centered exactly insidethe panel

•The 3-D border we used for the PictureBox control was gone We could haveattempted to draw a border inside the form using the Control- Paint.DrawBorder3D method, but a Panel provides a much easier solution.The Panel class provides a BorderStyle property much like the correspond-ing PictureBox property, so the NET framework will draw the border for us

•The status bar was part of the scrollable area Since the Form object managedthe scrolling, the StatusBar control on the form was caught up in the scroll-ing logic In this section, the scrolling will be managed by the Panel classindependent of the form and status bar As a result, our status bar will return toand remain at its natural position at the base of the form

Before we get into the required changes, figure 7.5 shows how our three displaymodes will appear by the end of this section As you can see, the application looksmuch more polished here than when we drew directly on the form Note especiallythe excellent centering, the fine border, and the well-behaved scroll bars

2 For the curious, the GroupBox control inherits from the Control class and does not support scrolling.

Figure 7.5 This shows an image drawn inside a panel with the Scale to Fit, Stretch to Fit, and Actual Size display modes.

As you will see, the code to draw the image inside a panel is very similar to drawing theimage directly on the form We will need to add a new panel, update some of our menuhandlers and the drawing of the status bar, and finally draw the image into the panel.

Adding a Panel object in Visual Studio is much like adding any other control Youopen the Toolbox and drag a Panel onto the form In the source code, the panel isadded using the Control property of the parent form We will look at both of these,beginning with the use of Visual Studio

Set the version number of the MyPhotos application to 7.4.

Take a look at the MainForm.cs source file to see how the panel is created As you cansee, this code looks very similar to the code for other controls from prior chapters Aprivate instance is created in the MainForm class, initialized in the Initialize- Component method, and added to the form using the Form.Controls property

private System.Windows.Forms.Panel pnlPhoto;

1 In the MainForm.cs [Design] window, drag a

Panel control from the Toolbox onto the form.

A Panel control is added to the window.

2 Set the panel’s properties as shown.

Settings Property Value

(Name) pnlPhoto BorderStyle Fixed3D

The Panel class depends largely on its base classes for exported functionality, withthe BorderStyle property just about the only new member added by the class Anoverview of the Panel class appears in NET Table 7.5.

With our panel on the form, we need to update the code for drawing our image touse the new panel rather than interacting with the form itself We will begin with themenu handlers for the Image submenu

The menuImage_Popup method simply sets the Enabled and Checked menuproperties as required for the current display mode This behavior does not change, so

no modifications are required The menuImage_ChildClick method sets scrollingproperties for the form Since our scrolling will be managed from the Panel object now,

we need to use the corresponding Panel members rather than those in the Form itself

.NET Table 7.5 Panel class

The Panel class represents a scrollable control that acts as a container for other controls This class is often used to define a region of controls within a Form This class is part of the Sys- tem.Windows.Forms namespace and inherits from the ScrollableControl class See NET Table 7.1 on page 196 for a list of members inherited from the ScrollableControl class.

Public Properties

BorderStyle Gets or sets the type of border to display around the

control.

DisplayRectangle (inherited from Control)

Gets the display area for the control When scrolling is enabled, this property represents the entire scrollable area for the panel The ClientRectangle property represents the visible portion of the control.

Enabled (inherited from Control)

Gets or sets whether the panel is enabled Controls within the panel are disabled whenever the panel itself is disabled.

Visible (inherited from Control)

Gets or sets whether the panel is visible Controls within the panel are invisible if the panel itself is invisible.

U PDATE THE MENU I MAGE _C HILD C LICK METHOD TO USE THE NEW PANEL

1 Locate the

menuImage_ChildClick method in the MainForm.cs source window.

protected void menuImage_ChildClick (object sender, System.EventArgs e) {

.

2 Modify the code for the

ScaleToFit and StretchToFit display mode to set drawing-related properties on the Panel rather than the parent Form

case DisplayMode.ScaleToFit:

case DisplayMode.StretchToFit:

SetStyle(ControlStyles.ResizeRedraw, true);

pnlPhoto.AutoScroll = false;

pnlPhoto.Invalidate();

break;

That’s it for our menu handlers The SetStyle method is a protected member andcannot be modified for our Panel class, so we just force the redraw to happen at theForm level as we did before This will redraw the entire form and not just our panel,but it gets the job done In this case, the drawing required outside of our panel is notoverly complex, so this extra drawing should not be a problem

On a more complex form, it would make sense to handle the Resize event forthe pnlPhoto object instead of setting a form-level style as we do here Handling theResize event would allow us to only redraw the panel itself, and not the other parts

Our status bar is drawn in the statusBar1_DrawItem method This method mustcalculate the percentage of the image shown in the window Since the image will now

be displayed inside the Panel object, we must modify this routine to use the Panelclient area rather than the MainForm one

3 Modify the code for the

ActualSize display mode in a similar manner.

case DisplayMode.ActualSize:

SetStyle(ControlStyles.ResizeRedraw, false);

pnlPhoto.AutoScroll = true;

pnlPhoto.Invalidate();

break;

}

U PDATE THE MENU I MAGE _C HILD C LICK METHOD TO USE THE NEW PANEL

protected void statusBar1_DrawItem (object sender,

StatusBarDrawItemEventArgs sbdevent) {

.

Once again this change simply uses our private Panel field rather than the thiskeyword Our last change is to draw the image inside the panel rather than on theform itself.

When drawing the image on the form, we were able to override the protectedOnPaint method that raises the Paint event For the Panel object, we do not haveaccess to protected members, so we must use the public Paint event to update thepanel Internally in the Windows Forms library, of course, the Panel control will useits own version of the OnPaint method to invoke our event handler

Note that the Paint event handler receives a PaintEventArgs instance containingthe event data As we saw earlier in the chapter, this class contains the Graphicsobject for drawing inside the panel Our code uses this object in the same way aswhen the image was drawn in the form Continuing our previous steps:

2 Modify the calculation of

the percent variable to use the panel rather than the form.

// Calculate percent of image shown int percent = 100;

if (_selectedMode == DisplayMode.ActualSize) {

Photograph photo = _album.CurrentPhoto;

Rectangle dr = pnlPhoto.ClientRectangle;

int imgWidth = photo.Image.Width;

int imgHeight = photo.Image.Height;

percent = 100

* Math.Min(dr.Width, imgWidth)

* Math.Min(dr.Height, imgHeight) / (imgWidth * imgHeight);

} }

U PDATE THE STATUS B AR 1_D RAW I TEM METHOD TO USE THE PANEL (continued)

Double-click the Panel control.

Note: The Paint event is the default event for the panel control in Visual Studio Other events can be added via the Properties window.

Visual Studio generates the appropriate code in the source file.

protected void pnlPhoto_Paint (object sender,

System.Windows.Forms.PaintEventArgs e) {

}

T P

2 In the pnlPhoto_Paint method,

use the given Graphics to draw the image when the album is not empty.

protected void pnlPhoto_Paint (object sender,

System.Windows.Forms.PaintEventArgs e) {

if (_album.Count > 0) {

// Paint the current photo Photograph photo = _album.CurrentPhoto; Graphics g = e.Graphics;

3 Copy the switch statement for

drawing the image from the existing OnPaint method.

switch (_selectedMode) {

} } else { // No image to paint }

}

4 Update this switch block to use

the pnlPhoto object as appropriate.

switch (_selectedMode) {

5 If the album is empty, draw the

standard system control color onto the panel.

else { // No image to paint e.Graphics.Clear(SystemColors.Control); }

}

It may look like a lot of code, but the number of changes is actually quite small, asindicated by the few number of bolded lines The program is all set now Verify thatyour code compiles and runs properly Change display modes, use different-sizedimages, and resize the form to observe the effect.

TRY IT! If you are feeling brave, try adding a Fit to Width menu item to the Image

submenu This should preserve the aspect ratio of the image by scaling theimage to match the width of the panel window You will need to add aFitToWidth enumeration value to the DisplayMode enumeration.Calculate the height using code similar to the Photo- graph.ScaleToFit method where the width is preserved The trickypart is setting the pnlPhoto.AutoScrollMinSize property appropri-ately and drawing the image into this same rectangle

7.5 R ECAP

This chapter has looked at some drawing and scrolling aspects of the Form class Inparticular, we removed the PictureBox control from our application and learned

6 Remove the corresponding

drawing code from the existing OnPaint method.

The OnPaint method now looks as follows:

protected override void OnPaint (PaintEventArgs e)

{

if (_album.Count > 0) {

// Paint the current image Photograph photo = _album.CurrentPhoto; // Update the status bar.

pnlFileName.Text = photo.Caption;

pnlFileIndex.Text = String.Format("{0:#}/{1:#}", _album.CurrentIndex+1, _album.Count);

pnlImageSize.Text = String.Format("{0:#} x {1:#}", photo.Image.Width,

photo.Image.Height);

statusBar1.ShowPanels = true;

} else { // Indicate the album is empty statusBar1.Text = "No Photos in Album"; statusBar1.ShowPanels = false;

}

7 At the end of this method,

invalidate the panel to ensure it is redrawn.

// Ensure contained controls are redrawn pnlPhoto.Invalidate();

how to draw our image directly onto the form We used the protected OnPaintmethod and made use of the automated scroll bars inherited by the Form class to scrollour image This did not work exactly as we wanted, so we modified our code to use thePanel class instead as a way to draw the image independent of the rest of the form.The next chapter will continue our investigation of the Form class by looking atdialog boxes.

C H A P T E R 8

Dialog boxes

8.1 Message boxes 225

8.2 The Form.Close method 233

8.3 Modal dialog boxes 237

8.4 Modeless dialogs 252

8.5 Recap 262

So far we have only used a single window in our MyPhotos application We havechanged its appearance in each chapter, adding controls such as a menu bar, statusbar, and panel, but all controls, events, painting, and other activities have occurredwithin our one Form window In this chapter we branch out

The previous chapter introduced the Form class and demonstrated drawing andscrolling in both it and the Panel class Both of these classes can be used to supportintricate drawing interfaces from those seen in basic drawing applications such asMicrosoft Paint to a full-fledged Internet browser window

Another common use for Form classes is the creation of dialog boxes The Form class , as well as the Panelclass, allows other controls to be positioned and managedinside its boundaries In this chapter we look at how dialog boxes are created for bothsimple message boxes and more complex custom dialogs This will consist of the fol-lowing topics

•Create simple message dialogs with the MessageBox class

•Discuss the use of Close and Dispose for Form objects

•Use the OnClosing method to intercept when a form or dialog box closes

•Explain the difference between modal and modeless dialogs.

•Create dialog boxes using the Form class

Before we get into generating custom dialog boxes, we will first look at how simplemessages are displayed using the MessageBox class

8.1 M ESSAGE BOXES

Developers, especially object-oriented developers, are always looking for shortcuts.Classes such as OpenFileDialog and SaveFileDialog not only provide a stan-dard way to prompt a user for files, they also save programmers a lot of time andeffort by encapsulating the required window display and interaction code Anothercommon task programmers face is the need to display a simple message to the user.Our photo album application, for example, should really display an error messagewhen an album cannot be saved successfully, or it could pose a question by asking theuser if they would like to save the album to an alternate file location

The NET Framework provides a MessageBox class for this purpose This class

is very similar to the MFC function of the same name This section will show how thisclass is used to handle simple interactions with a user While this class is not actually

a Form object, it is the most basic type of modal dialog box

All dialog boxes are either modal or modeless A modal dialog box requires the user to respond before the associated program will continue Modeless or nonmodal dia-

log boxes allow the application to continue while the dialog box is displayed.All MessageBoxwindows are modal, while Formwindows are modal if invokedvia the Form.ShowDialog method and modeless if invoked via the Form.Showmethod

Figure 8.1 These examples show the four types of icons available to

MessageBox dialogs.

Figure 8.1 shows some sample message boxes with various settings Note the differentbutton configurations, and how the Question Icon dialog has defined No as thedefault button An overview of the MessageBox class is provided in NET Table 8.1.

.NET Table 8.1 MessageBox class

The MessageBox class represents a modal dialog box that displays a message or question to the user and waits for their response This class is part of the System.Windows.Forms namespace A MessageBox cannot be instantiated as an object with the new keyword; instead the static Show method is used to display the dialog.

By default, a message box displays with no icon and a single OK button The Show method

is overloaded to allow these and other settings to be customized There are four tions used for this purpose: MessageBoxButtons , MessageBoxIcon , MessageBoxDefault- Button , and MessageBoxOptions In the following table, the enumeration values for some

enumera-of these four types are included, since these types are only used with the MessageBox.Show method.

Public Static Methods

Show Displays a message box and returns the

DialogResult enumeration value corresponding to the button selected by the user.

MessageBoxButtons Enumeration Values

OK The message box should contain an OK button only OKCancel The message box should contain an OK and Cancel

Error The message box should contain an error symbol, a

white X in a red circle Use this for unexpected problems that prevent an operation from continuing Information The message box should contain an information

symbol, a lower case letter ‘i’ in a circle Use this for general messages about the application such as a status or notification.

Question The message box should contain a question mark

symbol Use this for Yes/No questions where a choice by the user is required.

Warning The message box should contain a warning symbol,

an exclamation point in a yellow triangle Use this for problems that may interfere with the ability of an operation to continue.

Button Enumeration Values

MessageBoxDefault-Button1 The first button in the message box is the default Button2 The second button is the default.

Button3 The third button is the default.

8.1.1 T HE M ESSAGE B OX S HOW METHOD

A MessageBox instance cannot be instantiated Instead, the Show method is used tocreate the message dialog and return the result There are a number of overloads avail-able for this method, from a version that takes a single message string to one thataccepts a parameter for everything from the title bar text to which button should bethe default Various forms of this method are shown in the following signatures Thecomment preceding each signature refers to the characters in bold

// The return value indicates which button was clicked by the user

public static DialogResult Show( string text );

// Displays the dialog in front of the specified window object

public static DialogResult Show( IWin32Window owner, string text );

// Accepts a message string and title bar caption

public static DialogResult Show( string text, string caption );

// Displays the dialog with the specified buttons

public static DialogResult Show( IWin32Window owner,

•When an error occurs while trying to open an existing album

•When an error occurs while trying to save the current album

•When the current album has changed and is about to be discarded

We will add a MessageBox to our program for each of these instances

When we are unable to open a selected album, there is not much to do other thaninform the user that something is wrong We will use an error dialog since a failurehere is not normally expected The resulting dialog is shown in figure 8.2

Figure 8.2 This message box is displayed when the album contains an unrecognized version number.

Let’s add the code to create this dialog whenever an unexpected problem occurs whileopening the file

Set the version number of the MyPhotos application to 8.1.

In this code, we cheated a little by catching any and all Exception objects in thecatch block It is normally safer to catch specific exceptions that may occur so youcan provide feedback or take actions based on the specific error In this code, anIOException will occur if an unexpected error occurs during a file I/O operation Ifyou recall, the PhotoAlbum.Open method throws an IOException explicitly if theversion number in the file is not recognized

It is also worth noting that we ignore the result returned by the Showmethod,since there is only a single OK button in the dialog

H ANDLE EXCEPTION IN MENU O PEN _C LICK METHOD

.

2 Enclose the code to open

the album in a try block.

if (dlg.ShowDialog() == DialogResult.OK) {

try { // Open the new album.

catch (Exception ex)

4 Display the dialog in the

catch block.

{ MessageBox.Show(this, "Unable to open file " + dlg.FileName + "\n (" + ex.Message + ")", "Open Album Error",

MessageBoxButtons.OK, MessageBoxIcon.Error);

} } }

Note: The text string is constructed using the + (plus

sign) notation for strings Also note that a new line is inserted in the dialog with the \n character.

8.1.3 C REATING A Y ES N O DIALOG

As an alternate example, what happens when an error occurs while saving an album?

We could simply display an OK dialog as we did while opening an album Thiswould just duplicate the previous code, so we will do something different Instead, wewill allow the user to save the album under an alternate file name This permits theuser to save the album to an alternate location that is less likely to fail, or retry thesave to the same location The new message box is shown in figure 8.3

The steps required to generate this message dialog are shown in the following table:

Figure 8.3 This message box is displayed when an exception occurs in the

menuSave_Click method.

H ANDLE EXCEPTION IN MENU S AVE _C LICK METHOD

1 Locate the menuSave_Click

method in the MainForm.cs file.

private void menuSave_Click (object sender, System.EventArgs e) {

.

2 Enclose the code to save the

album in a try block.

else { try { // Save album in current file _album.Save();

_bAlbumChanged = false;

}

3 Catch any exception that occurs catch (Exception ex)

{

4 Within the catch block, display

the dialog and record the selected button.

string msg = "Unable to save file {0}" + " - {1}\nWould you like to save" + " the album in an alternate file?"; DialogResult result

= MessageBox.Show(this, String.Format(msg, _album.FileName, ex.Message), "Save Album Error",

MessageBoxButtons.YesNo, MessageBoxIcon.Error, MessageBoxDefaultButton.Button2);

5 If the user wishes to save under

an alternate name, prompt the user for the new file name.

How-to

Use the Save As menu handler.

if (result == DialogResult.Yes) {

menuSaveAs_Click(sender, e);

} } }

Unlike our message for the Open handler, this code makes use of the result returned

by the Show method This result is a DialogResult enumeration that indicates thebutton pressed The values in this enumeration are shown in NET Table 8.2, andcorrespond to the kinds of buttons typically found in Windows dialogs

You can compile and run this code if you would like to see the message boxes we ated You can generate an open error easily enough by selecting a file that is not, infact, an album file A save error can be generated by attempting to save to a read-only

cre-CD, or by filling up a floppy disk and then saving a file to it

Our last example will generate a message box for closing an existing album

Our final example is the case where an album has changed but is about to be discarded.This can occur when the application is about to exit, when loading a new album withthe Open menu item, and when creating a new album with the New menu item

To handle these situations in a consistentway, we will create a protected method to

gracefully close the current album for all three

cases using the dialog in figure 8.4 We will

call this method CloseCurrentAlbum and

have it return a boolean value indicating

whether the album was closed or the user

clicked the Cancel button

.NET Table 8.2 DialogResult enumeration

The DialogResult enumeration represents a value returned by a dialog box This class is part of the System.Windows.Forms namespace, and is used with all dialog boxes in Win- dows Forms In particular, a DialogResult is returned by the MessageBox.Show method as well as the ShowDialog method in both the Form class and common dialogs derived from the CommonDialog class This enumeration is also used by the Button class to indicate the result to automatically return from a modal dialog when the button is clicked.

Enumeration Values

Abort The dialog return value is Abort Typically, this means the user

clicked an Abort button.

Cancel The dialog returns Cancel, typically from a Cancel button Ignore The dialog returns Ignore, typically from an Ignore button.

No The dialog returns No, typically from a No button.

None The dialog returns nothing, indicating that the dialog box is still

running.

OK The dialog returns OK, typically from an OK button.

Retry The dialog returns Retry, typically from a Retry button.

Yes The dialog returns Yes, typically from a Yes button.

Figure 8.4 This dialog is displayed when

an album is about to be discarded.

The three buttons in our dialog will correspond to the following behavior in ourCloseCurrentAlbummethod:

•Yes will save the album, then close the album and return true

•No will not save the album, then close the album and return true

•Cancel will not save or close the album and return false to indicate that thecalling operation should be canceled

To close the album, CloseCurrentAlbum will clear the album and related settings.The following steps create this method:

We will use this new method in three different places to ensure that the user has theoption of saving any changes he or she might make to the album

A DD A C LOSE C URRENT A LBUM METHOD

1 Add the

CloseCurrentAlbum method to the MainForm.cs source code window.

protected bool CloseCurrentAlbum() {

2 Offer to save the album if it

has been modified.

if (_bAlbumChanged) {

// Offer to save the current album

3 Define an appropriate

message to display.

Note: We vary the

mes-sage text depending on whether the current album has a name or not.

string msg;

if (_album.FileName == null) msg = "Do you want to save the "

+ "current album?";

else msg = String.Format("Do you want to " + "save your changes to \n{0}?", _album.FileName);

4 Display the message box

and record the result.

DialogResult result = MessageBox.Show(this, msg, "Save Current Album?", MessageBoxButtons.YesNoCancel, MessageBoxIcon.Question);

5 Perform the action

requested by the user.

if (result == DialogResult.Yes) menuSave_Click(this,EventArgs.Empty); else if (result == DialogResult.Cancel) {

// Do not close the album return false;

} }

6 Close the album and return

true

Note: This action is only

performed if the Yes or No button was selected.

// Close the album and return true

if (_album != null) _album.Dispose();

_album = new PhotoAlbum();

SetTitleBar();

_bAlbumChanged = false;

return true;

}

•In menuNew_Click to save the existing album before a new album is created.

•In menuOpen_Click to save the album before a new album is selected

•In menuExit_Click to save the album before the application exits

We will modify the handlers for the New and Open menus here The Exit menu sents some additional issues, which we will take up in the next section The followingtable continues our previous steps

pre-These changes make our application much more user-friendly by interacting with theuser when they are about to discard a modified album

TRY IT! Before moving on, create a MessageBox dialog in the

menuRe-move_Click method, where the current photograph is removed withoutany confirmation by the user Add a question box here to verify that theuser does indeed want to remove the current photo

Another place where a message box could be used is at the beginning andend of the album Modify the Next and Previous menus to display an in-formation dialog whenever the user tries to move before the beginning ofthe album or past the end.1

For the Exit menu, life is not so easy We will pick up this topic in the next section

U PDATE THE HANDLERS FOR THE N EW AND O PEN MENUS

7 Modify the menuNew_Click

method to use the CloseCurrentAlbum method.

protected void menuNew_Click (object sender, System.EventArgs e) {

if (this.CloseCurrentAlbum() == true) {

// Make sure the window is redrawn this.Invalidate();

}

}

8 Modify the menuOpen_Click

method to use the CloseCurrentAlbum method.

Note: The new code here

replaces the previous code in this method to save the current album The remainder of this method stays the same.

protected void menuOpen_Click (object sender, System.EventArgs e) {

// Save the existing album, if necessary

if (this.CloseCurrentAlbum() == false)

{ // Cancel this operation return;

}

OpenFileDialog dlg = new OpenFileDialog();

}

1 The interface designers among us will argue that the Previous and Next commands should be disabled

at the beginning and end of the album, respectively Why allow the user to invoke a menu item that does not work? I would not disagree, and if you prefer this approach, please go right ahead.

8.2 T HE F ORM C LOSE METHOD

In this section we pick up the thread of our previous discussion on the rentAlbummethod by discussing the Closeand Disposemethods You may thinkthis is a little off-topic from dialog boxes, but in fact it is quite relevant One of thekey issues for C# programming in NET is when to call the Dispose method toclean up window handlers and other nonmemory resources This section will discussthis topic as it relates to dialog boxes, and introduce the Closingevent as a way tointercept a user’s request to close a form

Before we return to the topic of calling CloseCurrentAlbum when our applicationexits, let’s look at the relationship between Close and Dispose in NET It’s actu-ally quite simple: they are the same For all classes in the NET Framework, a call toClose is equivalent to calling the Dispose method, and a call to Dispose is equiv-alent to calling the Close method The term “close” traditionally applies to objectslike files and windows, and NET has preserved this terminology When you are fin-ished with a form or a file, it seems silly to require a call to both Close and Dis- pose, so it makes sense to merge these two concepts together The NET design teamcould have chosen to use a common name for all classes, but programmers naturallyexpect to close objects such as forms and files, and closing objects like arrays or draw-ing objects seems a bit odd Instead, the designers chose to use both methods anddefine them to be equivalent

For Formobjects, the behavior of the form itself varies depending on whether theobject is displayed as a modal or modeless window For a modeless window, displayedwith the Form.Show method, the nonmemory resources are automatically cleaned upwhen the form is closed This makes life much easier for us programmers, since we donot have to remember anything in this case You cannot use a modeless Formafter it

is closed since all of its resources are gone The Hidemethod should be used if yousimply want to remove a Form from the desktop and display it later via the Showmethod We will see this in chapter 13 when we use a tool bar button to hide the mod-eless dialog created in section 8.4 of this chapter

For modal windows, displayed with the Form.ShowDialogmethod, there is aproblem in that the dialog is typically accessed after the window disappears As a result,

a modal dialog must call Disposeexplicitly to release its nonmemory resources ically, a modal dialog is created and destroyed in the same block of code For example:

{

MyModalDialog dlg = new MyModalDialog();

// Initialize any dlg settings

if (dlg.ShowDialog() == DialogResult.OK)

{

// Use dlg settings to do something

dlg.Dispose()

}

In this code, if the resources for the dlg variable disappeared after the ShowDialogmethod returned, you could not access any of its settings For this reason, NET onlycalls the Hide method after a user responds to a modal dialog, so that the dialog set-tings may still be accessed This can be a little confusing since we still say the usercloses the dialog, even though the dialog’s Close method is not actually called

Fortunately, modal dialog boxes tend to have deterministic scope, meaning that

you can predict when the dialog will be created and destroyed The application waitsuntil the user responds to a modal dialog, so it’s clear where the Disposemethodmust be called We have already seen this method used with OpenFileDialog andSaveFileDialogobjects in chapter 6, both of which are modal dialogs

The C# language provides a using statement to call Dispose on our behalf indeterministic situations such as this We have seen how the using directive defines

an alias or shortcut for an object or members of a namespace The using statementdefines the scope in which a given object should exist The syntax is as follows:

For the remainder of the book, we will generally employ the using statement inour examples to dispose of nonmemory resources rather than calling the Disposemethod explicitly.

Let’s get back to our application and the CloseCurrentAlbum method Since ourapplication is a modeless dialog, Close will be called when the application exits Infact, we call the Close method explicitly in the Click handler for our Exit menu

We could certainly use the CloseCurrentAlbummethod in our Clickeventhandler While this would work for the Exit menu, it does not work for the case wherethe application exits via the Alt+F4 keyboard shortcut or the Close option on the sys-tem menu.2

To handle both situations, the Formclass provides a Closing event that occurswhenever the form is about to close The protected OnClosingmethod is invokedwhenever the Close method is called, and it in turn raises the Closingevent byinvoking any registered event handlers The signature for this method is as follows:

protected virtual void OnClosing(CancelEventArgs ce);

2 The system menu, as you may know, is the menu of operating system commands that appears when

you click the control box icon in the upper left corner of a window You can also right-click an cation’s title bar or its entry in the task bar to display this menu.

appli-As you can see, this method receives a CancelEventArgs object This class defines

a Cancel property to help determine whether the application will actually exit Ifthis property is set to true by an override of the OnClosing method or a Closingevent handler, then the close operation is cancelled and the application will continue

to run The Cancel property has a default value of false, so that the close tion is not cancelled and the application will exit

opera-We will override the OnClosingmethod in our MainFormclass to make surethe CloseCurrentAlbummethod is called regardless of how the application exits

Set the version number of the MyPhotos application to 8.2.

Compile and run the application to see this method in action Add a few photos andtry to exit the application using the Exit menu, the Alt+F4 key, and the Close optionfrom the system menu In all cases, you should be queried by the CloseCurrent- Album method with the question dialog for saving the current album If you selectthe Cancel button the application will not, in fact, exit

O VERRIDE THE O N C LOSING METHOD

1 Override the OnClosing

method in the MainForm.cs source window.

protected override void OnClosing (CancelEventArgs ce)

{

2 Within this method, call the

CloseCurrentAlbum method to see if the current album should be saved.

if (this.CloseCurrentAlbum() == false)

3 If the user clicked the

Cancel button, then cancel the close operation.

ce.Cancel = true;

Note: This cancels the Close operation so that the

appli-cation does not exit.

4 Otherwise, allow the

application to close.

else ce.Cancel = false;

Note: Since false is the default value, these lines are not strictly required They are here simply to illustrate the setting when the application is permitted to exit.

Note: This call ensures that logic internal to the Form

class is performed, and ensures that any Closing event handlers for the form are called before the application exits Of course, any registered handler can prevent the application from exiting by setting ce.Cancel to true

Before we go on, we should point out that our OnClosing override can be ten more succinctly by taking advantage of the boolean value returned by our closealbum method.

protected override void OnClosing(CancelEventArgs ce)

{

ce.Cancel = (!this.CloseCurrentAlbum());

base.OnClosing(ce);

}

Now that we know all about closing a dialog box, let’s see how to create one of our own

8.3 M ODAL DIALOG BOXES

In earlier chapters, we added controls such as a Button, PictureBox, and tusBar to our main form, and displayed and managed these objects within the Formclass on behalf of our application In this section we will see how a dialog box can becreated and displayed to further our understanding of the Form object

Sta-As a way to introduce this concept, we will add the ability to assign a caption to

an image This caption will be a text string supplied by the user The dialog box shown

in figure 8.5 will allow the user to modify this value The base file name of the imagewill be used as the default caption

In order to support this dialog, we will need to modify three aspects of our application:

1 Data layer. Our Photograph class must support a caption on an image, andour PhotoAlbum class must store and retrieve these captions when saving andopening files

2 Presentation layer. We need a class to display our form as a dialog box We willcall this class CaptionDlg This class must provide the interface and a meansfor returning a new caption value set by the user

3 Application layer. Our MainForm class must provide access to the new face, and the link between the interface layer in our CaptionDlg class and thedata layer in our MyPhotoAlbum library

inter-We will address each of these layers separately in order to create our new dialog

Figure 8.5 Our dialog box will contain three text labels, a text box, and two buttons.

8.3.1 A DDING CAPTIONS TO PHOTOS

Let’s begin with the data layer In this section we will support captions on graphs, and in the next section store and retrieve captions in our photo album files Inthe Photograph class, we need to track the caption value, and allow external classes toset and get this value These changes are detailed by the following steps

photo-Set the version number of the MyPhotoAlbum library to 8.3.

We now have the ability to set captions for individual photographs This will not do

us much good unless our album class preserves these captions in the album file Forthis we need to modify the Openand Save methods

A DD A CAPTION TO THE P HOTOGRAPH CLASS

1 In the Photograph.cs file,

add a private _caption field to hold the caption for the object.

private string _fileName;

private Bitmap _bitmap;

private string _caption;

2 Initialize the caption to the

base name of the file in the constructor.

using System.IO;

public Photograph(string fileName) {

4 Implement the get

accessor to return the current caption.

get { return _caption; }

5 Implement the set

accessor to revert to the default on null , and otherwise use the given value.

set {

if (value == null || value.Length == 0) {

_caption = Path.

GetFileNameWithoutExtension(_fileName); }

else { _caption = value;

} } }

Note: The value keyword is used as a string object here since the containing property is of type string

How-to

a Add a using System.IO statement at the top of the file.

b Use the Path class to retrieve the base file name.

Before we do, note that we can make immediate practical use of our caption inthe MainFormclass The sbpnlFileNamestatus bar panel has previously displayedthe entire path to the file, which may not fit when the window is small The photo’scaption seems like a much better choice here.

Set the version number of the MyPhotos application to 8.3.

Our new caption values must be saved whenever an album is saved to disk, andloaded when an album is opened To do this, we need to create a new version of ouralbum file, while still preserving the ability to read in our existing files Fortunately,

we established a version number for these files in chapter 6, so the changes requiredare not too extensive First, let’s look at the changes to our Save method

Note that the rest of our Save method works as before In particular, the current sion number is written as the first line of the file Since we updated the constant forthis number, the value written to our new album files is updated as well

ver-Next we need to modify our Open method to read the new file format We will alsopreserve backward compatibility with our older version This can be done by handling

D ISPLAY THE CAPTION VALUE IN THE STATUS BAR

6 Locate the OnPaint

method in the MainForm.cs source code.

protected override void OnPaint (PaintEventArgs e)

{

7 Modify the

sbpnlFileName status bar panel to display the caption.

if (_album.Count > 0) {

// Update the status bar.

sbpnlFileName.Text = photo.Caption;

} }

U PDATE THE S AVE METHOD TO STORE CAPTIONS

1 In the PhotoAlbum.cs file,

modify the version constant to be 83.

private const int _CurrentVersion = 83;

2 Modify our foreach loop in

the Save method to store both the file name and caption, each on a separate line.

public void Save(string fileName) {

// Store the data for each photograph foreach (Photograph photo in this) {

sw.WriteLine(photo.FileName);

sw.WriteLine(photo.Caption);

} }

our previous version number 66 in addition to our new one We continue the previoustable with the following steps.

Our data layer is complete We can add individual captions to photographs, and thesecaptions are preserved as the album is saved and opened Next we turn our attention

to the new Form required

With our data layer ready, we can turn to the presentation layer This requires the log previously shown in figure 8.5 In this section we create a new Form class to holdthe dialog, and look at what settings should be set to turn the default form into astandard dialog box In the next section we will add some properties to this class sothat our MainForm class can interact with the dialog

dia-In previous Windows development environments, an explicit class such asCDialog created a dialog box directly It would certainly be possible to create aFormDialogclass in NET derived from the Form class for this purpose, and per-haps Microsoft will do so in the future Until this happens, you will have to createyour own dialog class or modify each dialog form separately to have dialog boxbehavior The following table summarizes the properties required to turn the defaultForm into a somewhat standard dialog box

U PDATE THE O PEN METHOD TO READ CAPTIONS

3 Modify the switch block in

the Open method to recognize both the old and current version.

public void Open(string fileName) {

switch (version) {

case 66:

case 83:

{ string name;

4 Modify the do while

loop to read the caption when a newer version of the file is opened.

do { name = sr.ReadLine();

if (name != null) {

Photograph p = new Photograph(name);

break;

}