CTer Class Interface

The CTer class interface is provide by the TER_MFC.H and TER_MFC.CPP files. Your application module that uses the CTer class object should include the TER_MFC.H file. Your application project should include the TER_MFC.CPP and TER.LIB files. Also the TER.DLL file must be available in the current directory or a directory included in the path statement.

CTer is a class derived from the CWnd class provided by Microsoft's MFC library. Your application can create an object directly from CTer class or from a class derived from CTer class.

The editor window creation is a two step process. The first step is to call the constructor, and the second step is to call the 'Create' function.

The editor control sends the ON_EN_CHANGE message to the parent window. The parent window should include an entry in the message map to handle this message. The message map takes the form of 'ON_Notification(ControlId, MemberFunction)'.

Your application can communicate with the editor control using the class member functions as well as the DLL functions described in the 'Application Interface Functions' chapter. The class member functions provide rudimentary functionality similar to the Microsoft's CEdit class functions. The DLL functions should be used for additional manipulation of the control data.

Class Member Functions:

CanUndo:	Returns TRUE if the undo buffer is not empty.
Clear:	Delete the selected text.
Copy:	Copy the selected data to the clipboard.
Create:	Create the edit control and attach it to the CTer object.
CTer:	Constructor.
Cut:	Cut the selected data to the clipboard.
DefaultEditStyles:	Return the default editor window styles which can be used to create the control window.
DeleteContents:	Delete the current contents of the edit control.
GetFirstVisibleLine:	Get the line index of the topmost line in the window.
GetHandle:	Retrieve the control data.
GetLine:	Retrieve the text for a line.
GetLineCount:	Get the total number of lines in the edit control.
GetModify:	Returns TRUE if the text is modified
GetSel:	Retrieve the selected text.
LineFromChar:	Get the line number from a given character index.
LineIndex:	Retrieve the character index for a line.
LineLength:	Get the length of the given line.
LineScroll:	Scroll the control window.
MenuEnable:	Returns TRUE if a menu item should be enabled.
MenuSelect:	Returns TRUE if a menu item should be checked.
Paste:	Paste the text data from the clipboard.
ReplaceSel:	Replace the selected text or insert new text.
Serialize:	Save the contents of the control to the archive.
SerializeRaw:	Save the contents of the control to the standalone archive file.
SetHandle:	Assign new data to the control.
SetModify:	Set/reset the modification flag.
SetReadOnly	Set/reset the ReadOnly attribute.
SetSel:	Select text.
TerMenu:	Execute an editor menu command.
Undo:	Reverse the previous edit operation.

Class Member Function Description

CanUndo:

Returns TRUE if the undo buffer is not empty.

BOOL CanUndo();

See Also: Undo

Clear:

Delete the selected text.

void Clear();

See Also: SetSel(), DeleteContents()

Copy:

Copy the selected data to the clipboard.

void Copy();

See Also: Cut(), Paste()

Create:

Create the edit control and attach it to the CTer object.

BOOL Create(dwStyle, rect, pParentWnd, nID);

DWORD dwStyle; // Window style bits. Please refer to the 'Create Window' section in the 'Getting Started' chapter for a list of control style constants. These constants have a prefix of 'TER_', such as TER_WORD_WRAP, TER_PRINT_VIEW, etc.. More than one styles can be used by using the logical OR (|) operator.

Set this argument to 0 to use the default styles as given by the CTer::DefaultEditStyles function.

const RECT ▭ // Window rectangle. The rectangle coordinates are specified in the pixel units relative to the top-left of the parent window.

Cwnd *pParentWnd; // Pointer to the parent window object

UINT nId; // Control id. Each control within a parent window should have a unique control id.

Remarks: This function calls the CWnd::Create function passing the above arguments. The window class is given by the TER_CLASS constant defined in the TER.H file.

The dwStyle argument should always include the WS_CHILD style. Usually the dwStyle argument will also include the WS_VISIBLE and WS_BORDER styles.

Windows sends the initial window creation messages which can be handled by overriding the default handlers for the OnCreate, OnNcCreate, OnNcCalcSize and OnGetMinMaxInfo functions.

Return Value: The function returns a TRUE value when successful. Otherwise it returns 0.

See Also: DefaultEditStyles()

CTer

Constructor.

CTer();

Cut:

Cut the selected data to the clipboard.

void Cut();

DefaultEditStyles:

Return the default editor window styles which can be used to create the control window.

DWORD DefaultEditStyles();

Remarks: This function returns the default style bits that can be used to create a control window. The default style bits include the following styles:

Return Value: This function returns the window style bits as listed above.

See Also: Create()

DeleteContents:

Delete the entire contents of the edit control.

void DeleteContents();

Remarks: This function clears the contents of the edit control by assigning it an empty buffer.

See Also: Clear()

GetFirstVisibleLine:

Returns the line index of the topmost line in the window.

long GetFirstVisibleLine();

GetHandle:

Retrieve the control data.

HGLOBAL GetHandle(BufferLen);

long far *BufferLen; // this argument receives the length of the buffer.

Remarks: This function retrieves the current contents of the control in a global memory handle. The buffer contains the text as well as the formatting information. Your application is responsible for freeing this handle when you no longer need it.

The format of the data in the buffer will be the same as the input buffer. You can, however, get the data in an alternate format by calling the ::TerSetOutputFormat DLL function before calling this function.

Return Value: The function returns the handle to a global memory block containing the contents of the control.

See Also: SetHandle(), ::TerSetOutputFormat()

GetLine:

Retrieve the text for a line.

int GetLine(index, buffer);

int GetLine(index, buffer, MaxLength);

long index; // index of the line to retrieve the text. The line number must be between 0 and TotalLines -1.

LPSTR buffer; The buffer pointer to receive the text. The first WORD of the buffer stores the maximum length of the buffer.

When calling the first implementation of the function, your application is responsible for assigning the maximum buffer length to the first word before calling this function. In the second implementation, the GetLine function assigns the MaxLength argument to the first word.

int MaxLength: // maximum size of the text to return.

Remarks: The text data returned by this function does not include the format information. The text string is not NULL terminated.

Return Value: The function returns the length of the text returned in the buffer.

See Also: GetLineCount()

GetLineCount:

Get the total number of lines in the edit control.

long GetLineCount();

GetModify:

Returns TRUE if the text is modified

BOOL GetModify();

See Also: SetModify()

GetSel:

Retrieve the position of the selected text.

void GetSel(StartPos, EndPos);

long &StartPos; // Starting character index of the highlighted block

long &EndPos; // Index of the first non-highlighted character past the selected block

Remarks: If a block is not highlighted, both the StartPos and EndPos variables are set to zero.

See Also: SetSel()

LineFromChar:

Get the line number from a given character index.

long LineFromChar(nIndex);

long nIndex; // character index of the location

See Also: LineIndex()

LineIndex:

Retrieve the character index for a line.

long LineIndex(nLine);

long nLine; // Line index of a line. The line index must be between 0 and TotalLines - 1.

See Also: LineFromChar(), GetLineCount()

LineLength:

Get the length of the given line.

int LineLength(nLine);

long nLine; // Line index of a line..

Return Value: If the nLine argument is between 0 and TotalLines - 1, this function returns the length of the specified line.

If nLine is -1, and a block is not highlighted, the function then returns the length of the current line.

If nLine is -1 and a block is highlighted, then the function returns the number of unhighlighted characters in the highlighted lines. For example, if the selected block contains characters starting from the third character of the second line through the 25th character of the sixth line, and if the sixth line is 30 characters long, then this function will return 7 (2 for the second line and 5 for the sixth line).

LineScroll:

Scroll the control window.

void LineScroll(nLines, nChars);

long nLines; // number of lines to scroll the window vertically. If nLines is negative, the window is scrolled up.

int nChars; // number of characters to scroll the window horizontally. If nChars is negative, the window is scrolled toward the left.

MenuEnable:

Returns TRUE if a menu item should be enabled.

BOOL MenuEnable(MenuItem);

int MenuItem: // menu item number to test. The MenuItem can be one of the constants defined in the TER_CMD.H file.

Remarks: This function is helpful when your application uses the menu options to manipulate the editor control. Typically, your application will have menu options similar to the demo program. The MenuEnable function can be used to enable or disable a menu option.

For Example, consider the clipboard 'Cut' option in the menu. The following statement in the update handler for this menu option will enable or disable the 'Cut' menu selection:

void CMyView::OnUpdateEditCut(CCmdUI *pCmdUI)
{
pCmdUI->Enable(ter.MenuEnable(ID_CUT));
}

The 'ID_CUT' constant is defined in the TER_CMD.H file.

Return Value: This function returns TRUE if the menu option is to be enabled.

See Also: MenuSelect(), TerMenu()

MenuSelect:

Returns TRUE if a menu item should be checked.

BOOL MenuSelect(MenuItem);

int MenuItem: // menu item number to test. The MenuItem can be one of the constants defined in the TER_CMD.H file.

Remarks: This function is helpful when your application uses the menu options to manipulate the editor control. Typically, your application will have menu options similar to the demo program. The MenuSelect function can be used to 'check' a menu option.

For Example, consider the 'Bold' option in the font menu. The following statement in the update handler for this menu option will check or uncheck the 'Bold' menu selection:

void CMyView::OnUpdateFontBold(CCmdUI *pCmdUI)
{
pCmdUI->SetCheck(ter.MenuSelect(ID_BOLD_ON));
}

The 'ID_BOLD_ON' constant is defined in the TER_CMD.H file.

Return Value: This function returns TRUE if the menu option is to be checked.

See Also: MenuEnable(), TerMenu()

Paste:

Paste the text data from the clipboard.

void Paste();

ReplaceSel:

Replace the selected text or insert new text.

void ReplaceSel(NewText);

char huge *NewText; // pointer to the new text which will replace the old text.

Remarks: This function replaces a highlighted block of text with the new text specified by the argument. If a block is not highlighted, the new text is simply inserted at the current caret location.

Serialize:

Save the contents of the control to the archive.

void Serialize(ar);

CArchive &ar; // archive object reference

Remarks: This function retrieves and stores the control data from the archive file. The text is preceded by a 4 byte header block that stores the length of the control data buffer.

See Also: SerializeRaw()

SerializeRaw:

Save the contents of the control to the standalone archive file.

void SerializeRaw(ar);

CArchive &ar; // archive object reference

Remarks: This function retrieves and stores the control data from the archive file. Unlike the 'Serialize' function, this function does not use a header block. The archive file is expected to be a standalone file.

See Also: Serialize()

SetHandle:

Assign new data to the control.

BOOL SetHandle(hBuffer, BufferLen, title, release);

HANDLE hBuffer: // The global handle to the buffer containing the new text and format data.

long BufferLen; // The size of the hBuffer buffer

LPBYTE title; // new title for the window. Specify a NULL value if you do not wish to change the window title

BOOL release; // Release the buffer after applying

Description: You can use this function to set new data in an existing TER window. The existing text in the window is discarded. The data in the buffer can be provided in one of these formats:

Text Format

Rich Text Format

TER Native Format

If the 'release' flag is set, the hBuffer handle becomes the property of the TER window. Your application must not try to lock or free this buffer.

Return Value: This function returns a TRUE value if successful. Otherwise it returns a FALSE value.

See Also: GetHandle()

SetModify:

Set/reset the text modification flag.

void SetModify(bModified);

BOOL bModified; // new status of the modification flag

Remarks: The editor automatically sets an internal flag when the user modifies the text. This flag is used to prompt the user to save the text before closing the window. You can use this function to override the status of the modification flag.

See Also: GetModify()

SetReadOnly

Set/reset the ReadOnly attribute.

BOOL SetReadOnly(bReadOnly);

BOOL bReadOnly; // new status of the ReadOnly flag

Return Value: This function returns the previous status of the ReadOnly flag.

SetSel:

Select text.

void SetSel(nStartChar, nEndChar, bNoScroll);

long nStartChar; // Starting character index of the block

long nEndChar; .// Ending character index of the block

BOOL bNoScroll; // Set to TRUE to scroll the selection ending character into view.

Remarks: The highlighting is automatically turned off when the user inputs a new character or hits any direction key.

See Also: GetSel()

TerMenu:

Execute an editor menu command.

void TerMenu(MenuItem)

int MenuItem: // menu item number to test. The MenuItem can be one of the constants defined in the TER_CMD.H file.

Remarks: This function is helpful when your application uses the menu options to manipulate the editor control. Typically, your application will have menu options similar to the demo program. The TerMenu function is used to call the editor DLL to perform a menu option.

For Example, consider the 'Bold' option in the font menu. The following statement in the handler for this menu option will invoke the corresponding editor DLL handler:

void CMyView::OnFontBold()
{
ter.TerMenu(ID_BOLD_ON);
}

The 'ID_BOLD_ON' constant is defined in the TER_CMD.H file.

See Also: MenuEnable(), MenuSelect()

Undo:

Reverse the previous edit operation.

void Undo();

See Also: CanUndo()