CNativeTextEdit

Heritage

Description

Usage

Environment

Protected Data Members

Private Data Members

Public Methods

Destructor and Initializer Methods

Text Utilities

Selection Utilities

Non-text Utilities

Validation Handling

Tabbing Utilities

Inherited Utilities

Mouse Events

Get a Handle to an XVT Text Edit Object

Keyboard Navigation

Protected Methods

Constructor Methods

Internal Text Manipulation

TDI Enabling Methods

Heritage

Subclasses: NLineText, NTextEdit

Description

Usage

Environment

Protected Data Members

Private Data Members

Public Methods

virtual ~CNativeTextEdit(void);

The destructor, which cleans up the text edit box.

BOOLEAN INativeTextEdit(unsigned theAttributes	= TX_BORDER,
	UNITS theRightMargin 	= 1000,
	int theCharactedLimit 	= 1000,
	const CStringRW theInitialText	= NULLString,
	BOOLEAN isAutoSelected 	= FALSE,
	BOOLEAN isVisible 	= TRUE,
	GLUETYPE theGlue 	= NULLSTICKY);

The initializer. It takes an unsigned value pertaining to the XVT Portability Toolkit attributes that the text edit system can have. These attributes can be OR'd and passed in together, as described in the text editing chapter of the XVT Portability Toolkit Guide. Possible XVT Portability Toolkit values for theAttributes are shown in Table 10.

The next parameter, theRightMargin is a pixel measurement of the right margin, starting from the left side and beginning at zero (0). In addition, there is a parameter that sets the default character limit at 1,000 characters. theInitialText is a string containing any text you may wish to initialize with the text edit system. If the isAutoSelected parameter is set to TRUE, all of the text in the text edit box becomes selected when the user clicks inside the box. Finally, this initializer, like the initializers of all CView classes, takes a visibility state and a glue type.

virtual void SetText(const CStringRW& theText);

Given a text string, SetText sets the text for the text edit box. Any text already inside the box is replaced. This method sets the text to be exactly what is passed in.

virtual BOOLEAN Append(const CStringRW& theText);

Given a text string, Append appends this string to whatever text is already inside a text edit object. This method returns a BOOLEAN value of TRUE if the append operation succeeds.

virtual CStringRW GetText(void) const;

Returns a string containing all of the text in the edit box.

virtual T_CNUM GetNCharInText(void) const;

Returns the number of characters in a text edit box.

virtual void SelectText(void);

Selects all of the text inside a text edit box.

virtual CStringRW GetSelectedText(void) const;

This method is analogous to GetText, except that is applies to selected text. That is, it returns a string containing all selected text in the edit box.

virtual T_CNUM GetNCharInSelection(void) const;

Returns the number of characters in the selected text within a text edit box.

virtual BOOLEAN Clear(void);

Clears the contents of a text box.

virtual BOOLEAN IsEmpty(void) const;

Returns a BOOLEAN value indicating whether a text box contains any text.

virtual void SetAttribute(
	unsigned theAttribute,BOOLEAN isSet=TRUE);

Sets an attribute for a text box. You specify the attribute and give it a BOOLEAN value indicating whether to turn this attribute on or off. For further information about XVT Portability Toolkit attributes, see the initializer method INativeTextEdit. Also, see the text editing chapter of the XVT Portability Toolkit Guide.

virtual unsigned long GetAttributes(void) const;

Returns the attributes of a text editing box.

virtual void SetLimit(int theCharacterLimit);

Applies only when the TX_ONEPAR attribute is set. This method sets the limit on the number of characters the paragraph, and therefore the entire text box, can contain. If you set a new limit and the text box already contains more characters than the newly set limit, the text is not truncated. For example, if you set a new limit of 400 characters for a text box that already contains 600 characters, then the 600 characters remain. However, no more text can be entered into the box.

virtual int GetLimit(void) const;

Returns the maximum number of characters a text box can contain.

virtual void SetMargin(UNITS theRightMargin);

Sets the right margin of a text edit box. theRightMargin is a pixel measurement of the right margin, starting from the left side and beginning at zero (0). If the text edit object has a horizontal scrollbar, this method resets the scrollbar's range according to the new margin.

virtual UNITS GetMargin(void) const;

Returns a number indicating the pixel measurement of a text box's right margin. Numbering starts at zero (0) at the left margin.

virtual void Reset(void);

Redraws the entire text box and scrolls its contents to the top of the box. It also sets the cursor at the top-left corner of the text box.

virtual void Suspend(void);

Suspends the redrawing of a text box's contents so that multiple text insertions can be done in rapid succession without taking the time to redraw the box after each insertion. See Resume, next.

virtual void Resume(void);

Resumes the redrawing of a text edit box's contents after redrawing has been suspended. It is usually a good idea to "wrap" the insertion of text into a text edit box by calls to Suspend and Resume. See Suspend, above.

virtual void DoHit(CONTROL_INFO theControlInfo);

The text edit event handler calls DoHit() in response to an E_CONTROL message. These occur for such events as focus change and typing in the text edit.

virtual void SetFocusCommands(
	long theKeyFocusCommand,
	long theKeyFocusLostCommand);

Sets the command that the text edit sends when gaining or losing keyboard focus.

virtual void SetTextCommand(long theTextCommand);

Sets the command that the text edit sends when the text is changed by the user or programatically.

long GetTextCommand( void ) const;

Returns the command sent in response to a text change.

long GetKeyFocusCommand(void) const;

Returns the command sent when gaining keyboard focus.

long GetKeyFocusLostCommand(void) const;

Returns the command sent when losing keyboard focus.

virtual int Validate(int theKey,
	BOOLEAN isShiftKey, 
	BOOLEAN isControlKey);

This method is called when a text box receives a keyboard event. theKey is the ASCII value for the character key that was pressed; isShiftKey and isControlKey indicate whether the Shift or Control key was pressed in conjunction with the character key.

Validate responds to a keyboard event in one of three ways:

Validate accepts the keyboard event and returns theKey as the ASCII value of the character to be placed in the text edit system.

Validate rejects the keyboard event by returning NULL.

Validate seeks to modify the keyboard event by returning the ASCII value of the character it wishes to pass on to the text edit system.

To see how Validate works, think of implementing a password text box. When the user enters a login name, Validate would behave as in case 1 by permitting the characters being typed to appear on the screen. However, when the user enters a password, Validate may choose to modify the input by returning an asterisk (*) for each event received. In addition, Validate may behave as in case 2, ignoring all tabs by returning NULL.

Override this method to implement the kind of text validation described here. By default, this method always returns the exact key that it receives.

virtual void PostValidate();

When DoHit() detects a change in text content, it calls PostValidate(). The text edit implementation uses the CValidator associated with the text edit (if any) to perform standard validation of the modified text.

void SetTabSize(int theSize);

Sets the tab size to 8 tab units.

int GetTabSize(void) const;

Returns the current tab size.

virtual void Key(const CKey& theKey);

Sends a keyboard event to a text edit box. thekey represents the character key that was pressed, including whether the Shift or Control key was pressed at the same time. This method calls Validate to allow the user to validate the key before actually passing it on to the text edit system.

virtual void SetOrigin(const CPoint& theDelta);

Takes the current origin of the text edit box and adds theDeltaPoint to it. Suppose, for example, that a text box has an origin of 10,20 and you want to shift the origin by three pixels to the right. You set the origin by giving it a delta point of 3,0, which shifts the view three pixels horizontally.

virtual void SetFont(const CFont &theNewFont,
	BOOLEAN isUpdate = FALSE);

Takes a font and sets the text box's environment to have that font. The isUpdate parameter indicates whether this SetFont message is simply an update message or whether it is a "real" SetFont message meaning that the text box should set its own font to the new font.

virtual void Size(const CRect& theNewSize);

Resets the region of the text box. Possibly the region could be in a different location and have completely different dimensions-a new width or a new height. The coordinates of the region, theNewSize, like the region that is passed in on creation of a text box, is relative to the enclosure.

virtual void Show(void);

Makes the text edit box and its contents visible.

virtual void Hide(void);

Makes the text edit box and its contents invisible.

virtual void Activate(void);

Sets the state of the text box to active so that it can receive events.

virtual void Deactivate(void);

This method deactivates a text edit object.

virtual void Draw(const CRect& theClippingRegion);

Takes care of any drawing that the text box must do. theClippingRegion is the part of the text box that needs to be drawn.

virtual void SetGlue(GLUETYPE theGlue);

Sets the glue type of the glue object associated with the text box. By default, a glue object has a type of NULLSTICKY upon creation. For a listing of valid glue types, see the list under CGlue "Usage".

virtual BOOLEAN ClassCanGetKeyFocus(void) const;

Overrides CView::ClassCanGetKeyFocus to return TRUE.

virtual void Disable(void);

Disables a text box so that it cannot receive events.

virtual void SetEnvironment(const CEnvironment& theNewEnvironment, BOOLEAN isUpdate = FALSE);

Sets the environment for a text box, using theNewEnvironment that is passed to it. By default, text boxes share their enclosure's environment. However, as soon as you use SetEnvironment to give a text box an environment of its own, the text box uses that environment instead of the shared environment.

virtual void DoCommand(long theCommand, 
	void* theData = NULL);

Overrides CView::DoCommand to provide handling for TDI commands.

TXEDIT GetXVTTextEdit(void) const;

Returns a handle to an XVT Portability Toolkit text edit object.

CNativeTextEdit(CSubview *theEnclosure,
	const CRect& theRegion,
	unsigned theAttributes	= TX_BORDER,
	UNITS theRightMargin	= 1000,
	int theCharacterLimit	= 1000);

A constructor. theEnclosure is a pointer to the subview that will contain the text box. theRegion is a coordinate location, local to the enclosure, that is used to place the text box. If the text box has a border, which is the default, then the border rectangle is drawn around the CRect. This CRect object is inset by 4 pixels inside the border. The bottom of the CRect may be inset even more to ensure that an integral number of lines will fit into the text box.

In addition, this constructor takes an unsigned value pertaining to the XVT Portability Toolkit attributes that the text edit system can have. These attributes can be OR'd and passed in together, as described in the Text Edit section of the "Controls" chapter of the XVT Portability Toolkit Guide. For further information about the XVT Portability Toolkit attributes, see INativeTextEdit. Finally, this constructor takes a right margin for the text box, which is measured in logical units starting with zero (0) at the left side of the text box, and a limit on the number of characters that can fit into the text box.

CNativeTextEdit(CSubview *theEnclosure);

A constructor that passes theEnclosure to the inherited constructor for CView.

CNativeTextEdit(const CNativeTextEdit& theTextEdit);

A copy constructor that duplicates the attributes of a text box, as well as the text inside it.

CNativeTextEdit& operator= (
	const CNativeTextEdit& theTextEdit);

An assignment operator that duplicates the attributes of a text box, as well as the text inside it.

void CreateTextEdit(void);

This method is used to construct a text edit object at resource instantiation time.

void GetTextInternal(T_PNUM theFirstParagraph,
	T_PNUM theLastParagraph,
	T_LNUM theFirstLine,
	T_LNUM theLastLine,
	T_CNUM theFirstChar,
	T_CNUM theLastChar,
	CStringRW theTextBuffer) const; 

Returns all of the text contained in a text box. It is very similar to the copy constructor GetText, but it performs the actual calculations within the text editing system. GetTextInternal takes the numbers of the first and last paragraphs, the numbers of the first and last lines, and the numbers of the first and last characters. Then it appends the text mapped out by these parameters to any text already contained in the given string buffer.

T_CNUM GetNCharInternal(T_PNUM theFirstParagraph,
	T_PNUM theLastParagraph,
	T_LNUM theFirstLine,
	T_LNUM theLastLine,
	T_CNUM theFirstChar,
	T_CNUM theLastChar) const;

Returns the number of characters of all the text contained in a text box. GetNCharInternal takes the numbers of the first and last paragraphs, the numbers of the first and last lines, and the numbers of the first and last characters. Then it counts all the characters in the chunk of text mapped out by these parameters.

void GetFullPar(T_PNUM theParagraph, 
	CStringRW theText) const;

Given a paragraph number, returns the full paragraph of text, appending it to any text already contained in the given string buffer.

void GetLineInternal(T_PNUM theParagraph, 
	T_LNUM theLine, CStringRW theText) const;

Returns one line of text. This method takes the paragraph number and the line number and then appends the line to any text already contained in the given string buffer.

void Truncate(CStringRW& theText);

An internal method that truncates the text to fit the character limit of the CNativeTextEdit object.

void ResetColors(void);

An internal method that is called to update the colors of the text after a call to SetEnvironment.

virtual void UpdateUnits(CUnits* theUnits);

Updates the CUnits object indicated by theUnits, which is the CUnits object owned by the CNativeTextEdit object, that is, an object inheriting from CNativeTextEdit. For more information, see CUnits.

virtual void PositionTextEdit(void);

Internal method which positions the text edit control within the bounds of itsFrame.

virtual void DoUpdateModel(long theControllerId, 
	long theCommand, const CModel* theModel);

Overrides CView::DoUpdateModel to provide handling of TDI messages.

void TdiProcessEvent(EVENT* e);

Processes text edit events and sends TDI notifications with the contents of the control.

void GetPartLine(T_CNUM theFirstChar,
	T_CNUM theLastChar,
	T_PNUM theParagraph,
	T_LNUM theLineNumber, 
	CStringRW theText) const;

Returns part of a line. This method takes the numbers of the starting and ending characters in the line, the paragraph number, the line number, and a string buffer. It appends the partial line mapped out by the first four parameters to any text contained in the string buffer.

void GetPartPar(T_CNUM theStartChar,T_CNUM theEndChar,
	T_PNUM theParagraph,
	T_LNUM theStartLine,
	T_LNUM theEndLine, 
	CStringRW theText) const;

Returns part of a paragraph. It has parameters for the starting character and ending character, the paragraph number, the starting line and ending line, and a string buffer. The partial paragraph mapped out by the first five parameters is appended to any text already contained in the string buffer.

T_CNUM GetNCharInPartPar(T_CNUM theStartChar,
	T_CNUM theEndChar,
	T_PNUM theParagraph,
	T_LNUM theStartLine,
	T_LNUM theEndLine) const;

Returns the total number of characters in part of a paragraph. It takes the starting character and the ending character in the partial paragraph, the paragraph number, and the numbers of the starting line and ending line.