A Ready Made Text Entry Dialog

• Download source files - 3 Kb
• Download demo project - 20 Kb

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