![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tn013.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / mfc / doc|
Return to tn013.txt CVS log | Up to [WindowsNT SDKs] / mstools / mfc / doc |
1.1 root 1:
2: Microsoft Foundation Classes Microsoft Corporation
3: Technical Notes
4:
5: #13 : Using the standard dialog classes
6:
7:
8: This note describes the use of the standard dialog classes provided
9: with MFC. The classes are CFileDialog, CFontDialog, CColorDialog,
10: CPrintDialog, and CFindReplaceDialog. They provide standard user interface
11: objects for your application. The class declarations for these
12: classes can be found in the source file \C700\MFC\INCLUDE\AFXDLGS.H.
13: =============================================================================
14:
15:
16: Requirements
17: ============
18: You may use these classes for any MFC application. Although these
19: classes use the Windows 3.1 COMMDLG functions, they do not require
20: Windows 3.1 to run. You must redistribute COMMDLG.DLL with your
21: application and install the DLL in the user's Windows 3.0 system directory.
22: When building an application that uses these classes, you must
23: link with the library COMMDLG.LIB, which is part of the Windows SDK
24: installation.
25:
26:
27: General Use
28: ===========
29: These dialogs classes may be used in one of two ways. You can use them
30: "as is" and supply the necessary arguments to the constructor to
31: customize the dialogs to suit your needs. You might also
32: consider deriving from these classes and providing a specific constructor
33: tailored to your needs. In either case, these dialogs act
34: like standard MFC dialogs, since they derive from CDialog (either
35: directly or indirectly.) You can use message maps and customize
36: these dialogs even more.
37:
38: COMMDLG dialog APIs interface with the application code via
39: a parameter block structure. The MFC dialog classes provide
40: public access to this structure, which may be accessed at any
41: time to permit maximum customization. On the other hand, MFC
42: provides sensible defaults for most of the fields in the parameter
43: block so that you do not need to worry about them. These structures
44: are described in the online Windows 3.1 API reference.
45:
46:
47: Examples
48: ========
49: The MULTIPAD sample application uses the CFileDialog, CFontDialog,
50: and CPrintDialog. The CHART application uses CFileDialog
51: and CPrintDialog. The MDI application uses the CColorDialog. In
52: addition, the OLE classes use the standard CFileDialog for
53: implementing standard OLE user interface objects.
54:
55:
56: CFileDialog
57: ===========
58: The CFileDialog class encapsulates the OPENFILENAME structure
59: and the two Windows APIs GetOpenFileName and GetSaveFileName. This
60: dialog box is used to obtain from a user either a new file name
61: or the name of an existing file to open. CFileDialog is a modal
62: dialog and derives from the class CModalDialog.
63:
64: To use a CFileDialog class object, create an object using the CFileDialog
65: constructor. The arguments to the constructor are below, note
66: that several have default values:
67:
68: bOpenFileDialog set to TRUE for file open dialog, FALSE for
69: a file save dialog
70: lpszDefExt is the default extension, if a user does not
71: include a file extension, this is
72: automatically appended.
73: lpszFileName is the initial file name (defaults to NULL)
74: dwFlags is a set of flags that you can supply
75: that allow you to customize the dialog box.
76: See the online Windows API reference
77: (OPENFILESTRUCT) for more information
78: (defaults to OFN_HIDEREADONLY |
79: OFN_OVERWRITEPROMPT)
80: lpszFilter is a series of pairs of strings that specify
81: filters the user may apply to the files.
82: See below (defaults to NULL)
83: pParentWnd is a pointer to a parent Window. This is
84: used only when routing customized help
85: messages (defaults to NULL.)
86:
87: The lpszFilter is used to display a possible list of suffixes. For
88: example Microsoft Excel permits users to open *.XLC and *.XLS
89: (and many others). The filter for Excel would look something
90: like the following:
91:
92: char BASED_CODE szFilter[] =
93: "Chart Files (*.xlc)|*.xlc|Worksheet Files (*.xlm)|*.xlm|All Files (*.*)|*.*||"
94:
95: Note the use of '|' to separate the components of the filter. Also
96: note that the entire filter ends with two '|'. This is the
97: standard MFC syntax for specifying filters. Also, note that the
98: entire string is a standard NULL terminated C string, though you
99: can always use an MFC CString object.
100:
101: Once the dialog has been constructed, you are free to modify the
102: public member variable m_ofn, which is an OPENFILENAME structure.
103: You may manually set any flags or fields that you need. When you
104: are ready to prompt the user call the DoModal function (this is
105: a virtual function derived from CModalDialog.) The user is then
106: prompted for a file name (either an existing file or new file,
107: depending on the bOpenFileDialog constructor parameter.) When
108: the user clicks OK, CANCEL, or selected the CLOSE option from the
109: dialogs System Menu, control is returned to your application. The
110: return value from DoModal indicates success (IDOK) or
111: failure (IDCANCEL.) If the return value is IDCANCEL, either the
112: user closed the dialog or clicked CANCEL, or there was an error
113: in the parameter block. If you suspect an error, you can call
114: the CommDlgExtendedError API to learn more about the problem.
115: CommDlgExtendedError function returns 0 if there was no error.
116: This function differs from the standard OnOK and OnCancel functions
117: in that it is possible to force the user to change actions, whereas
118: OnOK and OnCancel are notifications that you must accept.
119:
120: If the user chose a file name, then you can continue processing.
121: The CFileDialog class provides a number of helper functions to
122: retrieve information regarding the users choice:
123:
124: GetPathName retrieves the fully qualified path name of the
125: selected file (suitable to use with CFile)
126: GetFileName retrieves just the file name without an extension
127: GetFileExt retrieves only the file extension (without a '.')
128: GetFileTitle retrieves the preferred title of the file, which
129: should be used as the title text of the frame window
130: GetReadOnlyPref returns TRUE if the user checked the read-only
131: option. If this is TRUE, you should open the file
132: with read-only permissions.
133:
134: There are also several "callback" functions that you may respond
135: to in your derived CFileDialog class. You do not need message map
136: entries for these, since they are standard virtual functions.
137:
138: OnShareViolation this function is called when a network
139: sharing violation occurs while processing
140: the dialog. See OPENFILENAME in the Windows
141: API for more information.
142: OnLBSelChangeNotify this function is called whenever the
143: user changes the selection(s) in the file
144: list. You can use this message if you
145: need to do extra work when a file is
146: a potential selection, such as calculating
147: disk space required, or displaying
148: file access rights.
149: OnFileNameOK this function is called when the user
150: selects OK. You can validate the file name
151: and determine if the user can continue. If
152: you return TRUE, be sure to indicate to the
153: user the problem with the selected file(s.)
154:
155: One other technique available to customize the CFileDialog is to
156: introduce a message map in a derived class and to handle messages
157: just as you would for any other dialog. For example, you can modify
158: the dialog background color or handle the command messages for
159: a new control (the .RC file for the dialog is included.)
160:
161:
162: CFontDialog
163: ===========
164: The CFontDialog class provides support for a standard dialog
165: that permits a user to choose a font. The dialog makes use
166: of the COMMDLG structure CHOOSEFONT and the API ChooseFont.
167: CFontDialog is a modal dialog derived from the CModalDialog class.
168:
169: To use a CFontDialog class object, create an object using the CFontDialog
170: constructor. The arguments to the constructor are below, note
171: that several have default values:
172:
173: lplfInitial the initial settings of the dialog box (defaults
174: to NULL)
175: dwFlags is a set of flags that you can use to customize
176: the function and appearance of the dialog. See
177: the CHOOSEFONT structure reference for more
178: information on possible values. (defaults to
179: CF_EFFECTS | CF_SCREENFONTS)
180: hdcPrinter if supplied is a CDC for the printer for which fonts
181: are to be selected (defaults to NULL)
182: pParentWnd is a pointer to a parent Window. This is
183: used only when routing customized help
184: messages (defaults to NULL)
185:
186: As with the CFileDialog class, once the object has been constructed
187: you are free to modify the CHOOSEFONT structure, m_cf, in order
188: to customize the dialog box fully. After any further customization,
189: you call the member function DoModal, which will return either
190: IDOK or IDCANCEL. If the return value is IDCANCEL, the user clicked
191: on CANCEL or there was an initialization error in the dialog. You
192: may use the CommDlgExtendedError function to determine if there
193: was an initialization error. If the user selected OK the IDOK value
194: is returned. The CFontDialog class provides a number of helper functions
195: for extracting information out of the dialog:
196:
197: GetFaceName returns the face name of the font
198: GetStyleName returns the style name of the font
199: GetSize returns the point size in 1/10ths of a point
200: GetColor returns the color of the selected font
201: GetWeight returns the weight of the font
202: IsStrikeout returns TRUE if the strikeout effect was selected
203: IsUnderline returns TRUE if the underline effect was selected
204: IsBold returns TRUE if the weight is equal to FW_BOLD
205: IsItalic returns TRUE if the font is italic
206:
207: In addition, the member variable m_lf is the LOGFONT descriptor
208: of the font, which can be used in a CreateFontIndirect call,
209: or accessed directly.
210:
211: You may customize the dialog by deriving your own class from CFontDialog
212: and using a message map to handle any messages. You can also use
213: the CFontDialog::GetCurrentFont member function to determine the
214: currently selected font while in a message handler.
215:
216:
217: CColorDialog
218: ============
219: The CColorDialog class provides support for a standard dialog
220: that permits a user to choose/create a color. The dialog makes use
221: of the COMMDLG structure CHOOSECOLOR and the API ChooseColor.
222: CColorDialog is a modal dialog derived from the CModalDialog class.
223:
224: CColorDialog is used just like CFontDialog. The COMMDLG structure
225: that is used for customizing the dialog is CHOOSECOLOR, and it
226: can be modified after construction of the object and before
227: DoModal is called. The arguments to the constructor are as
228: follows:
229:
230: clrInit is a COLORREF that is the initial color selection
231: (defaults to RGB(0,0,0))
232: dwFlags is a set of flags that you can use to customize
233: the function and appearance of the dialog. See
234: the CHOOSECOLOR structure reference for more
235: information on possible values. (defaults to 0)
236: pParentWnd is a pointer to a parent Window. This is
237: used only when routing customized help
238: messages (defaults to NULL.)
239:
240: In addition, the CColorDialog permits the user to define up to 16
241: custom colors. The CColorDialog saves these custom colors between
242: invocations of the dialog in the static member variable clrSavedCustom.
243: If you wish to save these colors between executions of the application,
244: then you must do this yourself. After the dialog has been constructed
245: you call DoModal. If the return value is IDOK, then you can use
246: the GetColor member function to retrieve the color the user
247: selected.
248:
249: As with all of the standard dialog classes, you are permitted
250: to define a message map in your derived CColorDialog class
251: customize the dialog to suite your needs. The member function
252: SetCurrentColor is provided for forcing the currently selected
253: color to a certain value. As with CFileDialog, a validation
254: callback is provided that gives you a chance to override the OK
255: selection. This validation is handled in the OnColorOK virtual
256: function.
257:
258:
259: CPrintDialog
260: ============
261: The CPrintDialog class provides support for a standard dialog
262: that permits a user to print a document or setup the printer.
263: The dialog makes use of the COMMDLG structure PRINTDLG and the
264: API PrintDlg. CPrintDialog is a modal dialog derived from
265: the CModalDialog class.
266:
267: As with CFileDialog, CPrintDialog is really two different dialogs,
268: distinguished by a constructor argument. The CPrintDialog class
269: can be used to respond to the Print command and/or the Print Setup
270: command (both usually in the File menu.) The arguments to the
271: constructor for CPrintDialog include:
272:
273: bPrintSetupOnly TRUE if you want only a Print Setup
274: dialog, FALSE for the Print dialog
275: dwFlags is a set of flags that you can use to customize
276: the function and appearance of the dialog. See
277: the PRINTDLG structure reference for more
278: information on possible values. (defaults to
279: PD_ALLPAGES | PD_USEDEVMODECOPIES | PD_NOPAGENUMS
280: | PD_HIDEPRINTTOFILE | PD_NOSELECTION)
281: pParentWnd is a pointer to a parent Window. This is
282: used only when routing customized help
283: messages (defaults to NULL.)
284:
285: You may use the GetDefaults member function to retrieve the
286: current printer defaults. All of the helper functions described
287: below will be valid after a successful return. Note that
288: this member function requires no user interaction.
289:
290: As with other standard dialogs, you can customize the appearance
291: and functionality by directly modifying the PRINTDLG structure,
292: which is the m_pd member variable. After any customization
293: you call DoModal, which will return IDOK or IDCANCEL as expected.
294: Remember to check for extended errors if IDCANCEL is the return
295: value, since there might have been a setup error. If IDOK
296: is returned there are a number of functions that can be used
297: to retrieve information about the selected printer. Some of
298: these functions might not be valid, depending on the settings
299: of dwFlags and m_pd.Flags.
300:
301: GetCopies returns the number of copies the user chose
302: GetFromPage returns the starting page of the print job
303: GetToPage returns the ending page of the print jon
304: GetDevMode returns a pointer to the device mode
305: GetDriverName returns a string that is the driver name
306: GetDeviceName returns a string that is the device name
307: GetPortName returns a string that is the port name
308: PrintCollate returns TRUE if the job is to be collated
309: PrintAll returns TRUE if All pages selected
310: PrintRange returns TRUE if the user entered a print range
311: (GetFromPage and GetToPage are then valid)
312: PrintSelection returns TRUE if the user wishes to print
313: the current selection
314: GetPrinterDC returns an HDC for the selected printer
315:
316: The GetPrinterDC function returns an HDC only if the bPrintSetupOnly
317: constructor parameter was FALSE (i.e. the Print dialog is displayed.)
318: You are responsible for calling DeleteDC. If you wish to
319: use this DC as an MFC CDC object, then you can attach it to
320: an object as follows:
321: {
322: CDC printerDC;
323: CPrintDialog pd(FALSE);
324: if (pd.DoModal() == IDCANCEL)
325: return FALSE;
326: printerDC.Attach(pd.GetPrinterDC());
327: // print using printerDC
328: } // falling out of scope will implicitly call CDC::DeleteDC
329:
330: While the Print dialog is active, it is possible for the user to
331: obtain a Print Setup dialog and further customize the print job.
332: MFC handles this automatically for you.
333:
334: You may customize the CPrintDialog object by deriving your
335: own class from it and using a message map to handle messages and
336: commands of your choosing. If you wish to handle the same message
337: differently depending on if the Print dialog or Print Setup dialog
338: is active you will need to derive an additional class, one
339: for the Print dialog and one for your custom Print Setup dialog. In
340: your print dialog class you will also need to override the
341: AttachOnSetup member function. This function handles the creation
342: of a new dialog for when the Print Setup button is clicked. The
343: source code in \C700\MFC\SRC\WINDLGS.CPP provides more documentation
344: on how to implement this feature.
345:
346:
347: CFindReplaceDialog
348: ==================
349: The CFindReplaceDialog class is a standard modeless dialog for implementing
350: a dialog that queries the user for a find/replace string pair. The
351: dialog is dual purpose in that it can display either a Find dialog
352: or a Find Replace dialog. This is a modeless dialog and is
353: derived from the CDialog class. You are responsible for implementing
354: code that does the actual search and replace, as this dialog only
355: receives input from the user. The relevant parameter block
356: structure is FINDREPLACE and the APIs used are FindText and
357: ReplaceText.
358:
359: Since this dialog is modeless, it should be dynamically allocated
360: using operator new. If you wish to allocate a CFindReplace dialog
361: on the stack frame, you will need to derive your own CFindReplaceDialog
362: and override the default behavior of the PostNcDestroy function.
363: The constructor for this class takes no arguments. When your application
364: needs to query the user for find/replace information the Create
365: member function is called. This will create and show the modeless
366: dialog. The parameters to Create are as follows:
367:
368: bFindDialogOnly TRUE for Find, FALSE for Find and Replace
369: lpszFindWhat the default search string, such as the
370: current selection
371: lpszReplaceWith the default replacement string
372: (defaults to NULL)
373: dwFlags is a set of flags that you can use to customize
374: the function and appearance of the dialog. See
375: the FINDREPLACE structure reference for more
376: information on possible values. (defaults to
377: FR_DOWN)
378: pParentWnd the parent of the dialog, this is the dialog
379: that receives the special message indicating
380: that a find/replace action is requested (defaults
381: to the current frame window, CWinApp::m_pMainWnd)
382:
383: In order for the pParentWnd to be notified of find/replace requests
384: you must use the Windows API ::RegisterMessage(FINDMSGSTRING). The
385: return value of this function is a message number that is unique to this
386: application instance. Your frame window should have a message map
387: entry that handles this registered message. The following code
388: fragments show how to do this for a frame window class CMyFrameWnd.
389:
390: class CMyFrameWnd : public CFrameWnd
391: {
392: // normal members
393:
394: protected:
395: // CFindReplaceDialog helpers
396: static CFindReplace* pFindReplace;
397: static UINT nMsgFind;
398: afx_msg LONG CmdFindHelper(UINT wParam, LONG lParam);
399:
400: DECLARE_MESSAGE_MAP()
401: };
402:
403: BEGIN_MESSAGE_MAP(CMyFrameWnd, CFrameWnd)
404: // normal message map entries
405: ON_REGISTERED_MESSAGE(nMsgFind, CmdFindHelper)
406: END_MESSAGE_MAP
407:
408: UINT CMyFrameWnd::nMsgFind = ::RegisterMessage(FINDMSGSTRING);
409: CFindReplace* CMyFrameWnd::pFindReplace = NULL;
410:
411: Note the use of a static member that is the current CFindReplaceDialog
412: object. When the user first executes the Find command, a dialog will
413: be created and that object will be used until the Close command on
414: the system menu is executed or the user clicks CANCEL.
415:
416: Within the CmdFindHelper you will interpret the intentions of the
417: user and do the work for find/replace. In order to assist you, there
418: are a number of helper functions available:
419:
420: GetFindString returns the current find string
421: SearchDown TRUE of the user wishes to search down
422: the document
423: FindNext TRUE if the user clicked the Find Next
424: button
425: MatchCase TRUE if the user wishes to match case
426: of text exactly
427: MatchWholeWord TRUE if the user wishes to match entire
428: words only
429: GetReplaceString returns the current replace string for
430: a replace dialog
431: ReplaceCurrent TRUE is the user requested that the current
432: word be replaced in a replace dialog
433: ReplaceAll TRUE if the user wishes all occurrences
434: to be replaced
435: IsTerminating TRUE is the dialog is terminating (the
436: current m_hWnd is no longer valid when this
437: function returns TRUE)
438: GetNotifier return the CFindReplaceDialog structure
439: (valid only in the CmdFindHandler callback
440: function)
441:
442: The CmdFindHandler upon being called will first use the static
443: member function of CFindReplaceDialog, GetNotifier, to convert
444: the lParam into a CFindReplaceDialog object pointer, which will
445: then be used to call member functions and extract dialog information.
446: If you derived your own CFindReplaceDialog, you will need to
447: provide a typesafe castdown static member function to safely convert
448: the lParam to your own derived CFileDialog.
449:
450: Normally the CmdFindHandler will then do a check to see if the
451: dialog is being terminated (using IsTerminating) and if this is
452: TRUE you will cleanup (delete the current pFindReplace dialog and
453: set the member variable to NULL) and possibly store away the
454: final find/replace text to be used in the initialization of the
455: next dialog.
456:
457: Although this dialog is a modeless dialog, as with other
458: CDialog derived modeless dialogs MFC automatically
459: handles the translation dialog messages and routes them to
460: your dialog's message map. Thus you are free to customize your
461: CFindReplaceDialog by deriving and supplying a message map with
462: the necessary handlers.
463:
464:
465: Advanced Usage Notes
466: ====================
467: Many of these dialogs permit the use of strings to customize
468: the appearance or functionality of the dialog. Whenever a
469: string is used, it is best to use a STRINGTABLE resource
470: rather than embedding the string in your code. The CString::LoadString
471: API can assist you in loading a string from a resource file.
472: Similarly, if the string is read-only, you could place it in
473: a code segment (use the MFC helper macro BASED_CODE.)
474:
475: The standard COMMDLG functions all permit the user to add special
476: "hook" functions in order to customize the dialog box appearance and
477: functionality. With MFC you should not use these special
478: hook procedures, but you should use a derived class and a message
479: just as you would for any other standard Windows dialog. If you
480: require the use of the hook function, be sure to save the MFC
481: hook function and call it if you do not handle a message, just
482: as when dynamically subclassing a Windows window.
483:
484: As with other short-lived objects, dialogs that derive from
485: the CModalDialog class are best allocated on the stack frame.
486: The CFindReplaceDialog class is designed to be heap allocated
487: (via operator new) since it is a long-lived object.
488:
489: All of these dialog classes have a parent window pointer as
490: a constructor parameter. The classes will all use the current
491: frame window (CWinApp::m_pMainWnd) as the parent if you
492: specify NULL as the pParentWnd parameter (the default.) If
493: you are spawning a standard dialog from another dialog, it
494: you must pass the current dialog as the the parent pointer
495: (the 'this' pointer in the command handler that spawns the
496: dialog. If you do not, the two dialogs will have sibling
497: relationship rather than a parent/child relationship.
498:
499: COMMDLG functions require significant stack space, so be
500: sure to have at least 16K of stack space available (use the
501: .DEF file to change the default.)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.