Class CRichText

CRichText

Support

Supported from 5.0

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

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 CGlobalText Text with globally applied formatting CPlainText Stores and manipulates plain text CRichText Text with rich formatting MFormatText Specifies the mixin protocol for getting and setting character and paragraph format attributes MLayDoc This class specifies the mixin protocol for providing the information needed by the text layout engine to lay out a text object

Defined in CRichText:
AppendParagraphL(), AppendTakingSolePictureOwnershipL(), ApplyCharFormatL(), ApplyParaFormatL(), ApplyParagraphStyleL(), CancelInsertCharFormat(), CharPosOfParagraph(), ComponentInfo(), CopyToStoreL(), DelSetInsertCharFormatL(), DeleteFromParagraph(), DeleteL(), DeleteParagraph(), DetachFromStoreL(), DropPictureOwnership(), EMultiPara, ESinglePara, ExternalizeL(), ExternalizeMarkupDataL(), ExternalizeStyleDataL(), GetCharFormat(), GetChars(), GetParaFormatL(), GetParagraphFormatL(), GetPictureSizeInTwips(), GetSpecificCharFormat(), GetSpecificCharFormatRight(), HasMarkupData(), InsertL(), InternalizeL(), InternalizeMarkupDataL(), InternalizeStyleDataL(), NewL(), NotifyStyleChangedL(), NotifyStyleDeletedL(), ParagraphCount(), ParagraphNumberForPos(), ParagraphStyle(), PasteFromStoreL(), PictureCount(), PictureFactory(), PictureHandleL(), PictureHeader(), RemoveSpecificCharFormatL(), RemoveSpecificParaFormatL(), Reset(), RestoreComponentsL(), RestoreWithStyleListL(), SetEditObserver(), SetHasChanged(), SetInsertCharFormatL(), SetPictureFactory(), SetStyleListExternallyOwned(), StoreComponentsL(), StoreMarkupComponentsL(), StoreResolver(), StyleCount(), StyleList(), StyleListExternallyOwned(), StyleListPresent(), TParaType, UpdateFieldL(), ~CRichText()

Inherited from CBase:
operator new()

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

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

Inherited from CPlainText:
Anonymous, ConvertAllFieldsToText(), ConvertFieldToText(), DocumentLength(), EOrganiseByLine, EOrganiseByParagraph, EScanBackwards, EScanEndOfData, EScanJoinDelimiters, EScanPictureIsDelimiter, EScanPunctuationIsDelimiter, EScanStayIfBoundary, EScanToUnitEnd, EScanToUnitStart, ExportAsTextL(), ExportTextL(), ExternalizeFieldDataL(), ExternalizePlainTextL(), ExternalizePlainTextNoLengthCountL(), Extract(), FieldCount(), FieldFactory(), FindFields(), GetWordInfo(), ImportTextFileL(), ImportTextL(), InsertFieldL(), InternalizeFieldDataL(), InternalizePlainTextL(), NewTextFieldL(), PageContainingPos(), Read(), RemoveField(), RestoreFieldComponentsL(), ScanParas(), ScanWords(), SetFieldFactory(), SetPageTable(), StoreFieldComponentsL(), TImportExportParam, TImportExportResult, TScanDataEnd, TTextOrganisation, TextField(), ToParagraphStart(), UpdateAllFieldsL(), WordCount()

Inherited from MLayDoc:
EForceLoadFalse, EForceLoadTrue, TForcePictureLoad

See also:

• CParagraphStyle

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

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

static CRichText* NewL(const CStreamStore& aStore,TStreamId aStreamId,const CParaFormatLayer* aGlobalParaLayer,const CCharFormatLayer* aGlobalCharLayer, MTextFieldFactory* aFieldFactory=NULL, 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.

static CRichText* NewL(const CStreamStore& aStore,TStreamId aStreamId,const CParaFormatLayer* aGlobalParaLayer,const CCharFormatLayer *aGlobalCharLayer,MPictureFactory* aPictureFactory, MRichTextStoreResolver* aStoreResolver,MTextFieldFactory* aFieldFactory=NULL, 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.

virtual ~CRichText();

Description

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

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

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

Parameters

RWriteStream& aStream Stream to which to write the rich text object.

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

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

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.

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.

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.

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.

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.

void DetachFromStoreL(CPicture::TDetach aDegree);
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.

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.

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.

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

virtual TInt PasteFromStoreL(const CStreamStore& aStore,const CStreamDictionary& aDictionary,TInt aPos);
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.

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.

virtual 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, or

• the end of the document, or

• the end of the segment, if segmented storage is being used

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

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

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

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

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.

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

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=1 The number of empty paragraphs to append to the document. By default, a single paragraph.

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.

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

void SetEditObserver(MEditObserver* aEditObserver);

Support

Supported from 6.0

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.

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

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

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.

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

Support

Supported from 6.1

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.

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.

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

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:

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.

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. Must be a valid position, or a panic will occur.

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.

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.

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

virtual 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=CParaFormat::EAllAttributes 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.

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

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.

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.

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.

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.

virtual 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=MLayDoc::EForceLoadTrue 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.

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

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

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.

TInt PictureCount()const;

Description

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

Return value

TInt The picture count.

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.

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.

void DropPictureOwnership(TInt aPos);

Support

Supported from 6.1

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:

• CRichText::PictureHandleL()

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.

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

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.

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

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 True if the object uses a style list. False if not

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.

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 True if the rich text object's style list is externally owned. False if it owns its style list, or if it does not use a style list.

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.

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

TBool aExternallyOwned The style list to assign to this rich text object. Not owned by the rich text object.

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

Description

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

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.

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.

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.