Introduction
There are several occasions when I have been programming an application, and have needed to have the user input a single line of text, for instance the name of a new object to create. To start with, I created a dialog template for each instance, with the correct title and controls. Then I realised that this was very wasteful in terms of code, resources and time. So I created a universal dialog template and class that would accept user input given a prompt and window title. However, since then, I have realised that even this is not ideal � every time you need to use that class, you have to copy the dialog resource to the new project, hence the CTextEntryDlg class, inspired by Chris Maunder�s progress window class, was born.
Usage
The class is extremely simple to use. First, in your .cpp file, add an #include directive as follows:
#include <TextEntryDlg.h>
Now, you need to create an instance of the class. This is simply done by declaring a variable of the type CTextEntryDlg, as follows:
CTextEntryDlg dlgTextEntry;
The next stage is to display the dialog. This is done by calling the Show(...) function. This has the following signature:
int Show(CWnd *pParent, LPCTSTR pszTitle, LPCTSTR pszPrompt,
LPCTSTR pszDefault = _T(""), bool bPassword = false)
In the pParent parameter, we pass a pointer to the parent window. This is to ensure the dialog�s modal loop works correct. The
pszTitle parameter should be set to a string that you would like for the title-bar of the window. The
pszPrompt parameter should be set to a string that you would like to use for the prompt, to be place in a static control positioned just above the edit control. The
pszDefault parameter is a string that should be used to begin with. If none is supplied, the edit box is empty when the dialog is created. If the
bPassword parameter is true, the edit box will be created with the ES_PASSWORD style.
When this function returns, you can determine whether the dialog was cancelled, and what string the user entered. Here are the possible return values:
|
0
|
The dialog was not successfully created.
|
|
IDOK
|
The dialog was dismissed with the OK button, or the user pressed ENTER
|
|
IDCANCEL
|
The dialog was dismissed with the Cancel button, or the user pressed ESCAPE
|
Once you have determined that the user clicked OK, you can obtain the string which was entered using the
GetText() function (the function will also return the correct string even if Cancel was selected). The
GetText() function returns a LPCTSTR for simplicity, but you can put this straight into a
CString if you like:
CString strResult = dlgTextExtry.GetText();
That�s basically all there is to it!
Under the Hood
The inner workings of the class are relatively simple. Basically, in the Show() function, the controls that make up the window are dynamically created. Important points to note here are the use of
CreateEx for the edit control, because otherwise it could not be created with a �client� edge, and the way in which the font is specifically set for each control.
The function then calls the private function DoModal(), which basically disables the parent window, and then calls
RunModalLoop(). The interaction with Windows from then on is purely message based. However, a further important point to notice is the additional code in
PreTranslateMessage. This exists to process escape and tab key-presses, and is lifted almost with change from
dlgcore.cpp in the MFC source files.
Conclusion
I hope you find this article and its accompanying source code useful, and if you have any questions, feel free to mail me (click on my name at the top of the page).
Updates
- January 27th, 2002
- Fixed problem with focus not returning to parent in WinME
- Fixed flicker problem in Windows 2000 and XP
- Corrected routine that calculates height of the dialog
