CStringEdit - An Edit Box With Validation and Status/Alert Display

• Download source files - 6 Kb
• Download demo project - 23 Kb

Introduction

I have often found that user input edit boxes on a dialog require much more than the capabilities provided by the basic CEdit control. A common problem I have encountered is the need for an edit control that restricts the characters that can be entered into the box in some manner. Some types of restrictions would include confining input to a specific set if legal characters, excluding characters in an illegal set, limiting text to a maximum length and providing for fixed length strings that may be padded to the right with spaces if they are too short.

Another issue that arises is the need to alternately display a status or prompt type string in an edit box under conditions where no user input has yet been specified. And then finally under the conditions where there is some type of error associated with a user entered value it is desireable to display an alert type error message in the edit box as opposed to using the proverbial MessageBeep or a popup error dialog.

I have implemented an editing control to address these needs. The picture above shows this CStringEdit control on the top area of the demo application. In normal edit mode the edit box will have a white background. When the edit box is switched to status mode the background will display in a yellow color. In a similar manner the alert message mode causes the alert text to be displayed on a red background. The design of this control permits the edit string, status string, and the alert string to be separately loaded into the control and then the modes can be changed via simple member function calls. The small demo application provides a test platform to exercise the edit control. In normal usage these controls would of course be programmably controlled via code included within the dialog class. The usage of the demo application becomes self evident once one is familair with the various interface routines to the CStringEdit control.

Application In Your Project

To be able to utilize this string edit control in your application requires four very easy steps:

• First you add the two source files StringEdit.h and StringEdit.cpp to your project.
• Next you design the control onto a dialog using the dialog design tool. Select the EDIT BOX control and place it on your dialog it the desired place.
• The next step is to use the ClassWizard to add a memember variable as a Control to the class definition for your dialog. In ClassWizard when you select the Add Variable command you will get a dialog box that should be set similar to that shown below:

  

• And finally after you close the ClassWizard you open the header file for your dialog class (the .h file) and edit two things into the file. Near the top type the the line shown below so that the compiler will know about the special control.

#include "StringEdit.h"

And then you locate the member variable declarations in this same header file in the part that is filled in by the ClassWizard. Locate the line for the CEdit control and change the type to CStringEdit as shown below:

From this :

// Dialog Data
  //{{AFX_DATA(CStringEditDemoDlg)
  enum { IDD = IDD_STRINGEDITDEMO_DIALOG };
  CEdit m_MyInputEdit;

To this :

// Dialog Data
  //{{AFX_DATA(CStringEditDemoDlg)
  enum { IDD = IDD_STRINGEDITDEMO_DIALOG };
  CStringEdit  m_MyInputEdit;

Usage Notes

The default constructor will configure the CStringEdit control to have behavior that matches that of CEdit except that you use the new member functions GetText() and SetText() to load the control. You may place other code in the OnInitDialog() handler in your dialog class to set the other behaviors that are special to the CStrinEdit class.

Some style attributes of the edit control can be set in the dialog design tool. Feel free to utilize any of the text alignment and framing options. CStringEdit should not however be used with the attributes or propertrties set that control to numeric mode or setting the maximum length of the input. The maximum length, if needed, should utilize the MaxLen property of the CStringEdit class.

The Interface

The interface to the class is provided through the use of the following member functions:

void SetFixedLen(BOOL bFixedLen)    // set fixed length flag
BOOL GetFixedLen(void)              // read back the fixed length flag

Fixed length mode for the control simply causes the string returned by the GetText() function to be padded to the right with spaces if the user entered text is shorter than the nMax value set for the control.

void SetMode(BOOL bMode)            // sets edit/status mode
BOOL GetMode(void)                  // reads back the mode flag

The control mode is primarily controlled to be in Edit Mode when the mode flag is set FALSE and to the yellow status display mode when the mode is set to the TRUE value.

void SetAlertActive(UINT nSeconds)     // start active alert mode 
void SetAlertInactive(void)            // End the alert mode 

The alert display mode, with the control in the red color is initiaited with the SetAlertActivate() function. The argument specifies the number of seconds that the control shall display the alert text. A value of zero makes the alert display stay on till disablesd. The SetAlertInactive() function ends a current alert display mode and returns the control to the mode set via the previous call to the SetMode() function.

void SetMaxLength(int nMax)     // method to set the maximum string length
int GetMaxLength(void)          // method to read back 
                                //the maximum string length

The MaxLength is set to limit the number of characters that can be entered into the control. A value of zero will let the text be any length.

void SetLegal(LPCSTR lpszLegal)      
    // sets the string of legal characters

void GetLegal(CString& strLegal)     // gets back the legal string

The legal string is a set of characters in a string that specify the valid entry characters for the edit control. If this string is empty then any characters are accepted as input (subject to those specified in the Illegal string).

void SetIllegal(LPCSTR lpszIllegal)    
    // sets the string of illegal characters

void GetIllegal(CString& strIllegal)   // gets back the illlegal string

The illegal string specifies those characters which are specifically disallowed in the edited string input. If this string is emppty then there are no illegal characters to look for.

void SetStatus(LPCSTR lpszStatus)      // set status string
void GetStatus(CString& strStatus)     // gets back the status string

These load and retreive the text string that is displayed in the status mode.

void SetAlert(LPCSTR lpszAlert)        // set alert string
void GetAlert(CString& strAlert)       // gets back the alert string

These load and retreive the text string that is displayed in the alert mode.

void SetText(LPCSTR lpszText)          // plug text into control  
void GetText(CString& strText)         // take text out of control

These are used to place edit mode text into and get it back from the control.