Class CEditableText

CEditableText

Support

Supported from 5.0

Description

An abstract base class which defines the behaviour that all classes in the editable text class hierarchy (CPlainText, CGlobalText and CRichText) must provide. It provides no storage for text or text formatting, so it is not directly usable. It defines protocols for editing the contents of a text object and for extracting format data from a text object which supports formatting.

Note: when specifying a position in a text object (the document position), zero is before the first character in the document. If the document contains n characters, position n is after the last character. Valid document positions are therefore between zero and the length of the document, inclusive. Many editable text functions raise a panic if a specified document position is invalid.

Note also that the functions which implement support for front-end-processor inline editing are intended for internal use only by Symbian.

Derivation

CBase Base class for all classes to be instantiated on the heap CEditableText An abstract base class which defines the behaviour that all classes in the editable text class hierarchy (CPlainText, CGlobalText and CRichText) must provide

Defined in CEditableText:
Anonymous, CopyToStoreL(), DeleteL(), DocumentLength(), EDefaultTextGranularity, EFlatStorage, ELineBreak, ENonBreakingHyphen, ENonBreakingSpace, ENonBreakingTab, EPageBreak, EParagraphDelimiter, EPictureCharacter, EPotentialHyphen, ESegmentedStorage, ETabCharacter, EVisibleSpaceCharacter, Extract(), GetWordInfo(), HasChanged(), InsertL(), ParagraphCount(), PasteFromStoreL(), Read(), Reset(), RestoreComponentsL(), RestoreL(), ScanParas(), ScanWords(), SetHasChanged(), StoreComponentsL(), StoreL(), TDocumentStorage, ToParagraphStart(), WordCount()

Inherited from CBase:
operator new()

TStreamId StoreL(CStreamStore& aStore)const;

Description

Stores the text and its components. The components (e.g. fields and pictures) are stored in separate streams within the stream store.

Parameters

CStreamStore& aStore Stream store to which the text and text components are written.

Return value

TStreamId The ID of the stream store.

void RestoreL(const CStreamStore& aStore,TStreamId aStreamId);

Description

Restores the text and its components from a stream store.

Parameters

const CStreamStore& aStore Stream store containing the text and its components. TStreamId aStreamId The ID of the stream store in which the text was previously stored.

virtual void StoreComponentsL(CStreamStore& aStore,CStoreMap& aMap)const = 0;

Description

Stores the text components, e.g. fields, pictures and formatting to the stream store specified. Does not store the text content.

Parameters

CStreamStore& aStore Stream store to which the text components are written. CStoreMap& aMap A store map. This binds the address of text components to the stream ID of aStore. This is needed to support deferred loading of pictures in rich text.

virtual void RestoreComponentsL(const CStreamStore& aStore) = 0;

Description

Restores the text components, e.g. fields, pictures and formatting from the stream store. Does not restore the text content.

Parameters

const CStreamStore& aStore The stream store from which the text components are restored.

virtual void Reset() = 0;

Description

Deletes the text content and components from the text object, leaving the single end-of-text paragraph delimiter.

virtual void InsertL(TInt aInsertPos,const TChar& aChar) = 0;
virtual void InsertL(TInt aInsertPos,const TDesC& aBuf) = 0;

Description

Inserts a single character or a descriptor into the text object at a specified document position.

Parameters

TInt aInsertPos A valid document position at which to insert the character or descriptor. const TChar& aChar The character to insert. const TDesC& aBuf The descriptor to insert.

virtual TBool DeleteL(TInt aPos,TInt aLength) = 0;

Description

Deletes one or more characters beginning at (and including) the character at the specified document position.

Parameters

TInt aPos The document position from which to delete. TInt aLength The number of characters to delete.

Return value

TBool Indicates whether or not two paragraphs have been merged as a result of the delete, so that the resulting paragraph needs to be reformatted. This value is only relevant to rich text, so for plain and global text implementations, the function always returns EFalse.

virtual TPtrC Read(TInt aStartPos)const = 0;
virtual TPtrC Read(TInt aStartPos,TInt aLength)const = 0;

Description

Gets a read-only pointer descriptor to a portion of the text.

Parameters

TInt aStartPos A valid document position from which to read. TInt aLength If specified, the number of characters to read, inclusive of the character at position aStartPos. If not specified, the read continues to the end of the document, or the end of the segment if using segmented storage.

Return value

TPtrC Read-only pointer descriptor to a portion of the text.

virtual void Extract(TDes& aBuf,TInt aPos=0)const = 0;
virtual void Extract(TDes& aBuf,TInt aPos,TInt aLength)const = 0;

Description

Copies a portion of the text into a descriptor. Starts at the position specified and continues to the end of the document. A length may optionally be specified.

Parameters

TDes& aBuf Buffer which on return contains the extracted text. TInt aPos=0 The document position from which to copy. Must be a valid position, or a panic occurs. TInt aLength If specified, the number of characters to copy.

virtual void CopyToStoreL(CStreamStore& aStore,CStreamDictionary& aDictionary,TInt aPos,TInt aLength)const = 0;

Description

Copies a portion of the text to the clipboard.

Parameters

CStreamStore& aStore The clipboard's store (see class CClipboard). CStreamDictionary& aDictionary The clipboard's stream dictionary (see class CClipboard). TInt aPos A valid document position from which to begin copying. TInt aLength The number of characters to copy.

virtual TInt PasteFromStoreL(const CStreamStore& aStore,const CStreamDictionary& aDictionary,TInt aPos) = 0;

Description

Pastes the contents of the clipboard into the text object at the specified document position.

Parameters

const CStreamStore& aStore The clipboard's store (see class CClipboard). const CStreamDictionary& aDictionary The clipboard's stream dictionary (see class CClipboard). TInt aPos A valid document position at which to paste the text.

Return value

TInt The number of characters pasted.

virtual TInt DocumentLength()const = 0;

Description

Returns a count of the number of characters in the document, excluding the end-of-text paragraph delimiter.

Return value

TInt The number of characters in the document.

virtual TInt WordCount()const = 0;

Description

Returns a count of the number of words in the document.

Return value

TInt The number of words in the document

virtual TInt ParagraphCount()const = 0;

Description

Returns a count of the number of paragraphs in the document.

Return value

TInt The number of paragraphs in the document. Notes: The end-of-text paragraph delimiter at the end of every document means this function always returns a count of at least one.

virtual TInt ScanWords(TInt& aPos,TUint& aScanMask)const;

Description

Scans the text from a specified document position to a location determined by the flags specified in a bitmask. The function can scan forwards or backwards to the beginning or end of a word.

Parameters

TInt& aPos A valid document position from which to scan. On return, contains the new document position. TUint& aScanMask The scan mask to use. See the scanning enumeration defined in class CPlainText.

Return value

TInt The number of characters skipped to reach the new document position. Notes: If the scan passes the end of text delimiter, on return, aPos is set to EScanEndOfData (= – 1) and the function’s return value indicates the number of characters skipped in passing the end of text delimiter.

virtual TInt ScanParas(TInt& aPos,TUint& aScanMask)const;

Description

Scans the text from a specified document position to a location determined by the flags specified in a bitmask. The function can scan forwards or backwards to the beginning or end of a paragraph.

Parameters

TInt& aPos A valid document position from which to scan. On return, contains the new document position. TUint& aScanMask The scan mask to use. See the scanning enumeration defined in class CPlainText.

Return value

TInt The number of characters skipped to reach the new document position. Notes: If the scan passes the end of text delimiter, on return, aPos is set to EScanEndOfData (= – 1) and the function’s return value indicates the number of characters skipped in passing the end of text delimiter.

virtual TInt ToParagraphStart(TInt& aPos)const = 0;

Description

Updates a document position to the start of the paragraph.

Parameters

TInt& aPos Initially specifies a valid document position. On return, set to the document position of the first character in the paragraph.

Return value

TInt The number of characters skipped in scanning to the start of the paragraph.

virtual void GetWordInfo(TInt aCurrentPos,TInt& aStartPos,TInt& aLength, TBool aPictureIsDelimiter,TBool aPunctuationIsDelimiter)const = 0;

Description

Returns the start position and length of the word that contains the specified document position.

Parameters

TInt aCurrentPos A valid document position. TInt& aStartPos On return, the document position of the first character in the word containing document position aCurrentPos. TInt& aLength On return, the length of the word containing document position aCurrentPos. Does not include the trailing word delimiter character. TBool aPictureIsDelimiter Specifies whether picture characters should be considered to be word delimiters. For example, this value might be EFalse when navigating a document, but ETrue when carrying out spell checking. TBool aPunctuationIsDelimiter Specifies whether puncutation characters should be considered to be word delimiters.

TBool HasChanged()const;

Description

Tests whether the editable text object has been changed by an operation on it, as set by SetHasChanged().

Return value

TBool ETrue if a change has occurred to the text object. EFalse if there has been no change.

virtual void SetHasChanged(TBool aHasChanged);

Description

Sets whether a change has occurred to the editable text object. This is called by functions which change the text object in some way.

Parameters

TBool aHasChanged ETrue if a change has occurred to the text object. EFalse if no change has occurred.

TDocumentStorage

Description

Storage type

EFlatStorage Storage uses a flat buffer (CBufFlat). ESegmentedStorage Storage uses a segmented buffer (CBufSeg).

Anonymous

Description

Miscellaneous constants.

EDefaultTextGranularity Granularity of the buffer, default 256 characters.

Anonymous

Description

Miscellaneous constants.

EParagraphDelimiter Paragraph delimiter. ELineBreak Forced line break. EPageBreak New page. ETabCharacter Tab stop. ENonBreakingTab Non-breaking tab stop (ensures that the words on either side of the tab stop remain on the same line). ENonBreakingHyphen A hard (non-breaking) hyphen. EPotentialHyphen A soft hyphen (ensures that a hyphen followed by a new line will be inserted at that point should a line break be required anywhere within the word). ENonBreakingSpace A hard (non-breaking) space. EPictureCharacter Represents a picture inserted into the text object. EVisibleSpaceCharacter Visible space character.