Class CPlainText

CPlainText

Support

Supported from 5.0

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 that all classes in the editable text class hierarchy (CPlainText, CGlobalText and CRichText) must provide CPlainText Stores and manipulates plain text

Defined in CPlainText:
Anonymous, CharPosOfParagraph(), ComponentInfo(), ConvertAllFieldsToText(), ConvertFieldToText(), CopyToStoreL(), DeleteL(), DocumentLength(), EOrganiseByLine, EOrganiseByParagraph, EScanBackwards, EScanEndOfData, EScanJoinDelimiters, EScanPictureIsDelimiter, EScanPunctuationIsDelimiter, EScanStayIfBoundary, EScanToUnitEnd, EScanToUnitStart, ExportAsTextL(), ExportTextL(), ExternalizeFieldDataL(), ExternalizeL(), ExternalizePlainTextL(), ExternalizePlainTextNoLengthCountL(), Extract(), FieldCount(), FieldFactory(), FindFields(), GetWordInfo(), ImportTextFileL(), ImportTextL(), InsertFieldL(), InsertL(), InternalizeFieldDataL(), InternalizeL(), InternalizePlainTextL(), NewL(), NewTextFieldL(), PageContainingPos(), ParagraphCount(), ParagraphNumberForPos(), PasteFromStoreL(), Read(), RemoveField(), Reset(), RestoreComponentsL(), RestoreFieldComponentsL(), ScanParas(), ScanWords(), SetFieldFactory(), SetPageTable(), StoreComponentsL(), StoreFieldComponentsL(), TImportExportParam, TImportExportResult, TScanDataEnd, TTextOrganisation, TextField(), ToParagraphStart(), UpdateAllFieldsL(), UpdateFieldL(), WordCount(), ~CPlainText()

Inherited from CBase:
operator new()

Inherited from CEditableText:
EDefaultTextGranularity, EFlatStorage, ELineBreak, ENonBreakingHyphen, ENonBreakingSpace, ENonBreakingTab, EPageBreak, EParagraphDelimiter, EPictureCharacter, EPotentialHyphen, ESegmentedStorage, ETabCharacter, EVisibleSpaceCharacter, HasChanged(), RestoreL(), SetHasChanged(), StoreL(), TDocumentStorage

static CPlainText* NewL(TDocumentStorage aStorage=ESegmentedStorage,TInt aDefaultTextGranularity=EDefaultTextGranularity);
static CPlainText* NewL(const CStreamStore& aStore,TStreamId aStreamId,
MTextFieldFactory* aFieldFactory=NULL,TDocumentStorage aStorage=ESegmentedStorage);

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=ESegmentedStorage The type of in-memory buffer to use. Defaults to ESegmentedStorage. TInt aDefaultTextGranularity=EDefaultTextGranularity Specifies the granularity of the in-memory buffer. Default is EDefaultTextGranularity bytes (=256). const CStreamStore& aStore Stream store from which the object is restored. TStreamId aStreamId ID of the stream store. MTextFieldFactory* aFieldFactory=NULL Pointer to a field factory. A field factory must be provided if the text object supports the addition of fields.

Return value

CPlainText* Pointer to the new plain text object.

virtual ~CPlainText();

Description

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

virtual 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.

virtual 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 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 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.

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

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.

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.

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.

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.

virtual 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 EPOC 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.

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

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 = KMaxTInt The maximum number of characters to write to the text object. TInt aMaxInputChars = KMaxTInt The maximum number of characters to read from the stream. TInt* aOutputChars = NULL On return, the number of characters written to the text object. TInt* aInputChars = NULL On return, the number of characters read from the stream.

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

Support

Supported from 6.1

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

virtual 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).

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

Description

Writes plain text to a stream.

A wrap width can be specified. This is only relevant when exporting by line, (aTextOrganisation is CPlainText::EOrganiseByLine). When the line length reaches the wrap width, a carriage return/line feed is inserted. When exporting text by paragraph, the wrap width is disregarded.

Parameters

TInt aPos A document position in this 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 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 a CR/LF pair. TInt aMaxOutputChars = KMaxTInt The maximum number of characters to write to the stream — you may have a limited size buffer. By default, no limit. TInt aMaxInputChars = KMaxTInt The maximum number of characters to read from this plain text object. By default, no limit. TInt aMaxLineLength = KMaxTInt The maximum length of each line in characters, (only relevant if the text organisation is EOrganiseByLine). By default, no limit. TInt* aOutputChars = NULL On return, the number of characters written to the stream. TInt* aInputChars = NULL On return, the number of characters read from the source plain text object.

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

Support

Supported from 6.1

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

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.

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.

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.

void InternalizeFieldDataL(RReadStream& aStream);

Description

Internalizes the field set.

Parameters

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

virtual 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 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.

virtual 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 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 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 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 (= – 1) 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 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 (= – 1) 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 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 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 True 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 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.

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.

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 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 (= – 1)

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 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.

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.

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.

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.

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

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

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.

TBool FindFields(TInt aPos) const;
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

TInt aPos The document position. Must be valid or a panic occurs. 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 aRange=0 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.

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

Description

Inserts a field into the text object at a specified document position.

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.

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.

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.

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

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

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.

virtual 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.

virtual void Reset();

Description

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

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

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. const TDesC& aBuf The descriptor to insert.

virtual 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 TPtrC Read(TInt aStartPos)const;
virtual 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())

• if aLength is specified, 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 If specified, 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 void Extract(TDes& aBuf,TInt aPos=0)const;
virtual 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.

Notes:

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

For the three parameter variant, 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=0 The document position from which to copy. Must be valid or a panic occurs. TInt aLength The number of characters to copy.

TImportExportParam

Support

Supported from 6.1

Description

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

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

Construction

TImportExportParam()

---

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 true, output is in internal format, so is written according to native endianness. Used in CPlainText::ExportTextL(). By default, false.

iInputInternal

---

TBool iInputInternal

Description

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

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 device, the function leaves with KErrNotSupported. By default, zero.

See also:

• Character set identifiers

iGuessForeignEncoding

---

TBool iGuessForeignEncoding

Description

If true, an attempt is made to guess the encoding of the foreign text being imported before converting it into Unicode. Used in CPlainText::ImportTextL(). If false, the value specified in iForeignEncoding (if any) is used. If none of the available character conversion plug-ins on the device 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.

TImportExportResult

Support

Supported from 6.1

Description

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

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

Construction

TImportExportResult()

---

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).

See also:

• Character set identifiers

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.

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.