Filter Library

Camera

Interface Physics

ControlFilterEdit.h

/*
 * ControlFilterEdit.h - a filtered edit control.
 *
 * This file is part of the Camera Filter Library.
 * Computer Aided Measurement Environment for Realtime Atomic imaging (Camera)
 *
 * Copyright (C) 2004-2005, Leiden Probe Microscopy.
 * Copyright (C) 2004-2005, Universiteit Leiden.
 *
 * The filtered edit control is based on:
 * CFilterEdit: Use Regular Expressions to Filter Your Input, By Ben Hanson.
 * See http://www.codeproject.com/editctrl/FilterEdit.asp
 *
 * Authors: Martin J. Moene (original)
 *
 * $Id: ControlFilterEdit.h 202 2005-05-12 11:00:48Z moene $
 */

#ifndef CFL_CONTROLFILTEREDIT_H
#define CFL_CONTROLFILTEREDIT_H

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#include <afxwin.h>                     // for class CEdit

/**
 * \addtogroup cfl_controlnumedit Numeric Edit Control
 * \brief numeric edit control.
 *
 * This section contains various classes for numeric edit controls, currently:
 * - CFilterEdit
 * - CIntegerEdit
 * - CRealEdit
 *
 * The controls are used in dialog classes to:
 * - restrict what can be input
 * - set the control to a new value
 * - obtain the current value
 *
 * The controls may also be buddied with a \ref cfl_controlnumspincontrol. 
 * In that case the numeric edit control is used to only accept allowable input 
 * and the spin control is used to set and obtain the value.
 *
 * Note: do not check the <em>Set buddy integer</em> flag on the spin control.
 *
 * By using a control class we avoid direct access to the underlying windows dialog 
 * item via GetDlgItem. More about that can be read in <em>Avoiding GetDlgItem
 * in MFC</em> by Joseph M. Newcomer \ref newcomer_avoidgetdlgitem "[GETDLGITEM]".
 *
 * Another advantage of the numeric edit controls is that this makes it possible 
 * to do direct numeric access, like in:
 * \code
 * CIntegerEdit c_txtOffset;
 * c_txtOffset = -10;
 *
 * // and
 *
 * if ( c_txtOffset > 0 )
 *    ...
 * \endcode
 *
 * Here is how you may use a filtering edit control of type CIntegerEdit in a
 * dialog.
 *
 * \code
 * // mydialog.h - header
 *
 * class MyDialog
 * {
 * public:
 *    MyDialog( CWnd* pParent = NULL );
 *
 * protected:
 *    virtual void DoDataExchange( CDataExchange* pDX );
 *
 *    //{{AFX_MSG(MyDialog)
 *    virtual BOOL OnInitDialog();
 *    afx_msg void OnChangeOffset();
 *    //}}AFX_MSG
 *    DECLARE_MESSAGE_MAP()
 *
 * private:
 *    CIntegerEdit c_txtOffset;
 *    bool         initialized;
 * };
 *
 * \endcode
 *
 * Please note the member variable \c initialized. Under some circumestances
 * messages start coming, while not all controls are fully initialized and
 * messages should not be handled yet. This happens for example when you
 * auto-buddy an edit control with a spin control.
 * (See also \ref newcomer_avoidgetdlgitem "[GETDLGITEM]".)
 *
 * \code
 * // mydialog.cpp - implementation
 *
 * MyDialog::MyDialog( CWnd* pParent ) :
 *    c_txtOffset( true   ),  // signed
 *    initialized( false  )   // don't handle messages yet; see OnInitDialog()
 * {
 *    //{{AFX_DATA_INIT(MyDialog)
 *    //}}AFX_DATA_INIT
 * }
 *
 * void MyDialog::DoDataExchange( CDataExchange* pDX )
 * {
 *    CDialog::DoDataExchange(pDX);
 *    //{{AFX_DATA_MAP(MyDialog)
 *    DDX_Control(pDX, IDC_MYDIALOG_OFFSET, c_txtOffset );
 *    //}}AFX_DATA_MAP
 * }
 *
 * BEGIN_MESSAGE_MAP( MyDialog )
 *    //{{AFX_MSG_MAP(MyDialog)
 *    ON_EN_CHANGE( IDC_MYDIALOG_OFFSET, OnChangeOffset )
 *    //}}AFX_MSG_MAP
 * END_MESSAGE_MAP()
 *
 * BOOL MyDialog::OnInitDialog()
 * {
 *    CFilterDlg::OnInitDialog();
 *
 *    c_txtOffset = 0;     // initialize offset value
 *
 *    UpdateData(FALSE);   // transfer data from variables to controls
 *
 *    initialized = true;  // dialog initialized
 *
 *    return TRUE;         // we set the focus
 * }
 *
 * // for example, ensure odd value:
 *
 * void MyDialog::OnChangeOffset()
 * {
 *    if ( !initialized )
 *       return ;
 *
 *    if ( 0 == c_txtOffset % 2 )
 *       c_txtOffset = c_txtOffset + 1;
 * }
 * \endcode
 *
 * Note that the handler OnChangeOffset() is not required to obtain the
 * filtering property, that is handled via DoDataExchange().
 *
 * @{
 */

DECLARE_CLASS( CFilterEdit );           // declare various types for class

/**
 * a base class for filtering edit classes.
 *
 * CFilterEdit is the base class for edit fields that can filter their input.
 * This can be used to limit the input to data that is valid in a certian
 * context, for example only positive integer numbers.
 *
 * Base class CFilterEdit lets you specify several ascpects of its behaviour:
 * - validate as the user types (also settable in the constructor), SetProcessChars()
 * - check that the entire input is valid when the control loses focus; set
 *   focus back to the control if the input is invalid when the control loses
 *   focus, SetAutoValidate()
 * - show invalid input visually: set the background color to a specified color
 *   if the input is invalid, draw a wavy line under the text if the input is
 *   invalid, SetShowInvalid()
 * - set the error colors, SetBackgroundColourError(), SetForegroundColourError()
 * - set the normal ('OK') colors, SetForegroundColourOK(), SetBackgroundColourOK()
 * - beep, if, when a final validation is performed, the validation fails, SetBeepOnInvalid()
 *
 * To implement the checking behaviour, do the following.
 * - derive your class publicly from CFilterEdit
 * - implement methods Check() and Match()
 *
 * Note: CFilterEdit can also be used by itself solely with the purpose to create
 * a colored edit field.
 *
 * Make sure that the control is included in method DoDataExchange() of the 
 * dialog classes where you use the edit control.
 *
 * Class CFilterEdit is a modification of the class CFilterEdit by Ben Hanson
 * \ref hanson_filteredit "[FILTEREDIT]" in that the regular expression pattern 
 * matching \ref hanson_regexp "[REGEXP]" is replaced by a simple lexical scanner
 * \ref dragon_1986 "[Aho et al.]".
 *
 * Another interesting article is: A Validating Edit Control by Joseph M. 
 * Newcomer \ref newcomer_valedtctl "[VALEDTCTL]". This article describes the
 * use of a tooltip to indicate the reason the contents of an edit control is
 * invalid.
 *
 * The following example shows an edit field that limits its input to signed
 * integer numbers in octal, decimal or hexadecimal notation.
 *
 * The interface.
 * \code
 * // ControlOctDecHexEdit.h - class declaration.
 *
 * #ifndef CFL_CONTROLOCTDECHEXEDIT_H
 * #define CFL_CONTROLOCTDECHEXEDIT_H
 *
 * #if _MSC_VER > 1000
 * #pragma once
 * #endif // _MSC_VER > 1000
 *
 * #include <cfl/ControlFilterEdit.h>      // for base class CFilterEdit
 *
 * //
 * // COctDecHexEdit
 * //
 *
 * class COctDecHexEdit : public CFilterEdit
 * {
 * public:
 *    ~COctDecHexEdit();
 *    COctDecHexEdit( bool bSigned = true );
 *
 * protected:
 *    bool Check( const CString &csText );
 *    bool Match( const CString &csText );
 *
 * private:
 *    bool m_bSigned;
 * };
 *
 * //
 * // destructor.
 * //
 *
 * inline COctDecHexEdit::~COctDecHexEdit()
 * {
 *    ; // do nothing
 * }
 *
 * //
 * // destructor.
 * //
 *
 * inline COctDecHexEdit::COctDecHexEdit( bool bSigned ) :
 *    CFilterEdit(), m_bSigned( bSigned )
 * {
 *    ; // do nothing
 * }
 *
 * #endif // CFL_CONTROLOCTDECHEXEDIT_H
 *
 * \endcode
 *
 * The implementation.
 * \code
 * // ControlOctDecHexEdit.cpp - class implementation.
 *
 * #include "stdafx.h"                     // for common (pre-compiled) headers
 * #include <cfl/ControlOctDecHexEdit.h>   // header
 *
 * //
 * // true if input is complete and valid.
 * //
 *
 * bool COctDecHexEdit::Check( const CString &csText )
 * {
 *    TCHAR* ePtr;
 *
 *    // let strtol() determine the base:
 *    (void) _tcstol( csText, &ePtr, 0 );
 *
 *    // ok if all characters are used for conversion
 *    return _TCHAR('\0') == *ePtr;
 * }
 *
 * //
 * // true if (partial) input valid.
 * //
 *
 * //      number : sign? ( octal | decimal | hexadecimal )
 * //        sign : [+-]
 * //       octal : "0" [0-7]+
 * //     decimal : [1-9][0-9]*
 * // hexadecimal : "0" [xX] [0-9a-fA-F]+
 * //
 *
 * bool COctDecHexEdit::Match( const CString &csText )
 * {
 *    int base = 10;
 *
 *    const TCHAR* cPtr = csText;
 *
 *    // optional sign?
 *
 *    if ( _TCHAR('+') == *cPtr || ( m_bSigned && _TCHAR('-') == *cPtr ) )
 *       ++cPtr;
 *
 *    // leading octal/hexadecimal 0?
 *
 *    if ( _TCHAR('0') == *cPtr )
 *    {
 *       ++cPtr;
 *       base = 8;
 *    }
 *
 *    // leading hexadecimal 0x, 0X?
 *
 *    if ( 8 == base && ( _TCHAR('x') == *cPtr || _TCHAR('X') == *cPtr ) )
 *    {
 *       ++cPtr;
 *       base = 16;
 *    }
 *
 *    // scan remaining digits:
 *
 *    if ( 8 == base )
 *    {
 *       while ( *cPtr && _TCHAR('0') <= *cPtr && *cPtr <= _TCHAR('7') )
 *         ++cPtr;
 *    }
 *    else if ( 10 == base )
 *    {
 *       while ( *cPtr && _istdigit( *cPtr ) )
 *         ++cPtr;
 *    }
 *    else if ( 16 == base )
 *    {
 *       while ( *cPtr && _istxdigit( *cPtr ) )
 *         ++cPtr;
 *    }
 *
 *    // ok if all characters matched:
 *    return cPtr == (const TCHAR*) csText + csText.GetLength();
 * }
 * \endcode
 */

class CFilterEdit : public CEdit
{
   typedef CFilterEdit self;            ///< this type

   DECLARE_DYNAMIC( CFilterEdit )

public:
   ///
   /// \name Construction
   /// @{

   virtual ~CFilterEdit ();
   CFilterEdit ( const bool bProcessChars = true );

   /// @}
   /// \name Predicates
   /// @{

   bool    IsValidChar ();
   bool    IsValidInput ();

   /// @}
   /// \name Accessors
   /// @{

   // Read this to further process text from derived class
   const   CString &GetProposedText () const;

   /// @}
   /// \name Mutators
   /// @{

   void    SetProcessChars         ( const bool bProcessChars );
   void    SetAutoValidate         ( const bool bAutoValidate, const bool bModal );
   void    SetShowInvalid          ( const bool bShowInvalid, const bool bSetBkOnError, const bool bWavyLineOnError );
   void    SetBeepOnInvalid        ( const bool bBeepOnInvalid );

   void    SetBackgroundColourOK   ( const COLORREF crBkOK   );
   void    SetForegroundColourOK   ( const COLORREF crFgOK    );
   void    SetBackgroundColourError( const COLORREF crBkError );
   void    SetForegroundColourError( const COLORREF crFgError );

   void    Select();

   // @}

protected:
   bool            ValidateChar( UINT nChar );
   void            ResetValid  ( );

   virtual bool    Check( const CString &csText );
   virtual bool    Match( const CString &csText );

   virtual LRESULT WindowProc ( UINT message, WPARAM wParam, LPARAM lParam );

   DECLARE_MESSAGE_MAP ()

   //
   // \name Message Handlers
   // @{

   afx_msg void    OnChar     ( UINT nChar, UINT nRepCnt, UINT nFlags );
   afx_msg void    OnKeyDown  ( UINT nChar, UINT nRepCnt, UINT nFlags );
   afx_msg void    OnKeyUp    ( UINT nChar, UINT nRepCnt, UINT nFlags );
   afx_msg HBRUSH  CtlColor   ( CDC *pDC, UINT /*nCtlColor*/ );
   afx_msg void    OnSetFocus ( CWnd *pOldWnd );
   afx_msg void    OnKillFocus( CWnd *pNewWnd );
   afx_msg void    OnPaint    ( );

   // @}

private:
   bool CanDelete();                    ///< handle cut, Ctrl+X
   bool CanPaste ();                    ///< handle paste, Ctrl+V

   CFilterEdit( CFilterEdit const&   ); ///< prevent copy-assignment construction
   self& operator=(CFilterEdit const&); ///< prevent assignment

private:
   // Set this to false to call CEdit::OnChar in derived class
   //   unsigned int m_uiMaxChars;
   bool m_bProcessChars;                ///< validate characters while typing (flag)

   // These two flags go together
   bool m_bAutoValidate;                ///< (flag)
   bool m_bModal;                       ///< (flag)

   // These three flags go together
   bool m_bShowInvalid;                 ///< indicate invalid input (flag)
   bool m_bSetBkOnError;                ///< change background color for invalid input (flag)
   bool m_bWavyLineOnError;             ///< draw wavy line if input is invalid (flag)

   bool m_bBeepOnInvalid;               ///< beep if input is invalid (flag)

   // Does the text completely match the regex
   bool m_bValid;                       ///< input is valid (flag)
   // Set to true or false each time a char is typed
   // (read from derived class
   bool m_bCharValid;                   ///< current character is valid (flag)
   // Latest proposed string (can be read by a derived class)
   CString m_strProposedText;           ///< current valid text

   bool m_bControlDown;                 ///< control key is down (flag)

   COLORREF m_crFgOK;                   ///< ok foreground color
   COLORREF m_crBkOK;                   ///< ok background color
   COLORREF m_crFgError;                ///< error foreground color
   COLORREF m_crBkError;                ///< error background color
   CBrush   m_brOK;                     ///< ok brush
   CBrush   m_brError;                  ///< error brush
};

/// @} cfl_controlnumedit

/**
 * focus the control and select it content.
 */

inline void CFilterEdit::Select()
{
   SetFocus(       );
   SetSel  ( 0, -1 );
}

#endif // CFL_CONTROLFILTEREDIT_H

/*
 * end of file
 */

---