Class CPlainText

class CPlainText : public CEditableText;

Description

Stores and manipulates plain text.

Plain text cannot be displayed, so this class provides no support for formatting. It is purely an in-memory buffer for text, and provides services that act upon it. These services include the following: import from and export to streams, optionally translating between Unicode and other encodings; reading and writing of field data; extraction of text; finding word and paragraph boundaries.

The type and size of in-memory buffer can be specified upon object construction. However, if no specification is provided a buffer is provided with default settings. There are two types of storage buffer: segmented buffers and flat buffers. The default buffer for plain text is segmented (CBufSeg). This is most efficient when a large quantity of text is to be stored, or will have a large dynamic range. A flat buffer (CBufFlat) is most appropriate for storing small quantities of text of bounded length. For most uses, however, a segmented buffer is sufficient.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CEditableText - An abstract base class which defines the behaviour common to all editable text classes

• CPlainText - Stores and manipulates plain text

Members

Defined in CPlainText:
CPlainText(), CharPosOfParagraph(), ComponentInfo(), ConstructL(), ConstructL(), ConsumeAdornmentL(), ConvertAllFieldsToText(), ConvertFieldToText(), CopyToStoreL(), DeleteL(), DoConstructL(), DoExternalizeFieldDataL(), DoExternalizePlainTextL(), DoInternalizeFieldDataL(), DoInternalizePlainTextL(), DoPtDelete(), DoPtInsertL(), DocumentLength(), EBiggestCharacterPaste, EExcludeInlineEditedText, EExtractAll, EExtractVisible, EImportBufSize, EOrganiseByLine, EOrganiseByParagraph, EScanBackwards, EScanEndOfData, EScanJoinDelimiters, EScanPictureIsDelimiter, EScanPunctuationIsDelimiter, EScanStayIfBoundary, EScanToUnitEnd, EScanToUnitStart, EUnitIsParagraph, EUnitIsWord, ExportAsTextL(), ExportTextL(), ExportTextL(), ExtendedInterface(), ExternalizeFieldDataL(), ExternalizeL(), ExternalizePlainTextL(), ExternalizePlainTextNoLengthCountL(), Extract(), Extract(), ExtractSelectively(), FieldCount(), FieldFactory(), FindFields(), FindFields(), GetWordInfo(), ImportTextFileL(), ImportTextL(), ImportTextL(), InsertFieldL(), InsertL(), InsertL(), InternalizeFieldDataL(), InternalizeL(), InternalizePlainTextL(), InternalizePlainTextL(), NewL(), NewL(), NewTextFieldL(), PageContainingPos(), ParagraphCount(), ParagraphNumberForPos(), PasteFromStoreL(), PtInsertL(), Read(), Read(), RemoveField(), Reset(), RestoreComponentsL(), RestoreFieldComponentsL(), SScanData, ScanParas(), ScanWords(), SetFieldFactory(), SetPageTable(), StoreComponentsL(), StoreFieldComponentsL(), TImportExportParam, TImportExportResult, TScanDataEnd, TTextOrganisation, TUnitOfText, TextField(), ToParagraphStart(), UidFromStreamL(), UpdateAllFieldsL(), UpdateFieldL(), WordCount(), anonymous, anonymous, anonymous, iByteStore, iFieldFactory, iFieldSet, iPageTable, ~CPlainText()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CEditableText:
EApostrophe, EBullet, EByteOrderMark, EDefaultTextGranularity, EEllipsis, EFlatStorage, EHyphen, EHyphenMinus, ELeftDoubleQuote, ELeftSingleQuote, ELineBreak, ENonBreakingHyphen, ENonBreakingSpace, EPageBreak, EParagraphDelimiter, EPictureCharacter, EPotentialHyphen, EReversedByteOrderMark, ERightDoubleQuote, ERightSingleQuote, ESegmentedStorage, ESpace, ETabCharacter, EZeroWidthNoBreakSpace, GetLengthOfInlineText(), GetPositionOfInlineTextInDocument(), HasChanged(), OverrideFormatOfInlineTextIfApplicable(), RestoreL(), SetHasChanged(), StoreL(), TDocumentStorage, iHasChanged

static IMPORT_C CPlainText *NewL(TDocumentStorage aStorage=ESegmentedStorage, TInt aDefaultTextGranularity=EDefaultTextGranularity);

Description

Allocates and constructs a plain text object overloaded function.

The text object's contents may be restored from a stream store. If the text object supports fields, a field factory should be specified.

Parameters

TDocumentStorage aStorage The type of in-memory buffer to use. Defaults to ESegmentedStorage. TInt aDefaultTextGranularity Specifies the granularity of the in-memory buffer. Default is EDefaultTextGranularity bytes (=256).

Return value

CPlainText * Pointer to the new plain text object.

static IMPORT_C CPlainText *NewL(const CStreamStore &aStore, TStreamId aStreamId, MTextFieldFactory *aFieldFactory=0, TDocumentStorage aStorage=ESegmentedStorage);

Description

Returns a handle to a new instance of this class, restored from the specified read stream.

Parameters

const CStreamStore &aStore TStreamId aStreamId MTextFieldFactory *aFieldFactory TDocumentStorage aStorage

Return value

CPlainText *

virtual IMPORT_C ~CPlainText();

Description

The destructor frees the object's text storage and field set, prior to its destruction.

protected: IMPORT_C CPlainText();

Description

protected: IMPORT_C void ConstructL(TDocumentStorage aStorage=ESegmentedStorage, TInt aDefaultTextGranularity=EDefaultTextGranularity);

Description

Allocates storage of CBufFlat or CBufSeg, according to the parameter aStorage. Creates & initializes the field set.

Parameters

TDocumentStorage aStorage TInt aDefaultTextGranularity

protected: IMPORT_C void ConstructL(const CStreamStore &aStore, TStreamId aStreamId, MTextFieldFactory *aFieldFactory, TDocumentStorage aStorage=ESegmentedStorage);

Description

Allocates storage of CBufFlat or CBufSeg, according to the parameter aStorage, restoring contents from the specified read-stream aStream.

Parameters

const CStreamStore &aStore TStreamId aStreamId MTextFieldFactory *aFieldFactory TDocumentStorage aStorage

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

Description

Stores the plain text object's components to the stream store specified.

Parameters

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

virtual IMPORT_C void RestoreComponentsL(const CStreamStore &aStore);

Description

Restores the plain text object's field set from a stream store.

Parameters

const CStreamStore &aStore The stream store from which the field set is restored.

virtual IMPORT_C void ExternalizeL(RWriteStream &aStream) const;

Description

Externalises a plain text object to a write stream. The presence of this function means that the standard templated operator<<() (defined in s32strm.h) is available to externalise objects of this class.

Parameters

RWriteStream &aStream Stream to which the object should be externalised.

virtual IMPORT_C void InternalizeL(RReadStream &aStream);

Description

Internalises the text object's text content and field set from a read stream. The presence of this function means that the standard templated operator>>() (defined in s32strm.h) is available to internalise objects of this class. InternalizeL() has construct rather than assignment semantics. You should not use it for fully initialised objects.

Parameters

RReadStream &aStream Stream from which the object should be internalised.

IMPORT_C void ExternalizePlainTextL(RWriteStream &aStream) const;

Description

Externalises the plain text object's text content (preceded by a length count) to a write stream.

Parameters

RWriteStream &aStream Stream to which the text content should be externalised.

IMPORT_C void InternalizePlainTextL(RReadStream &aStream);

Description

Internalises an empty text object's text content from a read stream overloaded function.

This function has construct rather than assignment semantics. You should not use it for fully initialised objects.NoteThe overload which takes a length argument is not intended for general use and its use is deprecated.

Parameters

RReadStream &aStream Stream from which the object should be internalised.

IMPORT_C void ExternalizePlainTextNoLengthCountL(RWriteStream &aStream) const;

Description

Externalises the plain text object's text content to a write stream.

This function differs from ExternalizePlainTextL() in that it does not precede the text content with a length count. This function is not intended for general use and is deprecated.

Parameters

RWriteStream &aStream

IMPORT_C void InternalizePlainTextL(RReadStream &aStream, TInt aLength);

Description

Internalises an empty text object's text content from a read stream's overloaded function.

This function has construct rather than assignment semantics. You should not use it for fully initialised objects.

Note

The overload which takes a length argument is not intended for general use and its use is deprecated.

Parameters

RReadStream &aStream Stream from which the object should be internalised. TInt aLength Indicates the number of characters which should be read, after expansion from their compressed format.

IMPORT_C void ImportTextL(TInt aPos, RReadStream &aInput, TTextOrganisation aTextOrganisation, TInt aMaxOutputChars=KMaxTInt, TInt aMaxInputChars=KMaxTInt, TInt *aOutputChars=0,TInt *aInputChars=0);

Description

Imports plain text from a stream into this text object.

Translates line feeds in the source text according to the aTextOrganisation argument.

Parameters

TInt aPos Document position at which to insert the text. Must be a valid position, or a panic occurs. RReadStream &aInput Stream from which to read the text. TTextOrganisation aTextOrganisation If EOrganiseByLine, a single line feed or a line feed and carriage return is converted into a space character. A line feed which is followed by another line feed is converted into a paragraph delimiter. If EOrganiseByParagraph, all line feeds are converted into paragraph delimiters. TInt aMaxOutputChars The maximum number of characters to write to the text object. TInt aMaxInputChars The maximum number of characters to read from the stream. TInt *aOutputChars On return, the number of characters written to the text object. TInt *aInputChars On return, the number of characters read from the stream.

IMPORT_C void ExportTextL(TInt aPos, RWriteStream &aOutput, TTextOrganisation aTextOrganisation, TInt aMaxOutputChars=KMaxTInt, TInt aMaxInputChars=KMaxTInt, TInt aMaxLineLength=KMaxTInt, TInt *aOutputChars=0,TInt *aInputChars=0) const;

Description

Writes plain text to a stream, optionally converting it from Unicode into a foreign encoding.

Parameters

TInt aPos A document position in the source plain text object from which to start reading the text to export. RWriteStream &aOutput On return, the write stream to which the text is written. TTextOrganisation aTextOrganisation TInt aMaxOutputChars TInt aMaxInputChars TInt aMaxLineLength TInt *aOutputChars TInt *aInputChars

virtual IMPORT_C TInt ImportTextFileL(TInt aPos, const TDes &aFileName, TTextOrganisation aTextOrganisation);

Description

Imports a plain text file into this text object.

Translates non-printing characters in the source text file into Symbian OS special characters, for instance tabs are converted into CEditableText::ETabCharacters, and form feeds into CEditableText::EPageBreaks. Line feeds in the source text file are translated according to the aTextOrganisation argument.

The function leaves if there is any problem in opening the file.

Parameters

TInt aPos Document position at which to insert the text. Must be a valid position, or a panic occurs. const TDes &aFileName The name of the text file to import. TTextOrganisation aTextOrganisation If EOrganiseByLine, a single line feed or a line feed and carriage return is converted into a space character. A line feed which is followed by another line feed is converted into a paragraph delimiter. If EOrganiseByParagraph, all line feeds are converted into paragraph delimiters.

Return value

TInt The number of characters imported.

virtual IMPORT_C void ExportAsTextL(const TDes &aFileName, TTextOrganisation aTextOrganisation, TInt aMaxLineLength) const;

Description

Writes the contents of the plain text object to a text file.

The filename is given by aFileName. Any existing file with that name is replaced. A wrap width can be specified. This is only used when exporting by line (aTextOrganisation is EOrganiseByLine).

The function leaves if there is any problem in creating or replacing the file.

Parameters

const TDes &aFileName The name of the file to export the text to. If a file with this name already exists, it is replaced. Otherwise, a new file is created. TTextOrganisation aTextOrganisation Defines how to translate line delimiters. If EOrganiseByLine, lines wrap at the wrap width, as specified in aMaxLineLength. If EOrganiseByParagraph, lines do not wrap and paragraph delimiters are converted into CR/LF pairs. TInt aMaxLineLength The maximum number of characters in each line, (only relevant if the text organisation is EOrganiseByLine).

IMPORT_C void ImportTextL(TInt aPos, RReadStream &aInput, const TImportExportParam &aParam, TImportExportResult &aResult);

Description

Imports plain text from a stream into this text object, optionally converting it from a foreign encoding into Unicode.

Parameters

TInt aPos Document position at which to insert the text. Must be a valid position, or a panic occurs. RReadStream &aInput Stream from which to read the text. const TImportExportParam &aParam Import parameters, including the foreign encoding to convert from, whether to guess the foreign encoding and the maximum number of characters to import. TImportExportResult &aResult On return, contains the number of characters read and written and the foreign encoding used by the imported text.

See also:

• CPlainText::TImportExportParam
• CPlainText::TImportExportResult

IMPORT_C void ExportTextL(TInt aPos, RWriteStream &aOutput, const TImportExportParam &aParam, TImportExportResult &aResult) const;

Description

Writes plain text to a stream, optionally converting it from Unicode into a foreign encoding.

Parameters

TInt aPos A document position in the source plain text object from which to start reading the text to export. RWriteStream &aOutput On return, the write stream to which the text is written. const TImportExportParam &aParam Export parameters, including an optional foreign encoding to convert the Unicode text into, a file server connection, (this is needed for the character conversion — if not specified, one will be created), a line wrap width, and the maximum number of characters to export. TImportExportResult &aResult On return, contains the number of characters read and written.

See also:

• CPlainText::TImportExportParam
• CPlainText::TImportExportResult

IMPORT_C void StoreFieldComponentsL(CStreamStore &aStore, CStoreMap &aMap) const;

Description

Stores the plain text object's field components to a stream store.

Parameters

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

IMPORT_C void RestoreFieldComponentsL(const CStreamStore &aStore);

Description

Restores the plain text object's field set.

Parameters

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

IMPORT_C void ExternalizeFieldDataL(RWriteStream &aStream) const;

Description

Externalises the plain text object's field set.

Parameters

RWriteStream &aStream The stream to which the field set should be written.

IMPORT_C void InternalizeFieldDataL(RReadStream &aStream);

Description

Internalizes the field set.

Parameters

RReadStream &aStream The read stream from which the field set is read.

virtual IMPORT_C void Reset();

Description

Deletes all text content, formatting and fields from the document, leaving the single paragraph delimiter which terminates the text object.

virtual IMPORT_C void InsertL(TInt aPos, const TChar &aChar);

Description

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

Updates the page table.

Parameters

TInt aPos The document position at which to insert the character/descriptor. Must be valid, or a panic occurs. const TChar &aChar The character to insert.

virtual IMPORT_C void InsertL(TInt aPos, const TDesC &aBuf);

Description

Inserts the contents of aBuf into the document at position aPos.

Parameters

TInt aPos const TDesC &aBuf

virtual IMPORT_C TBool DeleteL(TInt aPos, TInt aLength);

Description

Deletes one or more characters beginning at, and including, the character at a specified document position. Updates the page table. Any fields wholly contained in the range of characters to delete are removed from the field set.

Parameters

TInt aPos The document position from which to begin deleting. Must be valid or a panic occurs. TInt aLength The number of characters to delete. Must be positive or a panic occurs. The sum of aPos and aLength must be less than the document length, or a panic occurs.

Return value

TBool Indicates whether two paragraphs have been merged together as a result of the delete, indicating that the resulting paragraph must be reformatted. Has no meaning for plain text, so always EFalse.

virtual IMPORT_C TPtrC Read(TInt aStartPos) const;

Description

Gets a read-only view of a portion of the text object.

The extent of the view is the range of characters starting at aStartPos and ending at whichever of the following document positions is reached first:

• The end of the document.

• The end of the segment if using segmented storage (the storage type is specified in the NewL().

Therefore, when using a segmented buffer to store the document, the length of the resultant view may be less than the requested length. In this case multiple calls to Read() may be necessary.

Parameters

TInt aStartPos The document position at which to begin reading. Must be valid or a panic occurs.

Return value

TPtrC Constant pointer to a section of the text object.

virtual IMPORT_C TPtrC Read(TInt aStartPos, TInt aLength) const;

Description

Gets a read-only view of a portion of the text object.

The extent of the view is the range of characters starting at aStartPos and ending at whichever of the following document positions is reached first:

• The end of the document.

• The end of the segment if using segmented storage (the storage type is specified in the NewL().

• The sum of aStartPos and (aLength-1).

Therefore, when using a segmented buffer to store the document, the length of the resultant view may be less than the requested length. In this case multiple calls to Read() may be necessary.

Parameters

TInt aStartPos The document position at which to begin reading. Must be valid or a panic occurs. TInt aLength The number of characters to read, inclusive of the character at position aStartPos.

Return value

TPtrC Constant pointer to a section of the text object.

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

Description

Copies the contents of the text object into a descriptor overloaded function. The function copies all characters from and including the document position specified, to the end of the document or the end of the range of characters, if specified.

The buffer's maximum length must be greater than or equal to the number of characters to extract, or a panic occurs.

Parameters

TDes &aBuf A buffer; on return contains the extracted text. TInt aPos The document position from which to copy. Must be valid or a panic occurs.

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

Description

Copies the contents of the text object into a descriptor-overloaded function. The function copies all characters from and including the document position specified, to the end of the document or the end of the range of characters, if specified.

The buffer's maximum length must be greater than or equal to aLength, or a panic ocurs.

Parameters

TDes &aBuf A buffer; on return contains the extracted text. TInt aPos The document position from which to copy. Must be valid or a panic occurs. TInt aLength The number of characters to copy.

IMPORT_C void ExtractSelectively(TDes &aBuf, TInt aPos, TInt aLength, TUint aFlags);

Description

Parameters

TDes &aBuf TInt aPos TInt aLength TUint aFlags

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

Description

Copies plain text including fields, if present, to the clipboard.

A panic occurs in any of the following circumstances:

aPos is invalid

aLength is invalid (zero or less)

the sum of aPos and aLength is greater than or equal to the number of characters in the document

Parameters

CStreamStore &aStore Stream store to which the text is written. CStreamDictionary &aDictionary The stream dictionary. TInt aPos The document position from which to begin copying. TInt aLength The number of characters to copy.

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

Description

Pastes plain text and fields, if present, from the clipboard into the current text object at the specified document position. The entire contents of the store are pasted.

Parameters

const CStreamStore &aStore The steam store from which to paste the text. const CStreamDictionary &aDictionary The stream dictionary. TInt aPos Document position at which to paste. Must be valid or the function raises a panic.

Return value

TInt The number of characters pasted.

IMPORT_C void SetPageTable(TPageTable *aPageTable);

Description

Links the text object to a page table. A page table is an array of integers; each integer represents the number of characters on a page. It is required for pagination. The page table is updated when changes are made to the document, e.g. after pasting from the clipboard, inserting, importing or deleting text.

The text object does not take ownership of the page table specified.

Parameters

TPageTable *aPageTable The page table to be referenced by the text object.

IMPORT_C TInt PageContainingPos(TInt aPos) const;

Description

Gets the number of the page which contains the specified document position. If no page table has been set up, the function returns a value of zero. Use SetPageTable() to set up the page table.

Parameters

TInt aPos A document position. Must be valid or a panic occurs.

Return value

TInt The page number containing document position aPos.

virtual IMPORT_C TInt DocumentLength() const;

Description

Gets the the number of characters in the text object.

Note: the count includes all non-printing characters but excludes the end of text paragraph delimiter, so that the smallest possible return value is zero.

Return value

TInt The number of characters in the text object.

virtual IMPORT_C TInt WordCount() const;

Description

Gets a count of the number of words in the text object.

Return value

TInt The number of words in the text object.

virtual IMPORT_C TInt ParagraphCount() const;

Description

Gets a count of the number of paragraphs in the text object.

Note: the paragraph delimiter which terminates every text object means this function always returns a count of at least one.

Return value

TInt The number of paragraphs contained in the text object.

virtual IMPORT_C TInt ToParagraphStart(TInt &aPos) const;

Description

Gets the document position of the start of the paragraph containing the specified document position.

Parameters

TInt &aPos A document position. Must be valid or a panic occurs. On return, contains the document position of the first character in the paragraph in which it is located.

Return value

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

virtual IMPORT_C TInt CharPosOfParagraph(TInt &aLength, TInt aParaOffset) const;

Description

Finds the length and the start position of a paragraph identified by its paragraph number the first paragraph is numbered zero.

Notes:

if aParaOffset is invalid, (equal to or greater than the total number of paragraphs), the function's return value is EScanEndOfData

Parameters

TInt &aLength On return contains the length of the specified paragraph. TInt aParaOffset The paragraph number. The first paragraph is numbered zero.

Return value

TInt The document position of the first character in the paragraph.

virtual IMPORT_C TInt ParagraphNumberForPos(TInt &aPos) const;

Description

Gets the number of the paragraph which contains a document position. Paragraph numbering begins at zero.

Parameters

TInt &aPos A document position. Must be valid or a panic occurs. On return, contains the document position of the first character in the paragraph in which it is located.

Return value

TInt The number of the paragraph containing the specified document position. The first paragraph is numbered zero.

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

Description

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

Parameters

TInt aCurrentPos A document position. Must be valid or a panic occurs. TInt &aStartPos On return, the document position of the first character in the word containing the position aCurrentPos. TInt &aLength On return, the length of the word containing document position aCurrentPos. TBool aPictureIsDelimiter ETrue if picture characters should be treated as word delimiters, false if not. For example, when navigating text, this might be EFalse, but when spell checking, it might be ETrue. TBool aPunctuationIsDelimiter ETrue if punctuation characters should be treated as word delimiters, EFalse if not.

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

Description

Scans from a document position to the beginning or end of a word. The destination is determined by a scan mask. The scan can either be forwards (the default) or backwards, and the destination may be the first or last character in the word containing the position, or the first character in the next word.

Note: If an attempt is made to scan beyond the end of text delimiter, on return, aPos is set to EScanEndOfData and the function's return value indicates the number of characters skipped in passing the end of text delimiter.

Parameters

TInt &aPos The document position from which to scan. Must be valid, or a panic occurs. On return, contains the new document position. TUint &aScanMask The scan mask. See the enumeration whose values begin with CPlainText::EScanBackwards.

Return value

TInt The number of characters skipped to reach the new document position.

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

Description

Scans from a document position to the beginning or end of a paragraph. The destination is determined by a scan mask. The scan can either be forwards (the default) or backwards, and the destination may be the first or last character in the paragraph containing the position, or the first character in the next paragraph.

Note: if an attempt is made to scan beyond the end of text delimiter, on return, aPos is set to EScanEndOfData ) and the function's return value indicates the number of characters skipped in passing the end of text delimiter.

Parameters

TInt &aPos The document position to scan from. Must be valid or a panic occurs. On return, contains the new document position. TUint &aScanMask The scan mask. See the enumeration whose values begin with CPlainText::EScanBackwards.

Return value

TInt The number of characters skipped to reach the new document position.

virtual IMPORT_C TEtextComponentInfo ComponentInfo() const;

Description

Gets information about the number of components contained in the text object. For plain text, only the field count has relevance.

Return value

TEtextComponentInfo Contains the field count.

IMPORT_C void SetFieldFactory(MTextFieldFactory *aFactory);

Description

Sets up a field factory. A field factory is an instance of a class deriving from MTextFieldFactory. It must implement a NewFieldL() function to create and return fields of the desired type. The field factory's NewFieldL() function is called by CPlainText::NewTextFieldL(). A field factory must be set up if you intend to add any fields to the text object.

Parameters

MTextFieldFactory *aFactory The field factory.

inline const MTextFieldFactory *FieldFactory() const;

Description

Gets a pointer to the field factory used by the text object. The field factory may be set up using SetFieldFactory(), or may be specified in the NewL().

Return value

const MTextFieldFactory * The field factory. NULL if no field factory has been set up.

IMPORT_C CTextField *NewTextFieldL(TUid aFieldType) const;

Description

Creates and returns a new field. Before calling this function, a field factory should have been set up, either by calling SetFieldFactory(), or by specifying one in the NewL(). The field factory's NewFieldL() function is called to create a field of the type specified in the argument. A NULL field is returned if no field factory has been set up.

Parameters

TUid aFieldType Identifies the field type.

Return value

CTextField * Pointer to the new text field. NULL if no field factory has been set up.

IMPORT_C void InsertFieldL(TInt aPos, CTextField *aField, TUid aFieldType);

Description

Inserts a field into the text object at a specified document position. creating a zero-length field record. Maintain the field set.

Note: After insertion, the field should be evaluated in order to make its contents visible; use UpdateFieldL().

Parameters

TInt aPos The document position at which to insert the field. Must be valid, or a panic occurs. CTextField *aField The field to insert, created by NewTextFieldL(). Must not be NULL, or a panic occurs. TUid aFieldType Identifies the type of field to insert. For the built in field types, see the UID values defined in flddef.h.

virtual IMPORT_C void UpdateFieldL(TInt aPos);

Description

Re-evaluates the field which covers the document position specified. Re-evaluating a field means calculating the field's new value, then inserting that value into the text object, replacing the previous value.

Notes:

fields have a maximum length of 20 characters.

the first time a field is updated, the position specified should be the position at which the field was inserted.

Parameters

TInt aPos A document position in the field to be updated. Must be a valid position, or a panic occurs.

IMPORT_C void UpdateAllFieldsL();

Description

Re-evaluates all of the fields in the text object. Re-evaluating a field means calculating the field's new value, then inserting that value into the text object, replacing the previous value.

Note: Fields have a maximum length of 20 characters.

IMPORT_C TInt FieldCount() const;

Description

Gets a count of the number of fields in the text object's field set.

Return value

TInt The number of fields in the field set.

IMPORT_C const CTextField *TextField(TInt aPos) const;

Description

Returns a pointer to the field located at the specified document position.

Parameters

TInt aPos A document position within the field. Must be a valid document position, or a panic occurs.

Return value

const CTextField * Pointer to the field which covers position aPos. NULL if there is no field at the specified position.

IMPORT_C TBool FindFields(TInt aPos) const;

Description

Parameters

TInt aPos

Return value

TBool

IMPORT_C TBool FindFields(TFindFieldInfo &aInfo, TInt aPos, TInt aRange=0) const;

Description

Tests whether a document position is located within a field overloaded function.

The second overload extracts information about all fields located within a range of characters.

Parameters

TFindFieldInfo &aInfo On return, contains the number of fields fully or partially within the range of characters specified and the start position and length of the first field found. TInt aPos The document position. Must be valid or a panic occurs. TInt aRange The number of characters to search, beginning at aPos. Must not be negative, or a panic occurs. The sum of aPos and aRange must be less than the document length, or a panic occurs. The default range is zero. In this case the function just returns information about the single field located at the position specified.

Return value

TBool ETrue if aPos is located within a field, or if there were one or more fields found in the range. EFalse if not.

IMPORT_C TBool RemoveField(TInt aPos);

Description

Removes the field covering the document position specified from the field set, and deletes all text content associated with the field from the text object.

Parameters

TInt aPos A document position within the field to be deleted. Must be a valid position or a panic occurs.

Return value

TBool ETrue if a field was located at aPos. EFalse if no field was located at aPos.

IMPORT_C TBool ConvertFieldToText(TInt aPos);

Description

Converts the field containing the specified document position into text, leaving its current value in the text object. Does not update the field beforehand.

Parameters

TInt aPos A document position within the field to convert. Must be a valid position or a panic occurs.

Return value

TBool ETrue if there was a field located at aPos. EFalse if there was no field located at aPos.

IMPORT_C void ConvertAllFieldsToText();

Description

Removes all fields from the text object's field set, leaving their current text value in the text object. Does not update the fields beforehand.

virtual IMPORT_C void ExtendedInterface(TAny *&aInterface, TUid aInterfaceId);

Description

Returns the interface corresponding to the specified UID if it exists, or 0 if not. Overridden versions should base call rather than returning 0.

Parameters

TAny *&aInterface The interface corresponding to aInterfaceId if it is supported, or 0 if it is not TUid aInterfaceId The UID indicating the interface to return

protected: IMPORT_C void DoConstructL(TDocumentStorage aStorage, TInt aDefaultTextGranularity, MTextFieldFactory *aFieldFactory=0);

Description

Allocates storage of CBufFlat or CBufSeg, according to the parameter aStorage. Creates & initializes the field set.

Parameters

TDocumentStorage aStorage TInt aDefaultTextGranularity MTextFieldFactory *aFieldFactory

protected: IMPORT_C void PtInsertL(TInt aInsertPos, const TDesC &aBuf);

Description

Inserts the contents a aBuf into the document at position aInsertPos. Maintain field set.

Parameters

TInt aInsertPos const TDesC &aBuf

protected: IMPORT_C void DoPtInsertL(TInt aPos, const TDesC &aBuf);

Description

Inserts the contents a aBuf into the document at position aInsertPos. Maintain field set.

Parameters

TInt aPos const TDesC &aBuf

protected: IMPORT_C TBool DoPtDelete(TInt aPos, TInt aLength);

Description

Deletes aLength number of characters from the document, commencing at, and including, position aPos. The return value indicates if 2 paragraphs have been merged together as a result of the delete, indicating that the resulting paragraph must be reformatted. In global text, this clearly has no reasonable meaning, so always returns EFalse, so no reformatting occurs.

Parameters

TInt aPos TInt aLength

Return value

TBool

protected: IMPORT_C void DoExternalizeFieldDataL(RWriteStream &aStream) const;

Description

Write to the stream, the T.V. representing the field set.

Parameters

RWriteStream &aStream

protected: IMPORT_C void DoInternalizeFieldDataL(RReadStream &aStream);

Description

Read from the stream until the field data is identified, and consume it.

Parameters

RReadStream &aStream

protected: IMPORT_C void DoExternalizePlainTextL(RWriteStream &aStream) const;

Description

Write to the stream, the T.V. representing the plain text.

Parameters

RWriteStream &aStream

protected: IMPORT_C void DoInternalizePlainTextL(RReadStream &aStream);

Description

Read from the stream until the character data is found, and consume it.

Parameters

RReadStream &aStream

protected: static inline void ConsumeAdornmentL(RReadStream &aStream);

Description

Parameters

RReadStream &aStream

protected: static inline TUid UidFromStreamL(RReadStream &aStream);

Description

Parameters

RReadStream &aStream

Return value

TUid

class TImportExportParam;

Description

Parameters for importing or exporting text using CPlainText::ImportTextL() or CPlainText::ExportTextL().

Members

Defined in CPlainText::TImportExportParam:
TImportExportParam(), iFileSession, iForeignEncoding, iGuessForeignEncoding, iInputInternal, iMaxInputChars, iMaxLineLength, iMaxOutputChars, iOrganisation, iOutputInternal, iReserved

Construction and destruction

---

TImportExportParam()

inline TImportExportParam();

Description

Default constructor. All member data is assigned default values. For details, see the member data.

Member data

---

iOrganisation

TTextOrganisation iOrganisation;

Description

Controls how line delimiters are translated. By default, EOrganiseByParagraph.

See also:

• CPlainText::TTextOrganisation

---

iMaxOutputChars

TInt iMaxOutputChars;

Description

The maximum number of characters to write to the stream (when exporting) or to write to the text object (when importing). By default, KMaxTInt.

---

iMaxInputChars

TInt iMaxInputChars;

Description

The maximum number of characters to read from the stream (when importing) or to read from the text object (when exporting). By default, KMaxTInt.

---

iMaxLineLength

TInt iMaxLineLength;

Description

The wrap width as a number of characters.

Only relevant when exporting by line, (iOrganisation is CPlainText::EOrganiseByLine). Not used in CPlainText::ImportTextL(). By default, KMaxTInt.

---

iOutputInternal

TBool iOutputInternal;

Description

If ETrue, output is in internal format, so is written according to native endianness. Used in CPlainText::ExportTextL(). By default, EFalse.

---

iInputInternal

TBool iInputInternal;

Description

If ETrue, input is in internal format, so is read according to native endianness. Used in CPlainText::ImportTextL(). By default, EFalse.

---

iForeignEncoding

TUint iForeignEncoding;

Description

The identifier of the foreign character set encoding to be used to convert from or to.

Not used if iGuessForeignEncoding is true. If conversion to/from iForeignEncoding is not available on the phone, the function leaves with KErrNotSupported. By default, zero.

---

iGuessForeignEncoding

TBool iGuessForeignEncoding;

Description

If ETrue, an attempt is made to guess the encoding of the foreign text being imported before converting it into Unicode. Used in CPlainText::ImportTextL(). If EFalse, the value specified in iForeignEncoding (if any) is used. If none of the available character conversion plug-ins on the phone return a confidence level greater than 50%, CPlainText::ImportTextL() leaves with KErrNotSupported. By default, false.

---

iFileSession

RFs * iFileSession;

Description

If non-null, a connected file server session used to load character conversion data. Only relevant if the text needs to be converted to or from Unicode. By default, null.

---

iReserved

TUint iReserved;

Description

class TImportExportResult;

Description

Results of importing or exporting text using CPlainText::ImportTextL() or CPlainText::ExportTextL().

Members

Defined in CPlainText::TImportExportResult:
TImportExportResult(), iForeignEncoding, iInputChars, iOutputChars, iReserved

Construction and destruction

---

TImportExportResult()

inline TImportExportResult();

Description

Default constructor. All member data is initialised to zero.

Member data

---

iOutputChars

TInt iOutputChars;

Description

The number of characters written to the stream (when exporting) or written to this text object (when importing).

---

iInputChars

TInt iInputChars;

Description

The number of characters read from the stream (when importing) or read from this text object (when exporting).

---

iForeignEncoding

TUint iForeignEncoding;

Description

The identifier for the character set encoding selected when importing text whose encoding is guessed (iGuessForeignEncoding was true).

---

iReserved

TUint iReserved;

Description

protected: struct SScanData;

Description

Members

Defined in CPlainText::SScanData:
EInsideUnit, EIsDelimiter, EStopBegin, EStopEnd, anonymous, buf, currentSegLen, delta, oldPos, pos, scanMask, totalBufLen

Member enumerations

---

Enum anonymous

n/a

Description

EInsideUnit EStopEnd EStopBegin EIsDelimiter

Member data

---

pos

TInt pos;

Description

---

oldPos

TInt oldPos;

Description

---

buf

TText * buf;

Description

---

currentSegLen

TInt currentSegLen;

Description

---

totalBufLen

TInt totalBufLen;

Description

---

delta

TInt delta;

Description

---

scanMask

TUint32 scanMask;

Description

TTextOrganisation

Description

Line delimiter translation.

EOrganiseByParagraph When importing text from a text file, all line feeds are converted into paragraph delimiters. When exporting text to a text file, lines do not wrap and paragraph delimiters are converted into CR/LF pairs. EOrganiseByLine When importing text from a text file, a single line feed or a line feed followed by a carriage return is converted into a space character. A line feed which is followed by another line feed is converted into a CEditableText::EParagraphDelimiter. When exporting text to a text file, lines wrap at the specified wrap width and paragraph delimiters are converted into CR/LFs pairs.

n/a

Description

Scan mask values.

EScanBackwards Scan direction is backwards. The default is forwards. EScanStayIfBoundary If the current document position is a word or paragraph boundary, no scan occurs. EScanToUnitStart Scan to the first character in the word or paragraph. EScanToUnitEnd Scan to the last character in the word or paragraph. EScanJoinDelimiters Treat adjacent word or paragraph delimiters as a single delimiter. Required when performing a word count, for example. EScanPictureIsDelimiter Picture characters are considered to be word delimiters. EScanPunctuationIsDelimiter Punctuation characters, except hyphens and apostrophes, are considered to be word delimiters.

TScanDataEnd

Description

Used in text scanning functions to indicate the end of the document has been passed.

EScanEndOfData Indicates that a scan has passed the end of text paragraph delimiter.

n/a

Description

EExtractAll EExtractVisible EExcludeInlineEditedText

protected: n/a

Description

EImportBufSize EBiggestCharacterPaste

protected: TUnitOfText

Description

EUnitIsWord EUnitIsParagraph

protected: CBufBase * iByteStore;

Description

protected: TSwizzle< CTextFieldSet > iFieldSet;

Description

protected: TPageTable * iPageTable;

Description

protected: MTextFieldFactory * iFieldFactory;

Description