Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: TXTRICH.H
Link against: etext.lib

Class CRichText

class CRichText : public CGlobalText;

Description

Text with rich formatting.

In rich text, each paragraph can have a different paragraph format, and each character can have a different character format.

All formatting in a rich text object is based on a global character and paragraph format layer, and a chain of layers on which they may be based. In case of conflict, upper layers override lower layers. These two format layers are specified on construction, and are not owned by the text object. Additional formatting may then be added to any portion of the text. This is called specific formatting and in case of conflict, it overrides the formatting in the global layers. Specific formatting is owned by the text object. So, the effective formatting of a rich text object may be composed of specific formatting and formatting specified in a chain of format layers.

Rich text supports styles. A style is a named set of paragraph and character format attributes. Styles are stored in a list which is passed to the rich text object on construction, or which is assigned to the object after construction. Styles can be appended to and removed from the list and existing styles can be modified. Only paragraph styles are supported. This means that styles are applied to entire paragraphs, although both character and paragraph format attributes may be set in the style.

Rich text also supports object embedding. Embedded objects are represented in rich text by CPicture-derived objects. A rich text object which supports the display of pictures needs to be supplied with a picture factory.

Derivation

Members

Defined in CRichText:
ActivateDefaultParserL(), ActivateParserL(), AppendParagraphL(), AppendTakingSolePictureOwnershipL(), ApplyCharFormatL(), ApplyParaFormatL(), ApplyParagraphStyleL(), CRichText(), CancelInsertCharFormat(), CharPosOfParagraph(), ComponentInfo(), ConstructL(), ConstructL(), CopyComponentsL(), CopyToStoreL(), CopyToStreamL(), CopyToStreamL(), CursorOverTag(), DeactivateParser(), DeactivateParserDefaults(), DelSetInsertCharFormatL(), DeleteFromParagraph(), DeleteL(), DeleteParagraph(), DetachFromStoreL(), DetachFromStoreL(), DoExternalizeMarkupDataL(), DoExternalizeStyleDataL(), DoInternalizeMarkupDataL(), DoInternalizeStyleDataL(), DropPictureOwnership(), EDelimiterCharacterLength, EMultiPara, ESinglePara, ExtendedInterface(), ExternalizeL(), ExternalizeMarkupDataL(), ExternalizeStyleDataL(), GetCharFormat(), GetChars(), GetParaFormatL(), GetParagraphFormatL(), GetPictureSizeInTwips(), GetSpecificCharFormat(), GetSpecificCharFormatRight(), GetSpecificParagraphFormatL(), HasMarkupData(), InsertL(), InsertL(), InsertL(), InternalizeL(), InternalizeMarkupDataL(), InternalizeStyleDataL(), NewL(), NewL(), NewL(), NewL(), NotifyStyleChangedL(), NotifyStyleDeletedL(), ParagraphCount(), ParagraphNumberForPos(), ParagraphStyle(), ParseText(), PasteFromStoreL(), PasteFromStoreL(), PictureCount(), PictureFactory(), PictureHandleL(), PictureHeader(), PositionOfNextTag(), PositionOfNextTag(), PositionOfPrevTag(), PositionOfPrevTag(), RemoveSpecificCharFormatL(), RemoveSpecificParaFormatL(), Reset(), RestoreComponentsL(), RestoreWithStyleListL(), RtInsertL(), SetEditObserver(), SetHasChanged(), SetInsertCharFormatL(), SetPictureFactory(), SetStyleListExternallyOwned(), SetStyleListExternallyOwned(), StoreComponentsL(), StoreMarkupComponentsL(), StoreResolver(), StyleCount(), StyleList(), StyleListExternallyOwned(), StyleListPresent(), TParaType, UpdateFieldL(), anonymous, ~CRichText()

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(), StoreL(), TDocumentStorage, iHasChanged

Inherited from CGlobalText:
CancelSelectLabel(), EnquirePageBreak(), GlobalCharFormatLayer(), GlobalParaFormatLayer(), LdDocumentLength(), LdToParagraphStart(), SelectParagraphLabel(), SetGlobalCharFormat(), SetGlobalParaFormat(), iGlobalCharFormatLayer, iGlobalParaFormatLayer

Inherited from CPlainText:
ConsumeAdornmentL(), ConvertAllFieldsToText(), ConvertFieldToText(), 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(), ExternalizeFieldDataL(), ExternalizePlainTextL(), ExternalizePlainTextNoLengthCountL(), Extract(), ExtractSelectively(), FieldCount(), FieldFactory(), FindFields(), GetWordInfo(), ImportTextFileL(), ImportTextL(), InsertFieldL(), InternalizeFieldDataL(), InternalizePlainTextL(), NewTextFieldL(), PageContainingPos(), PtInsertL(), Read(), RemoveField(), RestoreFieldComponentsL(), SScanData, ScanParas(), ScanWords(), SetFieldFactory(), SetPageTable(), StoreFieldComponentsL(), TImportExportParam, TImportExportResult, TScanDataEnd, TTextOrganisation, TUnitOfText, TextField(), ToParagraphStart(), UidFromStreamL(), UpdateAllFieldsL(), WordCount(), iByteStore, iFieldFactory, iFieldSet, iPageTable

Inherited from MLayDoc:
EForceLoadFalse, EForceLoadTrue, TForcePictureLoad

See also:


Construction and destruction


NewL()

static IMPORT_C CRichText *NewL(const CParaFormatLayer *aGlobalParaLayer, const CCharFormatLayer *aGlobalCharLayer, TDocumentStorage aStorage=ESegmentedStorage, TInt aDefaultTextGranularity=EDefaultTextGranularity, TParaType aParaType=EMultiPara);

Description

Allocates and constructs an empty rich text object, with a global character and paragraph format layer. A single end-of-document delimiter is inserted. No style list is allocated.

Parameters

const CParaFormatLayer *aGlobalParaLayer

Pointer to the paragraph format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

const CCharFormatLayer *aGlobalCharLayer

Pointer to the character format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

TDocumentStorage aStorage

The type of in-memory buffer to use. Defaults to ESegmentedStorage which should rarely need to be changed.

TInt aDefaultTextGranularity

Specifies the granularity of the in-memory buffer. Default is EDefaultTextGranularity bytes (=256), and this should rarely need to be changed.

TParaType aParaType

This argument indicates whether you are using a single paragraph or multiple paragraphs, and thus affects the granularity of aggregate objects used internally for storing paragraph attributes. Default = EMultiPara.

Return value

CRichText *

The rich text object.


NewL()

static IMPORT_C CRichText *NewL(const CParaFormatLayer *aGlobalParaLayer, const CCharFormatLayer *aGlobalCharLayer, const CStyleList &aStyleList, TDocumentStorage aStorage=ESegmentedStorage, TInt aDefaultTextGranularity=EDefaultTextGranularity, TParaType aParaType=EMultiPara);

Description

Allocates and constructs an empty rich text object which supports styles. It is constructed with a global character and paragraph format layer and a style list. A single end-of-document delimiter is inserted. The rich text object takes ownership of the style list.

Note:

A rich text object not constructed with a style list may still use styles, by calling SetStyleListExternallyOwned() at any time after construction. In this case, the rich text object does not own the style list.

Parameters

const CParaFormatLayer *aGlobalParaLayer

Pointer to the paragraph format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

const CCharFormatLayer *aGlobalCharLayer

Pointer to the character format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

const CStyleList &aStyleList

Style list. Holds the set of paragraph styles which can be used in the rich text object.

TDocumentStorage aStorage

The type of in-memory buffer to use. Defaults to ESegmentedStorage which should rarely need to be changed.

TInt aDefaultTextGranularity

Specifies the granularity of the in-memory buffer. Default is EDefaultTextGranularity bytes (=256), and this should rarely need to be changed.

TParaType aParaType

This argument indicates whether you are using a single paragraph or multiple paragraphs, and thus affects the granularity of aggregate objects used internally for storing paragraph attributes. Default = EMultiPara.

Return value

CRichText *

The new rich text object.


NewL()

static IMPORT_C CRichText *NewL(const CStreamStore &aStore, TStreamId aStreamId, const CParaFormatLayer *aGlobalParaLayer, const CCharFormatLayer *aGlobalCharLayer, MTextFieldFactory *aFieldFactory=0, TDocumentStorage aStorage=ESegmentedStorage);

Description

Allocates and constructs a rich text object with a field factory. Its text content is internalized from a stream store.

Note:

A rich text object not constructed with a field factory may still support the addition of fields, by calling SetFieldFactory(), defined in the base class CPlainText.

Parameters

const CStreamStore &aStore

Stream store from which the object is restored.

TStreamId aStreamId

ID of the stream store.

const CParaFormatLayer *aGlobalParaLayer

Pointer to the paragraph format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

const CCharFormatLayer *aGlobalCharLayer

Pointer to the character format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

MTextFieldFactory *aFieldFactory

Pointer to a field factory. A field factory must be provided if the text object supports fields.

TDocumentStorage aStorage

The type of in-memory buffer to use. Defaults to ESegmentedStorage which should rarely need to be changed.

Return value

CRichText *

The new rich text object.


NewL()

static IMPORT_C CRichText *NewL(const CStreamStore &aStore, TStreamId aStreamId, const CParaFormatLayer *aGlobalParaLayer, const CCharFormatLayer *aGlobalCharLayer, MPictureFactory *aPictureFactory, MRichTextStoreResolver *aStoreResolver, MTextFieldFactory *aFieldFactory=0, TDocumentStorage aStorage=ESegmentedStorage);

Description

Allocates and constructs a rich text object with a field factory and a picture factory. Its text content is internalized from a stream store.

Note:

A rich text object not constructed with a field factory may still support the addition of fields, by calling SetFieldFactory(), defined in the base class CPlainText.

Parameters

const CStreamStore &aStore

Stream store from which the object is restored.

TStreamId aStreamId

ID of the stream store.

const CParaFormatLayer *aGlobalParaLayer

Pointer to the paragraph format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

const CCharFormatLayer *aGlobalCharLayer

Pointer to the character format layer referenced by the rich text object. Must not be NULL, or a panic occurs.

MPictureFactory *aPictureFactory

The picture factory. This is needed to load pictures into memory, (see PictureHandleL()). If a store resolver is specified (not NULL), then a factory must also be specified, or a panic occurs.

MRichTextStoreResolver *aStoreResolver

A store resolver. This determines which file store the picture is stored in. It is used to get from a reference to an embedded picture within a CRichText object to the actual picture itself. Picture loading is done by the picture factory.

MTextFieldFactory *aFieldFactory

Pointer to a field factory. A field factory must be provided if the text object supports fields.

TDocumentStorage aStorage

The type of in-memory buffer to use. Defaults to ESegmentedStorage which should rarely need to be changed.

Return value

CRichText *

The new rich text object.


~CRichText()

virtual IMPORT_C ~CRichText();

Description

The destructor frees all resources owned by the rich text object, prior to its destruction.


CRichText()

protected: IMPORT_C CRichText(const CParaFormatLayer *aGlobalParaLayer, const CCharFormatLayer *aGlobalCharLayer, CStyleList *aStyleList=0);

Description

Parameters

const CParaFormatLayer *aGlobalParaLayer

const CCharFormatLayer *aGlobalCharLayer

CStyleList *aStyleList


ConstructL()

protected: IMPORT_C void ConstructL(TDocumentStorage aStorage, TInt aDefaultTextGranularity, TParaType aParaType);

Description

Parameters

TDocumentStorage aStorage

TInt aDefaultTextGranularity

TParaType aParaType


ConstructL()

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

Description

Parameters

const CStreamStore &aStore

TStreamId aStreamId

MPictureFactory *aFactory

MRichTextStoreResolver *aStoreResolver

MTextFieldFactory *aFieldFactory

TDocumentStorage aStorage

[Top]


Member functions


RestoreWithStyleListL()

IMPORT_C void RestoreWithStyleListL(const CStreamStore &aStore, TStreamId aStreamId, const CStyleList &aExternalStyleList);

Description

Restores a rich text object, including all of its components and an externally owned style list, from a stream store.

Parameters

const CStreamStore &aStore

Stream store from which the object is restored.

TStreamId aStreamId

ID of the stream store.

const CStyleList &aExternalStyleList

An externally owned style list.


StoreComponentsL()

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

Description

Stores the rich text object's components (field set, style list, formatting and pictures) to the stream store specified.

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 the deferred loading of pictures in rich text.


RestoreComponentsL()

virtual IMPORT_C void RestoreComponentsL(const CStreamStore &aStore);

Description

Restores the rich text object's components (field set, style list, formatting and pictures) from a stream store.

Parameters

const CStreamStore &aStore

The stream store from which the text object's components are restored.


ExternalizeL()

virtual IMPORT_C void ExternalizeL(RWriteStream &aStream) const;

Description

Externalises the rich text object and all of its components (field set, style list, rich text formatting, pictures) to a read stream. The presence of this function means that the standard templated operator<<() (defined in s32strm.h) is available to externalise objects of this class.

Notes:

Any "insert pending" state is cancelled (calls CancelInsertCharFormat()).

The global format layers are not owned by the object; they are supplied by the owner of the object and not saved when the object is externalised or loaded when it is internalized.

StoreComponentsL() must be called before calling this function. This is necessary to set up the the stream store needed to externalize rich text objects. It is not possible to get a stream store into a stream and a rich text object cannot be externalized to an arbitrary stream thus StoreComponentsL() will set up this stream store before externalizing.

The inherited function CEditableText::StoreL() combines both calling of StoreComponentsL() to set up the stream store and externalizing the rich text object to this stream store.

Parameters

RWriteStream &aStream

Stream to which to write the rich text object.


InternalizeL()

virtual IMPORT_C void InternalizeL(RReadStream &aStream);

Description

Internalises the rich text object and all of its components (field set, style list, rich text formatting and pictures) 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.

Note: The global format layers are not owned by the object; they are supplied by the owner of the object and not saved when the object is externalised or loaded when it is internalized.

Parameters

RReadStream &aStream

Stream from which to read the rich text object.


ExternalizeStyleDataL()

IMPORT_C void ExternalizeStyleDataL(RWriteStream &aStream) const;

Description

Externalises the style list owned by the rich text object.

Parameters

RWriteStream &aStream

Stream to which to write the style list.


InternalizeStyleDataL()

IMPORT_C void InternalizeStyleDataL(RReadStream &aStream);

Description

Internalises the style list owned by the rich text object from a read stream, if one is present in the stream.

Parameters

RReadStream &aStream

Stream from which to read the style list.


StoreMarkupComponentsL()

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

Description

Stores all pictures in the rich text object to a stream store.

Parameters

CStreamStore &aStore

Stream store to which the pictures are to be stored.

CStoreMap &aMap

A store map. This binds the address of pictures to the stream ID of aStore. This is needed to support the deferred loading of pictures.


ExternalizeMarkupDataL()

IMPORT_C void ExternalizeMarkupDataL(RWriteStream &aStream) const;

Description

Externalises the rich text object's markup (specific formatting, styles and pictures). CRichText::HasMarkupData() can be used to test whether the object has any markup information.

Parameters

RWriteStream &aStream

Stream to which to store the rich text markup information.


InternalizeMarkupDataL()

IMPORT_C void InternalizeMarkupDataL(RReadStream &aStream);

Description

Internalises the rich text object's markup (specific formatting, styles and pictures).

Parameters

RReadStream &aStream

Stream from which to internalise the rich text markup.


SetPictureFactory()

IMPORT_C void SetPictureFactory(MPictureFactory *aPictureFactory, MRichTextStoreResolver *aStoreResolver);

Description

Sets the picture factory.

Pictures in a rich text object may be represented as picture headers, or by the picture data itself. CRichText supports the deferred loading of picture data, so that it is only loaded when it is needed to be displayed, thus economising on memory use. A rich text object which supports the deferred loading of pictures needs to be supplied with a picture factory. It can either be set using this function, or during construction.

Note: A panic occurs if the factory is NULL, but the store resolver is not NULL.

Parameters

MPictureFactory *aPictureFactory

The picture factory.

MRichTextStoreResolver *aStoreResolver

The store resolver. This determines which file store the picture is stored in.


PictureFactory()

inline MPictureFactory *PictureFactory() const;

Description

Gets the picture factory. A picture factory may be set during construction, or by calling CRichText::SetPictureFactory().

Return value

MPictureFactory *

The picture factory


StoreResolver()

inline MRichTextStoreResolver *StoreResolver() const;

Description

Gets the store resolver. A store resolver may be set during construction, or by calling CRichText::SetPictureFactory().

Return value

MRichTextStoreResolver *

The store resolver. This determines which file store the picture is stored in.


PictureHeader()

IMPORT_C TPictureHeader PictureHeader(TInt aPos) const;

Description

Gets the picture header which describes the picture located at a specified document position. If no picture header is located at the position, the function constructs and returns a default one.

Parameters

TInt aPos

The document position. Must be valid.

Return value

TPictureHeader

The picture header located at document position aPos, or a default picture header.


DropPictureOwnership()

IMPORT_C void DropPictureOwnership(TInt aPos);

Description

Removes ownership from this rich text object of the picture located at a document position. The picture character is deleted from the document and ownership of the picture passes to the caller of this function. Use PictureHandleL() beforehand to get a pointer to the picture.

Parameters

TInt aPos

The document position of the picture character. Must be valid or a panic occurs.

See also:


DetachFromStoreL()

IMPORT_C void DetachFromStoreL(CPicture::TDetach aDegree);

Description

Loads pictures not already present in memory overloaded function. Either loads all pictures in the document, or just the pictures located within a specified range. Note: In order to load pictures, a picture factory and a store resolver must have been set.

Parameters

CPicture::TDetach aDegree

There are two possible values: EDetachFull and EDetachDraw. If you detach using EDetachFull then you can both draw and edit the picture(s), but if you detach with EDetachDraw then you can only draw them any attempt at editing them causes a panic.


DetachFromStoreL()

IMPORT_C void DetachFromStoreL(CPicture::TDetach aDegree, TInt aPos, TInt aLength);

Description

Loads pictures not already present in memory overloaded function. Either loads all pictures in the document, or just the pictures located within a specified range.

Note: In order to load pictures, a picture factory and a store resolver must have been set.

Parameters

CPicture::TDetach aDegree

There are two possible values: EDetachFull and EDetachDraw. If you detach using EDetachFull then you can both draw and edit the picture(s), but if you detach with EDetachDraw then you can only draw them any attempt at editing them causes a panic.

TInt aPos

The start of the range of characters to search.

TInt aLength

The number of characters in the range.


HasMarkupData()

IMPORT_C TBool HasMarkupData() const;

Description

Tests whether the rich text object has any markup, or owns a style list.

Markup is rich text-specific information, for instance specific formatting, styles and pictures. It may be stored in a separate stream from the text.

Return value

TBool

ETrue if the rich text object has markup, or owns a style list. EFalse if not.


CopyToStoreL()

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

Description

Copies a portion of the rich text object, with components to the clipboard.

A panic occurs in the following circumstances:

aPos is an invalid document position

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


PasteFromStoreL()

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.


PasteFromStoreL()

IMPORT_C TInt PasteFromStoreL(const CStreamStore &aStore, const CStreamDictionary &aDictionary, TInt aPos, CParagraphStyle::TStylePasteMode aStylePasteMode);

Description

Pastes the contents of the clipboard into the rich text object at the specified document position. Returns the number of characters pasted.

If the text in the clipboard has been formatted using styles, the aStylePasteMode argument indicates whether the styles should be preserved or discarded. If the argument is not specified, the pasted rich text retains all formatting specified in the styles, and any new style definitions are added to the style list of the rich text object into which it is pasted.

Parameters

const CStreamStore &aStore

The stream store from which to paste the rich text.

const CStreamDictionary &aDictionary

The stream dictionary.

TInt aPos

The document position at which to paste the rich text. Must be valid, or a panic occurs.

CParagraphStyle::TStylePasteMode aStylePasteMode

Indicates whether styles in the pasted text should be preserved or discarded.

Return value

TInt

The number of characters pasted.


Reset()

virtual IMPORT_C void Reset();

Description

Resets the document's contents to a single end-of-document delimiter. Also deletes the style list if owned by the object.


InsertL()

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.

The insertion position must be valid or a panic occurs.Note:A panic occurs if the text object is in an "insert pending" state (i.e. SetInsertCharFormatL() has been called and has not been cancelled using CancelInsertCharFormat()) and aPos is not the same as the insertion point.

Parameters

TInt aPos

The document position at which to insert the character/descriptor.

const TChar &aChar

The character to insert. Must not be a picture character or a panic occurs.


InsertL()

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


InsertL()

IMPORT_C void InsertL(TInt aPos, const TPictureHeader &aHeader);

Description

Inserts a picture header into the text object at a specified document position. The picture header specified must reference a valid picture, or a panic occurs.

A panic also occurs if the text object is in an "insert pending" state (SetInsertCharFormatL() has been called and has not been cancelled using CancelInsertCharFormat()) and aPos is not the same as the insertion point.

This method takes ownership of a picture referenced in aHeader.

Parameters

TInt aPos

The document position at which to insert the picture header. Must be valid, or a panic occurs.

const TPictureHeader &aHeader

A picture header. This holds a pointer to the picture to insert, and information about the picture.


DeleteL()

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. Can leave because paragraphs may be merged and reformatted by the function.

Parameters

TInt aPos

The start of the range of characters to delete. 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 as a result of the delete, indicating that the formatting of part of the resulting paragraph may have changed.


DeleteFromParagraph()

IMPORT_C void DeleteFromParagraph(TInt aPos, TInt aLength);

Description

Removes a range of characters from within a single paragraph only. Should not be used for deleting an entire paragraph or paragraphs because this may cause it to leave. Otherwise, it is guaranteed not to leave.

Parameters

TInt aPos

The document position of the start of the range of characters to delete. Must be a valid document position, or a panic occurs.

TInt aLength

The number of characters to delete. The sum of aPos and aLength must be less than the document length, or a panic occurs.


DeleteParagraph()

IMPORT_C void DeleteParagraph(TInt aPos, TInt aLength);

Description

Deletes one or more whole paragraphs of text. No paragraphs can be merged together by this function, so it cannot leave — it must only be used to delete entire paragraphs.

Parameters

TInt aPos

The document position of the start of the first paragraph to delete. Must be a valid position or a panic occurs.

TInt aLength

The number of characters to delete.


SetInsertCharFormatL()

IMPORT_C void SetInsertCharFormatL(const TCharFormat &aFormat, const TCharFormatMask &aMask, TInt aPos);

Pre-Condition

aPos must be a valid position, or a panic will occur.

Description

Applies character formatting to a zero length selection, for example turning bold on. This has the effect that the formatting will be applied to text subsequently inserted at the position. This "insert pending" state is cancelled by calling CancelInsertCharFormat().

Note 1: After calling this function, if text is inserted at a different position to aPos, a panic will occur, unless CancelInsertCharFormat() has been called before the insertion to cancel the "insert pending" state.

Note 2: If the insert character format is being set for the end of the paragraph, the paragraph delimiter is set to that format as well. This helps end-of-paragraph behaviour be more similar to other places.

Parameters

const TCharFormat &aFormat

The character format values to apply.

const TCharFormatMask &aMask

Character format mask specifying the attributes affected.

TInt aPos

The document position at which to insert the character format.


CancelInsertCharFormat()

IMPORT_C void CancelInsertCharFormat();

Description

Cancels the "insert pending" state set by a call to SetInsertCharFormatL() or DelSetInsertCharFormatL().

This function removes the restriction on the text insertion position imposed by these two functions. It is recommended that it is called before every cursor movement, scroll, paste, etc. This call is a small overhead, and has no effect if not applicable.


DelSetInsertCharFormatL()

IMPORT_C TBool DelSetInsertCharFormatL(TInt aPos, TInt aLength);

Description

Deletes a range of characters. The range affected is from aPos to aPos+(aLength-1) inclusive. It differs from DeleteL() in that this function preserves the formatting of the deleted character at position aPos, so that any text subsequently inserted at aPos will have that formatting applied to it.

A panic occurs if:

after calling this function, text is inserted at a different position to aPos, without calling CancelInsertCharFormat() before the insertion

aPos is invalid

aLength is negative

the range goes beyond the end of the document

Parameters

TInt aPos

The document position of the first character to delete.

TInt aLength

The number of characters to delete.

Return value

TBool

ETrue if two paragraphs have been merged as a result of the deletion; EFalse if there has been no paragraph merge.


GetParagraphFormatL()

virtual IMPORT_C void GetParagraphFormatL(CParaFormat *aFormat, TInt aPos) const;

Description

Gets the effective paragraph formatting which applies to the paragraph which contains a specified document position. On return, aFormat is filled with values for all paragraph format attributes.

Parameters

CParaFormat *aFormat

On return, filled with the paragraph's effective paragraph formatting.

TInt aPos

Any document position within the paragraph of interest.


GetChars()

virtual IMPORT_C void GetChars(TPtrC &aView, TCharFormat &aFormat, TInt aPos) const;

Description

Gets a constant pointer descriptor to a portion of the text object with constant character formatting.

The view starts at the document position specified, and ends at: the last character which shares the same character formatting, orthe end of the document, orthe end of the segment, if segmented storage is being usedwhichever occurs first. Also fills a character format object with the character formatting of the range of characters.

Parameters

TPtrC &aView

On return, a constant pointer to a portion of the text.

TCharFormat &aFormat

On return, contains the character formatting of the text.

TInt aPos

The start position for the view. Must be a valid document position, or a panic occurs.


GetPictureSizeInTwips()

virtual IMPORT_C TInt GetPictureSizeInTwips(TSize &aSize, TInt aPos) const;

Description

Gets the size of a picture located at a specified document position.

Parameters

TSize &aSize

On return, contains the size of the picture located at aPos.

TInt aPos

Document position of the picture. Must be a valid position.

Return value

TInt

KErrNotFound if there is no picture at the specified document position, KErrNone if there is.


PictureHandleL()

virtual IMPORT_C CPicture *PictureHandleL(TInt aPos, MLayDoc::TForcePictureLoad aForceLoad=MLayDoc::EForceLoadTrue) const;

Description

Gets a pointer to the picture located at a specified document position, if one exists. If the picture is not in memory, the function loads it (if the second argument has a value of MLayDoc::EForceLoadTrue).

Note:

In order to load the picture, a picture factory and a store resolver must have been set.

Parameters

TInt aPos

Document position of the picture character. Must be a valid position.

MLayDoc::TForcePictureLoad aForceLoad

If the picture is not loaded into memory, MLayDoc::EForceLoadTrue loads it using the picture factory; MLayDoc::EForceLoadFalse does not, and in this case, the function returns NULL.

Return value

CPicture *

A pointer to the picture located at aPos. NULL if aPos does not specify a picture character, or if there is a picture at aPos which is not in memory, and the second argument is MLayDoc::EForceLoadFalse.


GetParaFormatL()

virtual IMPORT_C void GetParaFormatL(CParaFormat *aFormat, TParaFormatMask &aVaries, TInt aPos, TInt aLength, CParaFormat::TParaFormatGetMode aMode=CParaFormat::EAllAttributes) const;

Description

Gets the effective paragraph formatting which applies to a range of paragraphs. The region involved is every paragraph containing one or more characters in the range aPos to aPos+(aLength-1) inclusive. On return, aFormat is filled with values for all paragraph format attributes and the mask indicates the values that change over the region, and whose value is therefore indeterminate.

Note:

If aMode has a value of EFixedAttributes, the function cannot leave.

Parameters

CParaFormat *aFormat

Must not be NULL or a panic occurs. On return, contains the effective paragraph formatting for the range of paragraphs.

TParaFormatMask &aVaries

On return, a bitmask indicating which paragraph format attributes vary over the range of characters selected.

TInt aPos

The document position of the start of the range.

TInt aLength

The number of characters in the range.

CParaFormat::TParaFormatGetMode aMode

The default, EAllAttributes means that values for all paragraph format attributes are written to aFormat. EFixedAttributes means that tabs, bullets and borders are not written to aFormat.


ApplyParaFormatL()

virtual IMPORT_C void ApplyParaFormatL(const CParaFormat *aFormat, const TParaFormatMask &aMask, TInt aPos, TInt aLength);

Description

Applies paragraph formatting to a range of paragraphs. The attributes which are set in the mask are taken from aFormat and applied. The attributes which are not set in the mask are not changed.

The region affected consists of every paragraph containing one or more characters in the range aPos to aPos+(aLength-1).

Parameters

const CParaFormat *aFormat

Contains the paragraph format attribute values to apply.

const TParaFormatMask &aMask

Specifies which paragraph format attributes should be affected.

TInt aPos

The document position of the start of the range.

TInt aLength

The number of characters in the range.


GetCharFormat()

virtual IMPORT_C void GetCharFormat(TCharFormat &aFormat, TCharFormatMask &aVaries, TInt aPos, TInt aLength) const;

Description

Gets the effective character formatting which applies to a range of characters. The range of characters involved is from aPos to aPos+(aLength-1) inclusive. On return, aFormat is filled with values for all character format attributes, and on return, the mask indicates the values that change over the region, and whose value is therefore indeterminate.

The length value can be zero. In this case, the character formatting sensed is that of the character immediately to the left of the position specified.

Parameters

TCharFormat &aFormat

On return, contains the character format values for the range of characters.

TCharFormatMask &aVaries

On return, indicates which character format attributes vary over the range.

TInt aPos

Document position of the start of the range. Must be valid or a panic occurs.

TInt aLength

Number of characters in the range. Must be greater than or equal to zero, or a panic occurs.


ApplyCharFormatL()

virtual IMPORT_C void ApplyCharFormatL(const TCharFormat &aFormat, const TCharFormatMask &aMask, TInt aPos, TInt aLength);

Description

Applies character formatting to a range of characters. The attributes which are set in the mask are read from aFormat and applied. The attributes which are not set in the mask are not changed. The range of characters affected is from aPos to aPos+(aLength-1) inclusive. The sum of aPos and aLength must be less than or equal to the document length, or a panic occurs.

Parameters

const TCharFormat &aFormat

Contains the character format attribute values to apply.

const TCharFormatMask &aMask

Bitmask specifying which character format attributes should be applied.

TInt aPos

Document position from which to apply the new character formatting. Must be greater than or equal to zero, or a panic occurs.

TInt aLength

The number of characters to which the new formatting should be applied. Must be greater than or equal to zero, or a panic occurs. If the length is zero, the function has the same effect as SetInsertCharFormatL().


GetSpecificCharFormat()

IMPORT_C void GetSpecificCharFormat(TCharFormat &aFormat, TCharFormatMask &aMask, TInt aPos) const;

Description

Gets the specific character formatting which applies to the character to the left of a document position. Specific formatting is just the formatting which has been applied over the object's global format layers - it is not the same as the effective formatting.

Parameters

TCharFormat &aFormat

On return contains the specific character formatting which applies to the character to the left of the document position.

TCharFormatMask &aMask

On return, indicates which character format attributes have been applied specifically, (not taken from the global layers).

TInt aPos

The document position. Must be valid or a panic occurs.


GetSpecificCharFormatRight()

IMPORT_C void GetSpecificCharFormatRight(TCharFormat &aFormat, TCharFormatMask &aMask, TInt aPos) const;

Description

Gets the specific character formatting which applies to the character logically after a document position. Note that this is not necessarily the character to the right of the document position, because right to left text is supported.

Specific formatting is just the formatting which has been applied over the object's global format layers — it is not the same as the effective formatting.

Parameters

TCharFormat &aFormat

On return, contains the specific character formatting which applies to the character logically after the document position.

TCharFormatMask &aMask

On return, indicates which character format attributes have been applied specifically, (not taken from the global layers).

TInt aPos

The document position. Must be valid or a panic occurs.


GetSpecificParagraphFormatL()

IMPORT_C void GetSpecificParagraphFormatL(CParaFormat *aFormat, TParaFormatMask &aMask, TInt aPos) const;

Description

Parameters

CParaFormat *aFormat

TParaFormatMask &aMask

TInt aPos


ApplyParagraphStyleL()

IMPORT_C void ApplyParagraphStyleL(const CParagraphStyle &aStyle, TInt aPos, TInt aLength, CParagraphStyle::TApplyParaStyleMode aMode);

Description

Applies a specified paragraph style to a range of paragraphs. The region affected consists of every paragraph containing one or more characters in the range aPos to aPos+(aLength-1).

A panic occurs if:

aPos is invalid, or

aLength is negative, or

the range goes beyond the end of the document, or

the rich text object has no style list

Parameters

const CParagraphStyle &aStyle

The style to apply.

TInt aPos

The document position of the start of the range.

TInt aLength

The number of characters in the range.

CParagraphStyle::TApplyParaStyleMode aMode

Controls what specific formatting, if any, should be preserved when the style is applied.


NotifyStyleDeletedL()

inline void NotifyStyleDeletedL(const CParagraphStyle *aStyle);

Description

Removes a style from all paragraphs to which it applies. The formatting is reset to the global character and paragraph format layers, except that any specific formatting which has been applied to the paragraphs is retained.

Notes:

This function should be called on the text content object after deleting a style in the style list.

A panic occurs if the rich text object does not use a style list (this can be tested for using StyleListPresent()).

Parameters

const CParagraphStyle *aStyle

Pointer to the style to remove from the rich text object.


NotifyStyleChangedL()

IMPORT_C void NotifyStyleChangedL(const CParagraphStyle *aTo, const CParagraphStyle *aFrom);

Description

Removes a style from every paragraph in the document to which it applies, and replaces it with another.

If style aTo is NULL, aFrom is replaced by the global character and paragraph format layers, so that in effect, style aFrom is removed. Any specific formatting which has been applied to the paragraphs is retained.

Notes:

This function should be called on the text content object after changing a style in the style list.

A panic occurs if the rich text object does not use a style list (this can be tested for using StyleListPresent()).

Parameters

const CParagraphStyle *aTo

The new paragraph style to apply.

const CParagraphStyle *aFrom

The paragraph style to remove.


ParagraphStyle()

IMPORT_C const CParaFormatLayer *ParagraphStyle(TBool &aStyleChangesOverRange, TInt aPos, TInt aLength) const;

Description

Gets a pointer to the first paragraph style encountered in the specified range.

Parameters

TBool &aStyleChangesOverRange

On return, set to ETrue if more than one paragraph style is used over the specified range of characters. Otherwise EFalse

TInt aPos

The document position of the start of the range. Must be valid.

TInt aLength

The number of characters in the range. Must be greater than or equal to zero.

Return value

const CParaFormatLayer *

Pointer to the paragraph style which applies to the paragraph containing document position aPos. Its type (returned by CParaFormatLayer::Type()) indicates whether this object is a style, or just a paragraph format layer.


StyleListPresent()

inline TBool StyleListPresent() const;

Description

Tests whether the rich text object uses a style list. The style list may be owned by the object itself, or may be externally owned.

Return value

TBool

ETrue if the object uses a style list. EFalse if not


StyleList()

inline CStyleList *StyleList() const;

Description

Gets a pointer to the style list used by the rich text object.

Return value

CStyleList *

The object's style list. NULL if no style list present.


StyleCount()

inline TInt StyleCount() const;

Description

Gets the number of styles contained in the rich text object's style list. Returns zero if there is no style list present.

Return value

TInt

The number of styles in the style list


SetStyleListExternallyOwned()

inline void SetStyleListExternallyOwned(TBool aExternallyOwned);

Description

Sets whether the style list used by this rich text object is owned by the object itself, or is externally owned.

Parameters

TBool aExternallyOwned

ETrue if the style list should be marked as externally owned, EFalse if not.


SetStyleListExternallyOwned()

IMPORT_C void SetStyleListExternallyOwned(const CStyleList &aStyleList);

Description

Assigns an externally owned style list to the rich text object. Replaces any previous style list used by the object. Calls SetStyleListExternallyOwned(ETrue).

Parameters

const CStyleList &aStyleList


StyleListExternallyOwned()

inline TBool StyleListExternallyOwned() const;

Description

Tests whether the style list used by this rich text object is owned by the object itself, or is externally owned. This value is set using SetStyleListExternallyOwned().

Return value

TBool

ETrue if the rich text object's style list is externally owned. EFalse if it owns its style list, or if it does not use a style list.


RemoveSpecificParaFormatL()

IMPORT_C void RemoveSpecificParaFormatL(TInt aPos, TInt aLength);

Description

Removes all specific paragraph formatting from a range of paragraphs. This does not remove formatting from the object's global paragraph format layer. The region affected consists of every paragraph containing one or more characters in the range covered by document position aPos to aPos+(aLength-1) inclusive.

A panic occurs in the following situations:

the position is negative,

the length is negative,

the range goes beyond the end of the document

Parameters

TInt aPos

The document position of the start of the range.

TInt aLength

The number of characters in the range.


RemoveSpecificCharFormatL()

IMPORT_C void RemoveSpecificCharFormatL(TInt aPos, TInt aLength);

Description

Removes all specific character formatting from a range of characters (does not remove the formatting which has been taken from the object's global character format layer). A panic occurs in the following situations:

the position is negative,

the length is negative,

the range goes beyond the end of the document

Parameters

TInt aPos

The document position of the start of the region affected.

TInt aLength

The number of characters in the region affected. If zero, the function has no effect.


PictureCount()

IMPORT_C TInt PictureCount() const;

Description

Gets a count of the number of pictures contained in the rich text object.

Return value

TInt

The picture count.


ParagraphCount()

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 in the document.


CharPosOfParagraph()

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


ParagraphNumberForPos()

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.


ComponentInfo()

virtual IMPORT_C TEtextComponentInfo ComponentInfo() const;

Description

Gets information about the number of components contained in the text object (the field count, the picture count and the style count).

Return value

TEtextComponentInfo

Contains the component information.


UpdateFieldL()

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.


AppendTakingSolePictureOwnershipL()

IMPORT_C void AppendTakingSolePictureOwnershipL(const CRichText &aSource);

Description

Appends a rich text object to this one. The text is appended immediately after the end-of-text paragraph delimiter. The incoming text's formatting is set to be based on the global formatting of this rich text object.

Notes:

If this rich text object is empty (e.g. because it is newly initialised, or has been reset), then the end-of-text delimiter of the incoming rich text is not appended. This avoids the possibility of having a trailing paragraph delimiter, giving one more empty line than would typically be desired.

If the incoming rich text contains pictures which have been loaded into memory, their sole ownership is transferred to the current rich text object. In aSource, these picture handles are set to NULL.

Parameters

const CRichText &aSource

The rich text object to append.


AppendParagraphL()

IMPORT_C void AppendParagraphL(TInt aReplicas=1);

Description

Appends one or more empty paragraphs to the document. The new paragraphs take on the formatting specified in the global format layers.

Parameters

TInt aReplicas

The number of empty paragraphs to append to the document. By default, a single paragraph.


SetHasChanged()

virtual IMPORT_C void SetHasChanged(TBool aHasChanged);

Description

Sets whether the document's content or formatting has changed. This function is called with an value of ETrue by all functions which modify the text content or formatting. Use CEditableText::HasChanged() to test whether the document has changed.

Parameters

TBool aHasChanged

ETrue if the text object has been changed, EFalse if not.


ExtendedInterface()

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. For KUidRichText, CRichText will be returned if rich text is supported.

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


DoExternalizeStyleDataL()

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

Description

Parameters

RWriteStream &aStream


DoInternalizeStyleDataL()

protected: IMPORT_C void DoInternalizeStyleDataL(RReadStream &aStream);

Description

Parameters

RReadStream &aStream


DoExternalizeMarkupDataL()

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

Description

Parameters

RWriteStream &aStream


DoInternalizeMarkupDataL()

protected: IMPORT_C void DoInternalizeMarkupDataL(RReadStream &aStream);

Description

Parameters

RReadStream &aStream


RtInsertL()

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

Description

Parameters

TInt aPos

const TDesC &aBuf


CopyComponentsL()

protected: IMPORT_C void CopyComponentsL(CStreamStore &aStore, CStoreMap &aMap, TInt aPos, TInt aLength, TStreamId aGlobalTextId) const;

Description

Parameters

CStreamStore &aStore

CStoreMap &aMap

TInt aPos

TInt aLength

TStreamId aGlobalTextId


CopyToStreamL()

protected: IMPORT_C void CopyToStreamL(RWriteStream &aStream, TInt aPos, TInt aLength, TStreamId aGlobalTextId) const;

Description

Parameters

RWriteStream &aStream

TInt aPos

TInt aLength

TStreamId aGlobalTextId


CopyToStreamL()

protected: IMPORT_C void CopyToStreamL(RWriteStream &aStream, TInt aPos, TInt aLength) const;

Description

Parameters

RWriteStream &aStream

TInt aPos

TInt aLength


ActivateParserL()

static IMPORT_C void ActivateParserL(MParser *aParser);

Description

Parameters

MParser *aParser


DeactivateParser()

static IMPORT_C void DeactivateParser(MParser *aParser);

Description

Parameters

MParser *aParser


ActivateDefaultParserL()

static IMPORT_C void ActivateDefaultParserL(MParser *aParser);

Description

Parameters

MParser *aParser


DeactivateParserDefaults()

static IMPORT_C void DeactivateParserDefaults();

Description


SetEditObserver()

IMPORT_C void SetEditObserver(MEditObserver *aEditObserver);

Description

Sets the rich text object's edit observer. The observer's EditObserver() function is called by the rich text object each time the object's text content is edited (e.g. after a paste, insert, delete, reset etc.).

Parameters

MEditObserver *aEditObserver

Pointer to the edit observer.


ParseText()

IMPORT_C TBool ParseText(TInt &aStartOfTags, TInt &aLength, TBool aForceScanAllText);

Description

Parameters

TInt &aStartOfTags

TInt &aLength

TBool aForceScanAllText

Return value

TBool


CursorOverTag()

IMPORT_C TBool CursorOverTag(TInt aPos, MParser *&aParser, TInt &aTagStart, TInt &aLength) const;

Description

Parameters

TInt aPos

MParser *&aParser

TInt &aTagStart

TInt &aLength

Return value

TBool


PositionOfNextTag()

IMPORT_C TInt PositionOfNextTag(TInt aPos) const;

Description

Parameters

TInt aPos

Return value

TInt


PositionOfNextTag()

IMPORT_C TInt PositionOfNextTag(TInt aPos, const MParser *aParser) const;

Description

Parameters

TInt aPos

const MParser *aParser

Return value

TInt


PositionOfPrevTag()

IMPORT_C TInt PositionOfPrevTag(TInt aPos) const;

Description

Parameters

TInt aPos

Return value

TInt


PositionOfPrevTag()

IMPORT_C TInt PositionOfPrevTag(TInt aPos, const MParser *aParser) const;

Description

Parameters

TInt aPos

const MParser *aParser

Return value

TInt

[Top]


Member enumerations


Enum TParaType

TParaType

Description

Number of paragraphs in the object.

ESinglePara

The text object will contain a single paragraph.

EMultiPara

The text object will contain multiple paragraphs.


Enum anonymous

protected: n/a

Description

EDelimiterCharacterLength