CEdit Class
Provides the functionality of a Windows edit control.
class CEdit : public CWnd
Name | Description |
---|---|
CEdit::CEdit | Constructs a CEdit control object. |
Name | Description |
---|---|
CEdit::CanUndo | Determines whether an edit-control operation can be undone. |
CEdit::CharFromPos | Retrieves the line and character indexes for the character closest to a specified position. |
CEdit::Clear | Deletes (clears) the current selection (if any) in the edit control. |
CEdit::Copy | Copies the current selection (if any) in the edit control to the Clipboard in CF_TEXT format. |
CEdit::Create | Creates the Windows edit control and attaches it to the CEdit object. |
CEdit::Cut | Deletes (cuts) the current selection (if any) in the edit control and copies the deleted text to the Clipboard in CF_TEXT format. |
CEdit::EmptyUndoBuffer | Resets (clears) the undo flag of an edit control. |
CEdit::FmtLines | Sets the inclusion of soft line-break characters on or off within a multiple-line edit control. |
CEdit::GetCueBanner | Retrieves the text that is displayed as the text cue, or tip, in an edit control when the control is empty and does not have focus. |
CEdit::GetFirstVisibleLine | Determines the topmost visible line in an edit control. |
CEdit::GetHandle | Retrieves a handle to the memory that is currently allocated for a multiple-line edit control. |
CEdit::GetHighlight | Gets the indexes of the starting and ending characters in a range of text that is highlighted in the current edit control. |
CEdit::GetLimitText | Gets the maximum amount of text this CEdit can contain. |
CEdit::GetLine | Retrieves a line of text from an edit control. |
CEdit::GetLineCount | Retrieves the number of lines in a multiple-line edit control. |
CEdit::GetMargins | Gets the left and right margins for this CEdit . |
CEdit::GetModify | Determines whether the contents of an edit control have been modified. |
CEdit::GetPasswordChar | Retrieves the password character displayed in an edit control when the user enters text. |
CEdit::GetRect | Gets the formatting rectangle of an edit control. |
CEdit::GetSel | Gets the first and last character positions of the current selection in an edit control. |
CEdit::HideBalloonTip | Hides any balloon tip associated with the current edit control. |
CEdit::LimitText | Limits the length of the text that the user can enter into an edit control. |
CEdit::LineFromChar | Retrieves the line number of the line that contains the specified character index. |
CEdit::LineIndex | Retrieves the character index of a line within a multiple-line edit control. |
CEdit::LineLength | Retrieves the length of a line in an edit control. |
CEdit::LineScroll | Scrolls the text of a multiple-line edit control. |
CEdit::Paste | Inserts the data from the Clipboard into the edit control at the current cursor position. Data is inserted only if the Clipboard contains data in CF_TEXT format. |
CEdit::PosFromChar | Retrieves the coordinates of the upper-left corner of a specified character index. |
CEdit::ReplaceSel | Replaces the current selection in an edit control with the specified text. |
CEdit::SetCueBanner | Sets the text that is displayed as the text cue, or tip, in an edit control when the control is empty and does not have focus. |
CEdit::SetHandle | Sets the handle to the local memory that will be used by a multiple-line edit control. |
CEdit::SetHighlight | Highlights a range of text that is displayed in the current edit control. |
CEdit::SetLimitText | Sets the maximum amount of text this CEdit can contain. |
CEdit::SetMargins | Sets the left and right margins for this CEdit . |
CEdit::SetModify | Sets or clears the modification flag for an edit control. |
CEdit::SetPasswordChar | Sets or removes a password character displayed in an edit control when the user enters text. |
CEdit::SetReadOnly | Sets the read-only state of an edit control. |
CEdit::SetRect | Sets the formatting rectangle of a multiple-line edit control and updates the control. |
CEdit::SetRectNP | Sets the formatting rectangle of a multiple-line edit control without redrawing the control window. |
CEdit::SetSel | Selects a range of characters in an edit control. |
CEdit::SetTabStops | Sets the tab stops in a multiple-line edit control. |
CEdit::ShowBalloonTip | Displays a balloon tip that is associated with the current edit control. |
CEdit::Undo | Reverses the last edit-control operation. |
An edit control is a rectangular child window in which the user can enter text.
You can create an edit control either from a dialog template or directly in your code. In both cases, first call the constructor CEdit
to construct the CEdit
object, then call the Create member function to create the Windows edit control and attach it to the CEdit
object.
Construction can be a one-step process in a class derived from CEdit
. Write a constructor for the derived class and call Create
from within the constructor.
CEdit
inherits significant functionality from CWnd
. To set and retrieve text from a CEdit
object, use the CWnd
member functions SetWindowText and GetWindowText, which set or get the entire contents of an edit control, even if it is a multiline control. Text lines in a multiline control are separated by '\r\n' character sequences. Also, if an edit control is multiline, get and set part of the control's text by calling the CEdit
member functions GetLine, SetSel, GetSel, and ReplaceSel.
If you want to handle Windows notification messages sent by an edit control to its parent (usually a class derived from CDialog
), add a message-map entry and message-handler member function to the parent class for each message.
Each message-map entry takes the following form:
ON_NOTIFICATION( id, memberFxn )
where id
specifies the child window ID of the edit control sending the notification, and memberFxn
is the name of the parent member function you have written to handle the notification.
The parent's function prototype is as follows:
afx_msg void memberFxn ( );
Following is a list of potential message-map entries and a description of the cases in which they would be sent to the parent:
ON_EN_CHANGE The user has taken an action that may have altered text in an edit control. Unlike the EN_UPDATE notification message, this notification message is sent after Windows updates the display.
ON_EN_ERRSPACE The edit control cannot allocate enough memory to meet a specific request.
ON_EN_HSCROLL The user clicks an edit control's horizontal scroll bar. The parent window is notified before the screen is updated.
ON_EN_KILLFOCUS The edit control loses the input focus.
ON_EN_MAXTEXT The current insertion has exceeded the specified number of characters for the edit control and has been truncated. Also sent when an edit control does not have the ES_AUTOHSCROLL style and the number of characters to be inserted would exceed the width of the edit control. Also sent when an edit control does not have the ES_AUTOVSCROLL style and the total number of lines resulting from a text insertion would exceed the height of the edit control.
ON_EN_SETFOCUS Sent when an edit control receives the input focus.
ON_EN_UPDATE The edit control is about to display altered text. Sent after the control has formatted the text but before it screens the text so that the window size can be altered, if necessary.
ON_EN_VSCROLL The user clicks an edit control's vertical scroll bar. The parent window is notified before the screen is updated.
If you create a CEdit
object within a dialog box, the CEdit
object is automatically destroyed when the user closes the dialog box.
If you create a CEdit
object from a dialog resource using the dialog editor, the CEdit
object is automatically destroyed when the user closes the dialog box.
If you create a CEdit
object within a window, you may also need to destroy it. If you create the CEdit
object on the stack, it is destroyed automatically. If you create the CEdit
object on the heap by using the new
function, you must call delete
on the object to destroy it when the user terminates the Windows edit control. If you allocate any memory in the CEdit
object, override the CEdit
destructor to dispose of the allocations.
To modify certain styles in an edit control (such as ES_READONLY) you must send specific messages to the control instead of using ModifyStyle. See Edit Control Styles in the Windows SDK.
For more information on CEdit
, see Controls.
CEdit
Header: afxwin.h
Call this function to determine if the last edit operation can be undone.
BOOL CanUndo() const;
Nonzero if the last edit operation can be undone by a call to the Undo
member function; 0 if it cannot be undone.
For more information, see EM_CANUNDO in the Windows SDK.
See the example for CEdit::Undo.
Constructs a CEdit
object.
CEdit();
Use Create to construct the Windows edit control.
// Declare a local CEdit object.
CEdit myEdit;
// Declare a dynamic CEdit object.
CEdit *pmyEdit = new CEdit;
Call this function to retrieve the zero-based line and character indices of the character nearest the specified point in this CEdit
control
int CharFromPos(CPoint pt) const;
pt
The coordinates of a point in the client area of this CEdit
object.
The character index in the low-order WORD, and the line index in the high-order WORD.
Note
This member function is available beginning with Windows 95 and Windows NT 4.0.
For more information, see EM_CHARFROMPOS in the Windows SDK.
// CMyEdit inherits from CEdit
void CMyEdit::OnLButtonDown(UINT nFlags, CPoint point)
{
int n = CharFromPos(point);
int nLineIndex = HIWORD(n);
int nCharIndex = LOWORD(n);
TRACE(_T("nLineIndex = %d, nCharIndex = %d\r\n"), nLineIndex, nCharIndex);
CEdit::OnLButtonDown(nFlags, point);
}
Call this function to delete (clear) the current selection (if any) in the edit control.
void Clear();
The deletion performed by Clear
can be undone by calling the Undo member function.
To delete the current selection and place the deleted contents into the Clipboard, call the Cut member function.
For more information, see WM_CLEAR in the Windows SDK.
// Delete all of the text.
m_myEdit.SetSel(0, -1);
m_myEdit.Clear();
Call this function to coy the current selection (if any) in the edit control to the Clipboard in CF_TEXT format.
void Copy();
For more information, see WM_COPY in the Windows SDK.
// Copy all of the text to the clipboard.
m_myEdit.SetSel(0, -1);
m_myEdit.Copy();
Creates the Windows edit control and attaches it to the CEdit
object.
virtual BOOL Create(
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
dwStyle
Specifies the edit control's style. Apply any combination of edit styles to the control.
rect
Specifies the edit control's size and position. Can be a CRect
object or RECT
structure.
pParentWnd
Specifies the edit control's parent window (usually a CDialog
). It must not be NULL.
nID
Specifies the edit control's ID.
Nonzero if initialization is successful; otherwise 0.
You construct a CEdit
object in two steps. First, call the CEdit
constructor and then call Create
, which creates the Windows edit control and attaches it to the CEdit
object.
When Create
executes, Windows sends the WM_NCCREATE, WM_NCCALCSIZE, WM_CREATE, and WM_GETMINMAXINFO messages to the edit control.
These messages are handled by default by the OnNcCreate, OnNcCalcSize, OnCreate, and OnGetMinMaxInfo member functions in the CWnd
base class. To extend the default message handling, derive a class from CEdit
, add a message map to the new class, and override the above message-handler member functions. Override OnCreate
, for example, to perform needed initialization for the new class.
Apply the following window styles to an edit control.
WS_CHILD Always
WS_VISIBLE Usually
WS_DISABLED Rarely
WS_GROUP To group controls
WS_TABSTOP To include edit control in the tabbing order
// dynamically create an edit control
CEdit *pEdit = new CEdit;
pEdit->Create(ES_MULTILINE | WS_CHILD | WS_VISIBLE | WS_TABSTOP | WS_BORDER,
CRect(10, 10, 100, 100), this, 1);
Call this function to delete (cut) the current selection (if any) in the edit control and copy the deleted text to the Clipboard in CF_TEXT format.
void Cut();
The deletion performed by Cut
can be undone by calling the Undo member function.
To delete the current selection without placing the deleted text into the Clipboard, call the Clear member function.
For more information, see WM_CUT in the Windows SDK.
// Delete all of the text and copy it to the clipboard.
m_myEdit.SetSel(0, -1);
m_myEdit.Cut();
Call this function to reset (clear) the undo flag of an edit control.
void EmptyUndoBuffer();
The edit control will now be unable to undo the last operation. The undo flag is set whenever an operation within the edit control can be undone.
The undo flag is automatically cleared whenever the SetWindowText or SetHandleCWnd
member functions are called.
For more information, see EM_EMPTYUNDOBUFFER in the Windows SDK.
// Clear the undo buffer.
if (m_myEdit.CanUndo())
{
m_myEdit.EmptyUndoBuffer();
ASSERT(!m_myEdit.CanUndo());
}
Call this function to set the inclusion of soft line-break characters on or off within a multiple-line edit control.
BOOL FmtLines(BOOL bAddEOL);
bAddEOL
Specifies whether soft line-break characters are to be inserted. A value of TRUE inserts the characters; a value of FALSE removes them.
Nonzero if any formatting occurs; otherwise 0.
A soft line break consists of two carriage returns and a line feed inserted at the end of a line that is broken because of word wrapping. A hard line break consists of one carriage return and a line feed. Lines that end with a hard line break are not affected by FmtLines
.
Windows will only respond if the CEdit
object is a multiple-line edit control.
FmtLines
only affects the buffer returned by GetHandle and the text returned by WM_GETTEXT. It has no impact on the display of the text within the edit control.
For more information, see EM_FMTLINES in the Windows SDK.
CString strText;
// Add soft line-break breaks.
m_myEdit.FmtLines(TRUE);
// Dump the text of the edit control.
m_myEdit.GetWindowText(strText);
AFXDUMP(strText);
// Remove soft line-break breaks.
m_myEdit.FmtLines(FALSE);
Retrieves the text that is displayed as the text cue, or tip, in an edit control when the control is empty.
BOOL GetCueBanner(
LPWSTR lpszText,
int cchText) const;
CString GetCueBanner() const;
lpszText
[out] A pointer to a string that contains the cue text.
cchText
[in] The number of characters that can be received. This number includes the terminating NULL character.
For the first overload, TRUE if the method is successful; otherwise FALSE.
For the second overload, a CString that contains the cue text if the method is successful; otherwise, the empty string ("").
This method sends the EM_GETCUEBANNER message, which is described in the Windows SDK. For more information, see the Edit_GetCueBannerText macro.
Call this function to determine the topmost visible line in an edit control.
int GetFirstVisibleLine() const;
The zero-based index of the topmost visible line. For single-line edit controls, the return value is 0.
For more information, see EM_GETFIRSTVISIBLELINE in the Windows SDK.
int nFirstVisible = m_myEdit.GetFirstVisibleLine();
// Scroll the edit control so that the first visible line
// is the first line of text.
if (nFirstVisible > 0)
{
m_myEdit.LineScroll(-nFirstVisible, 0);
}
Call this function to retrieve a handle to the memory currently allocated for a multiple-line edit control.
HLOCAL GetHandle() const;
A local memory handle that identifies the buffer holding the contents of the edit control. If an error occurs, such as sending the message to a single-line edit control, the return value is 0.
The handle is a local memory handle and may be used by any of the Local Windows memory functions that take a local memory handle as a parameter.
GetHandle
is processed only by multiple-line edit controls.
Call GetHandle
for a multiple-line edit control in a dialog box only if the dialog box was created with the DS_LOCALEDIT style flag set. If the DS_LOCALEDIT style is not set, you will still get a nonzero return value, but you will not be able to use the returned value.
Note
GetHandle
will not work with Windows 95/98. If you call GetHandle
in Windows 95/98, it will return NULL. GetHandle
will work as documented under Windows NT, versions 3.51 and later.
For more information, see EM_GETHANDLE in the Windows SDK.
HLOCAL h = m_myEdit.GetHandle();
LPCTSTR lpszText = (LPCTSTR)::LocalLock(h);
// Dump the text of the edit control.
AFXDUMP(lpszText);
::LocalUnlock(h);
Gets the indexes of the first and last characters in a range of text that is highlighted in the current edit control.
BOOL GetHighlight(
int* pichStart,
int* pichEnd) const;
pichStart
[out] Zero-based index of the first character in the range of text that is highlighted.
pichEnd
[out] Zero-based index of the last character in the range of text that is highlighted.
TRUE if this method is successful; otherwise, FALSE.
This method sends the EM_GETHILITE message, which is described in the Windows SDK. Both SetHighlight
and GetHighlight
are currently enabled for UNICODE builds only.
Call this member function to get the text limit for this CEdit
object.
UINT GetLimitText() const;
The current text limit, in TCHARs, for this CEdit
object.
The text limit is the maximum amount of text, in TCHARs, that the edit control can accept.
Note
This member function is available beginning with Windows 95 and Windows NT 4.0.
For more information, see EM_GETLIMITTEXT in the Windows SDK.
CString strText(_T("I'm an edit control!"));
UINT nLength = strText.GetLength() * sizeof(TCHAR);
// Want the text limit to be at least the size of the new string.
if (m_myEdit.GetLimitText() < nLength)
m_myEdit.SetLimitText(nLength);
m_myEdit.SetWindowText(strText);
Call this function to retrieve a line of text from an edit control and places it in lpszBuffer.
int GetLine(
int nIndex,
LPTSTR lpszBuffer) const;
int GetLine(
int nIndex,
LPTSTR lpszBuffer,
int nMaxLength) const;
nIndex
Specifies the line number to retrieve from a multiple-line edit control. Line numbers are zero-based; a value of 0 specifies the first line. This parameter is ignored by a single-line edit control.
lpszBuffer
Points to the buffer that receives a copy of the line. The first word of the buffer must specify the maximum number of TCHARs that can be copied to the buffer.
nMaxLength
Specifies the maximum number of TCHAR characters that can be copied to the buffer. GetLine
places this value in the first word of lpszBuffer before making the call to Windows.
The number of characters actually copied. The return value is 0 if the line number specified by nIndex is greater than the number of lines in the edit control.
The copied line does not contain a null-termination character.
For more information, see EM_GETLINE in the Windows SDK.
See the example for CEdit::GetLineCount.
Call this function to retrieve the number of lines in a multiple-line edit control.
int GetLineCount() const;
An integer containing the number of lines in the multiple-line edit control. If no text has been entered into the edit control, the return value is 1.
GetLineCount
is only processed by multiple-line edit controls.
For more information, see EM_GETLINECOUNT in the Windows SDK.
int i, nLineCount = m_myEdit.GetLineCount();
CString strText, strLine;
// Dump every line of text of the edit control.
for (i = 0; i < nLineCount; i++)
{
// length of line i:
int len = m_myEdit.LineLength(m_myEdit.LineIndex(i));
m_myEdit.GetLine(i, strText.GetBuffer(len), len);
strText.ReleaseBuffer(len);
strLine.Format(_T("line %d: '%s'\n"), i, strText);
AFXDUMP(strLine);
}
Call this member function to retrieve the left and right margins of this edit control.
DWORD GetMargins() const;
The width of the left margin in the low-order WORD and the width of the right margin in the high-order WORD.
Margins are measured in pixels.
Note
This member function is available beginning with Windows 95 and Windows NT 4.0.
For more information, see EM_GETMARGINS in the Windows SDK.
See the example for CEditView::GetEditCtrl.
Call this function to determine whether the contents of an edit control have been modified.
BOOL GetModify() const;
Nonzero if the edit-control contents have been modified; 0 if they have remained unchanged.
Windows maintains an internal flag indicating whether the contents of the edit control have been changed. This flag is cleared when the edit control is first created and may also be cleared by calling the SetModify member function.
For more information, see EM_GETMODIFY in the Windows SDK.
// Reset the modified state only if my edit has been modified.
if (m_myEdit.GetModify())
m_myEdit.SetModify(FALSE);
Call this function to retrieve the password character that is displayed in an edit control when the user enters text.
TCHAR GetPasswordChar() const;
Specifies the character to be displayed instead of the character that the user typed. The return value is NULL if no password character exists.
If you create the edit control with the ES_PASSWORD style, the DLL that supports the control determines the default password character. The manifest or the InitCommonControlsEx method determines which DLL supports the edit control. If user32.dll supports the edit control, the default password character is ASTERISK ('*', U+002A). If comctl32.dll version 6 supports the edit control, the default character is BLACK CIRCLE ('●', U+25CF). For more information about which DLL and version supports the common controls, see Shell and Common Controls Versions.
This method sends the EM_GETPASSWORDCHAR message, which is described in the Windows SDK.
// Turn on the password mode.
m_myEdit.SetPasswordChar('*');
ASSERT(m_myEdit.GetStyle() & ES_PASSWORD);
ASSERT(m_myEdit.GetPasswordChar() == '*');
Call this function to get the formatting rectangle of an edit control.
void GetRect(LPRECT lpRect) const;
lpRect
Points to the RECT
structure that receives the formatting rectangle.
The formatting rectangle is the limiting rectangle of the text, which is independent of the size of the edit-control window.
The formatting rectangle of a multiple-line edit control can be modified by the SetRect and SetRectNP member functions.
For more information, see EM_GETRECT in the Windows SDK.
See the example for CEdit::LimitText.
Call this function to get the starting and ending character positions of the current selection (if any) in an edit control, using either the return value or the parameters.
DWORD GetSel() const;
void GetSel(
int& nStartChar,
int& nEndChar) const;
nStartChar
Reference to an integer that will receive the position of the first character in the current selection.
nEndChar
Reference to an integer that will receive the position of the first nonselected character past the end of the current selection.
The version that returns a DWORD returns a value that contains the starting position in the low-order word and the position of the first nonselected character after the end of the selection in the high-order word.
For more information, see EM_GETSEL in the Windows SDK.
// Set the selection to be all characters after the current selection.
DWORD dwSel = m_myEdit.GetSel();
m_myEdit.SetSel(HIWORD(dwSel), -1);
Hides any balloon tip associated with the current edit control.
BOOL HideBalloonTip();
TRUE if this method is successful; otherwise, FALSE.
This function sends the EM_HIDEBALLOONTIP message, which is described in the Windows SDK.
Call this function to limit the length of the text that the user may enter into an edit control.
void LimitText(int nChars = 0);
nChars
Specifies the length (in TCHARs) of the text that the user can enter. If this parameter is 0, the text length is set to UINT_MAX bytes. This is the default behavior.
Changing the text limit restricts only the text the user can enter. It has no effect on any text already in the edit control, nor does it affect the length of the text copied to the edit control by the SetWindowText member function in CWnd
. If an application uses the SetWindowText
function to place more text into an edit control than is specified in the call to LimitText
, the user can delete any of the text within the edit control. However, the text limit will prevent the user from replacing the existing text with new text, unless deleting the current selection causes the text to fall below the text limit.
Note
In Win32 (Windows NT and Windows 95/98), SetLimitText replaces this function.
For more information, see EM_LIMITTEXT in the Windows SDK.
// Limit the number of characters to be the maximum number visible.
// Get the text metrics for the edit; needed for the
// average character width.
TEXTMETRIC tm;
CDC *pDC = m_myEdit.GetDC();
pDC->GetTextMetrics(&tm);
m_myEdit.ReleaseDC(pDC);
CRect r;
m_myEdit.GetRect(&r);
m_myEdit.LimitText(r.Width() / tm.tmAveCharWidth);
Call this function to retrieve the line number of the line that contains the specified character index.
int LineFromChar(int nIndex = -1) const;
nIndex
Contains the zero-based index value for the desired character in the text of the edit control, or contains -1. If nIndex is -1, it specifies the current line, that is, the line that contains the caret.
The zero-based line number of the line containing the character index specified by nIndex. If nIndex is -1, the number of the line that contains the first character of the selection is returned. If there is no selection, the current line number is returned.
A character index is the number of characters from the beginning of the edit control.
This member function is only used by multiple-line edit controls.
For more information, see EM_LINEFROMCHAR in the Windows SDK.
// The index of the char to get information on.
int nIndex = 4;
CString strText;
m_myEdit.GetWindowText(strText);
strText = strText.Mid(nIndex, 1);
// Get the text extent of the character.
CDC *pDC = m_myEdit.GetDC();
CSize sz = pDC->GetTextExtent(strText);
m_myEdit.ReleaseDC(pDC);
CPoint pt = m_myEdit.PosFromChar(nIndex);
// Dump the index, character, line number, and character bounds.
TRACE(_T("nIndex = %d, character = %c, line = %d, bounds = ")
_T("{%d, %d, %d, %d}\r\n"),
nIndex, strText[0], m_myEdit.LineFromChar(nIndex),
pt.x /* left */, pt.y /* top */,
pt.x + sz.cx /* right */, pt.y + sz.cy /* bottom */);
Call this function to retrieve the character index of a line within a multiple-line edit control.
int LineIndex(int nLine = -1) const;
nLine
Contains the index value for the desired line in the text of the edit control, or contains -1. If nLine is -1, it specifies the current line, that is, the line that contains the caret.
The character index of the line specified in nLine or -1 if the specified line number is greater than the number of lines in the edit control.
The character index is the number of characters from the beginning of the edit control to the specified line.
This member function is only processed by multiple-line edit controls.
For more information, see EM_LINEINDEX in the Windows SDK.
// The string for replacing.
CString strString(_T("Hi, we're the replacements."));
int nBegin, nEnd;
// Replace the second line, if it exists, of the edit control
// with the text strString.
if ((nBegin = m_myEdit.LineIndex(1)) != -1)
{
nEnd = nBegin + m_myEdit.LineLength(nBegin);
m_myEdit.SetSel(nBegin, nEnd);
m_myEdit.ReplaceSel(strString);
}
Retrieves the length of a line in an edit control.
int LineLength(int nLine = -1) const;
nLine
The zero-based index of a character in the line whose length is to be retrieved. The default value is -1.
For single-line edit controls, the return value is the length, in TCHARs, of the text in the edit control.
For multiline edit controls, the return value is the length, in TCHARs, of the line specified by the nLine parameter. For ANSI text, the length is the number of bytes in the line; for Unicode text, the length is the number of characters in the line. The length does not include the carriage-return character at the end of the line.
If the nLine parameter is more than the number of characters in the control, the return value is zero.
If the nLine parameter is -1, the return value is the number of unselected characters in the lines that contain selected characters. For example, if the selection extends from the fourth character of one line through the eighth character from the end of the next line, the return value is 10. That is, three characters on the first line and seven on the next.
For more information about the TCHAR type, see the TCHAR row in the table in Windows Data Types.
This method is supported by the EM_LINELENGTH message, which is described in the Windows SDK.
See the example for CEdit::LineIndex.
Call this function to scroll the text of a multiple-line edit control.
void LineScroll(
int nLines,
int nChars = 0);
nLines
Specifies the number of lines to scroll vertically.
nChars
Specifies the number of character positions to scroll horizontally. This value is ignored if the edit control has either the ES_RIGHT or ES_CENTER style.
This member function is processed only by multiple-line edit controls.
The edit control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by nLines exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window.
LineScroll
can be used to scroll horizontally past the last character of any line.
For more information, see EM_LINESCROLL in the Windows SDK.
See the example for CEdit::GetFirstVisibleLine.
Call this function to insert the data from the Clipboard into the CEdit
at the insertion point.
void Paste();
Data is inserted only if the Clipboard contains data in CF_TEXT format.
For more information, see WM_PASTE in the Windows SDK.
// Replace all of the text with the text in the clipboard.
m_myEdit.SetSel(0, -1);
m_myEdit.Paste();
Call this function to get the position (top-left corner) of a given character within this CEdit
object.
CPoint PosFromChar(UINT nChar) const;
nChar
The zero-based index of the specified character.
The coordinates of the top-left corner of the character specified by nChar.
The character is specified by giving its zero-based index value. If nChar is greater than the index of the last character in this CEdit
object, the return value specifies the coordinates of the character position just past the last character in this CEdit
object.
Note
This member function is available beginning with Windows 95 and Windows NT 4.0.
For more information, see EM_POSFROMCHAR in the Windows SDK.
See the example for CEdit::LineFromChar.
Call this function to replace the current selection in an edit control with the text specified by lpszNewText.
void ReplaceSel(LPCTSTR lpszNewText, BOOL bCanUndo = FALSE);
lpszNewText
Points to a null-terminated string containing the replacement text.
bCanUndo
To specify that this function can be undone, set the value of this parameter to TRUE . The default value is FALSE.
Replaces only a portion of the text in an edit control. If you want to replace all of the text, use the CWnd::SetWindowText member function.
If there is no current selection, the replacement text is inserted at the current cursor location.
For more information, see EM_REPLACESEL in the Windows SDK.
See the example for CEdit::LineIndex.
Sets the text that is displayed as the text cue, or tip, in an edit control when the control is empty.
BOOL SetCueBanner(LPCWSTR lpszText);
BOOL SetCueBanner(
LPCWSTR lpszText,
BOOL fDrawWhenFocused = FALSE);
lpszText
[in] Pointer to a string that contains the cue to display in the edit control.
fDrawWhenFocused
[in] If FALSE, the cue banner is not drawn when the user clicks in the edit control and gives the control the focus.
If TRUE, the cue banner is drawn even when the control has focus. The cue banner disappears when the user starts to type in the control.
The default value is FALSE.
TRUE if the method is successful; otherwise FALSE.
This method sends the EM_SETCUEBANNER message, which is described in the Windows SDK. For more information, see the Edit_SetCueBannerTextFocused macro.
The following example demonstrates the CEdit::SetCueBanner method.
m_cedit.SetCueBanner(_T("First, enter text here..."), TRUE);
Call this function to set the handle to the local memory that will be used by a multiple-line edit control.
void SetHandle(HLOCAL hBuffer);
hBuffer
Contains a handle to the local memory. This handle must have been created by a previous call to the LocalAlloc Windows function using the LMEM_MOVEABLE flag. The memory is assumed to contain a null-terminated string. If this is not the case, the first byte of the allocated memory should be set to 0.
The edit control will then use this buffer to store the currently displayed text instead of allocating its own buffer.
This member function is processed only by multiple-line edit controls.
Before an application sets a new memory handle, it should use the GetHandle member function to get the handle to the current memory buffer and free that memory using the LocalFree
Windows function.
SetHandle
clears the undo buffer (the CanUndo member function then returns 0) and the internal modification flag (the GetModify member function then returns 0). The edit-control window is redrawn.
You can use this member function in a multiple-line edit control in a dialog box only if you have created the dialog box with the DS_LOCALEDIT style flag set.
Note
GetHandle
will not work with Windows 95/98. If you call GetHandle
in Windows 95/98, it will return NULL. GetHandle
will work as documented under Windows NT, versions 3.51 and later.
For more information, see EM_SETHANDLE, LocalAlloc, and LocalFree in the Windows SDK.
// The string to set in the edit control.
CString strString(_T("George Frideric"));
// Initialize the new local handle.
size_t cbSize = (strString.GetLength() + 1) * sizeof(TCHAR);
HLOCAL h = ::LocalAlloc(LHND, cbSize);
LPTSTR lpszText = (LPTSTR)::LocalLock(h);
_tcsncpy_s(lpszText, cbSize / sizeof(TCHAR), strString, _TRUNCATE);
::LocalUnlock(h);
// Free the current text handle of the edit control.
::LocalFree(m_myEdit.GetHandle());
// Set the new text handle.
m_myEdit.SetHandle(h);
Highlights a range of text that is displayed in the current edit control.
void SetHighlight(
int ichStart,
int ichEnd);
ichStart
[in] Zero-based index of the first character in the range of text to highlight.
ichEnd
[in] Zero-based index of the last character in the range of text to highlight.
This method sends the EM_SETHILITE message, which is described in the Windows SDK. This method sends the EM_SETHILITE message, which is described in the Windows SDK. Both SetHighlight
and GetHighlight
are enabled for UNICODE builds only.
Call this member function to set the text limit for this CEdit
object.
void SetLimitText(UINT nMax);
nMax
The new text limit, in characters.
The text limit is the maximum amount of text, in characters, that the edit control can accept.
Changing the text limit restricts only the text the user can enter. It has no effect on any text already in the edit control, nor does it affect the length of the text copied to the edit control by the SetWindowText member function in CWnd
. If an application uses the SetWindowText
function to place more text into an edit control than is specified in the call to LimitText
, the user can delete any of the text within the edit control. However, the text limit will prevent the user from replacing the existing text with new text, unless deleting the current selection causes the text to fall below the text limit.
This function replaces LimitText in Win32.
For more information, see EM_SETLIMITTEXT in the Windows SDK.
See the example for CEditView::GetEditCtrl.
Call this method to set the left and right margins of this edit control.
void SetMargins(
UINT nLeft,
UINT nRight);
nLeft
The width of the new left margin, in pixels.
nRight
The width of the new right margin, in pixels.
Note
This member function is available beginning with Windows 95 and Windows NT 4.0.
For more information, see EM_SETMARGINS in the Windows SDK.
See the example for CEditView::GetEditCtrl.
Call this function to set or clear the modified flag for an edit control.
void SetModify(BOOL bModified = TRUE);
bModified
A value of TRUE indicates that the text has been modified, and a value of FALSE indicates it is unmodified. By default, the modified flag is set.
The modified flag indicates whether or not the text within the edit control has been modified. It is automatically set whenever the user changes the text. Its value may be retrieved with the GetModify member function.
For more information, see EM_SETMODIFY in the Windows SDK.
See the example for CEdit::GetModify.
Call this function to set or remove a password character displayed in an edit control when the user types text.
void SetPasswordChar(TCHAR ch);
ch
Specifies the character to be displayed in place of the character typed by the user. If ch is 0, the actual characters typed by the user are displayed.
When a password character is set, that character is displayed for each character the user types.
This member function has no effect on a multiple-line edit control.
When the SetPasswordChar
member function is called, CEdit
will redraw all visible characters using the character specified by ch.
If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk ( *). This style is removed if SetPasswordChar
is called with ch set to 0.
For more information, see EM_SETPASSWORDCHAR in the Windows SDK.
// Turn off the password mode.
m_myEdit.SetPasswordChar(0);
ASSERT(!(m_myEdit.GetStyle() & ES_PASSWORD));
Calls this function to set the read-only state of an edit control.
BOOL SetReadOnly(BOOL bReadOnly = TRUE);
bReadOnly
Specifies whether to set or remove the read-only state of the edit control. A value of TRUE sets the state to read-only; a value of FALSE sets the state to read/write.
Nonzero if the operation is successful, or 0 if an error occurs.
The current setting can be found by testing the ES_READONLY flag in the return value of CWnd::GetStyle.
For more information, see EM_SETREADONLY in the Windows SDK.
// Set the edit control to be read-only.
m_myEdit.SetReadOnly(TRUE);
ASSERT(m_myEdit.GetStyle() & ES_READONLY);
Call this function to set the dimensions of a rectangle using the specified coordinates.
void SetRect(LPCRECT lpRect);
lpRect
Points to the RECT
structure or CRect
object that specifies the new dimensions of the formatting rectangle.
This member is processed only by multiple-line edit controls.
Use SetRect
to set the formatting rectangle of a multiple-line edit control. The formatting rectangle is the limiting rectangle of the text, which is independent of the size of the edit-control window. When the edit control is first created, the formatting rectangle is the same as the client area of the edit-control window. By using the SetRect
member function, an application can make the formatting rectangle larger or smaller than the edit-control window.
If the edit control has no scroll bar, text will be clipped, not wrapped, if the formatting rectangle is made larger than the window. If the edit control contains a border, the formatting rectangle is reduced by the size of the border. If you adjust the rectangle returned by the GetRect
member function, you must remove the size of the border before you pass the rectangle to SetRect
.
When SetRect
is called, the edit control's text is also reformatted and redisplayed.
For more information, see EM_SETRECT in the Windows SDK.
// Flag indicating whether to redraw the edit control.
bool fRedraw = TRUE;
CRect r;
m_myEdit.GetRect(&r);
// Reduce the formatting rect of the edit control by
// 10 pixels on each side.
if ((r.Width() > 20) && (r.Height() > 20))
{
r.DeflateRect(10, 10);
if (fRedraw)
m_myEdit.SetRect(&r);
else
m_myEdit.SetRectNP(&r);
}
Call this function to set the formatting rectangle of a multiple-line edit control.
void SetRectNP(LPCRECT lpRect);
lpRect
Points to a RECT
structure or CRect
object that specifies the new dimensions of the rectangle.
The formatting rectangle is the limiting rectangle of the text, which is independent of the size of the edit-control window.
SetRectNP
is identical to the SetRect
member function except that the edit-control window is not redrawn.
When the edit control is first created, the formatting rectangle is the same as the client area of the edit-control window. By calling the SetRectNP
member function, an application can make the formatting rectangle larger or smaller than the edit-control window.
If the edit control has no scroll bar, text will be clipped, not wrapped, if the formatting rectangle is made larger than the window.
This member is processed only by multiple-line edit controls.
For more information, see EM_SETRECTNP in the Windows SDK.
See the example for CEdit::SetRect.
Call this function to select a range of characters in an edit control.
void SetSel(
DWORD dwSelection,
BOOL bNoScroll = FALSE);
void SetSel(
int nStartChar,
int nEndChar,
BOOL bNoScroll = FALSE);
dwSelection
Specifies the starting position in the low-order word and the ending position in the high-order word. If the low-order word is 0 and the high-order word is -1, all the text in the edit control is selected. If the low-order word is -1, any current selection is removed.
bNoScroll
Indicates whether the caret should be scrolled into view. If FALSE, the caret is scrolled into view. If TRUE, the caret is not scrolled into view.
nStartChar
Specifies the starting position. If nStartChar is 0 and nEndChar is -1, all the text in the edit control is selected. If nStartChar is -1, any current selection is removed.
nEndChar
Specifies the ending position.
For more information, see EM_SETSEL in the Windows SDK.
See the example for CEdit::GetSel.
Call this function to set the tab stops in a multiple-line edit control.
void SetTabStops();
BOOL SetTabStops(const int& cxEachStop);
BOOL SetTabStops(
int nTabStops,
LPINT rgTabStops);
cxEachStop
Specifies that tab stops are to be set at every cxEachStop dialog units.
nTabStops
Specifies the number of tab stops contained in rgTabStops. This number must be greater than 1.
rgTabStops
Points to an array of unsigned integers specifying the tab stops in dialog units. A dialog unit is a horizontal or vertical distance. One horizontal dialog unit is equal to one-fourth of the current dialog base width unit, and 1 vertical dialog unit is equal to one-eighth of the current dialog base height unit. The dialog base units are computed based on the height and width of the current system font. The GetDialogBaseUnits
Windows function returns the current dialog base units in pixels.
Nonzero if the tabs were set; otherwise 0.
When text is copied to a multiple-line edit control, any tab character in the text will cause space to be generated up to the next tab stop.
To set tab stops to the default size of 32 dialog units, call the parameterless version of this member function. To set tab stops to a size other than 32, call the version with the cxEachStop parameter. To set tab stops to an array of sizes, use the version with two parameters.
This member function is only processed by multiple-line edit controls.
SetTabStops
does not automatically redraw the edit window. If you change the tab stops for text already in the edit control, call CWnd::InvalidateRect to redraw the edit window.
For more information, see EM_SETTABSTOPS and GetDialogBaseUnits in the Windows SDK.
See the example for CEditView::SetTabStops.
Displays a balloon tip that is associated with the current edit control.
BOOL ShowBalloonTip(PEDITBALLOONTIP pEditBalloonTip);
BOOL ShowBalloonTip(
LPCWSTR lpszTitle,
LPCWSTR lpszText,
INT ttiIcon = TTI_NONE);
pEditBalloonTip
[in] Pointer to an EDITBALLOONTIP structure that describes the balloon tip.
lpszTitle
[in] Pointer to a Unicode string that contains the title of the balloon tip.
lpszText
[in] Pointer to a Unicode string that contains the balloon tip text.
ttiIcon
[in] An INT that specifies the type of icon to associate with the balloon tip. The default value is TTI_NONE. For more information, see the ttiIcon
member of the EDITBALLOONTIP structure.
TRUE if this method is successful; otherwise, FALSE.
This function sends the EM_SHOWBALLOONTIP message, which is described in the Windows SDK. For more information, see the Edit_ShowBalloonTip macro.
The first code example defines a variable, m_cedit
, that is used to access the current edit control. This variable is used in the next example.
public:
// Variable to access the edit control.
CEdit m_cedit;
The next code example displays a balloon tip for an edit control. The CEdit::ShowBalloonTip method specifies a title and balloon tip text.
m_cedit.ShowBalloonTip(
_T("CEdit Balloon Tip"), // title
_T("Here's a tip!"), // text
TTI_INFO);
Call this function to undo the last edit-control operation.
BOOL Undo();
For a single-line edit control, the return value is always nonzero. For a multiple-line edit control, the return value is nonzero if the undo operation is successful, or 0 if the undo operation fails.
An undo operation can also be undone. For example, you can restore deleted text with the first call to Undo
. As long as there is no intervening edit operation, you can remove the text again with a second call to Undo
.
For more information, see EM_UNDO in the Windows SDK.
// Undo the last operation, if possible.
if (m_myEdit.CanUndo())
m_myEdit.Undo();
MFC Sample CALCDRIV
MFC Sample CMNCTRL2
CWnd Class
Hierarchy Chart
CWnd Class
CButton Class
CComboBox Class
CListBox Class
CScrollBar Class
CStatic Class
CDialog Class