Class CParaFormat

class CParaFormat : public CBase;

Description

A transient container of paragraph format attributes, including tab stops, bullet points and paragraph borders.

Rich and global text objects store paragraph formatting using paragraph format layers (see class CParaFormatLayer). The CParaFormat class is used to store the relevant attribute values when setting or sensing a CParaFormatLayer. It is normally used in combination with a TParaFormatMask, to specify which attributes are relevant to the function concerned.

On construction, all CParaFormat member data is initialised. The attributes which are not explicitly set are assigned default values.

Derivation

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

• CParaFormat - A transient container of paragraph format attributes, including tab stops, bullet points and paragraph borders

Members

Defined in CParaFormat:
AllBordersEqual(), BordersPresent(), CParaFormat(), CopyL(), CopyL(), EAbsoluteLeftAlign, EAbsoluteRightAlign, EAllAttributes, EBottomAlign, ECenterAlign, ECustomAlign, EFixedAttributes, EJustifiedAlign, ELeftAlign, ELineSpacingAtLeastInPixels, ELineSpacingAtLeastInTwips, ELineSpacingExactlyInPixels, ELineSpacingExactlyInTwips, EMaxParaBorder, EParaBorderBottom, EParaBorderLeft, EParaBorderRight, EParaBorderTop, ERightAlign, ETopAlign, EUnspecifiedAlign, IsBorderEqual(), IsEqual(), IsEqual(), LocateTab(), NewL(), NewL(), NewLC(), ParaBorder(), ParaBorderPtr(), RemoveAllBorders(), RemoveAllTabs(), RemoveTab(), Reset(), ResetNonDestructive(), SetParaBorderL(), StoreTabL(), Strip(), TAlignment, TLineSpacingControl, TParaBorderSide, TParaFormatGetMode, TabCount(), TabStop(), anonymous, iBorderMarginInTwips, iBullet, iDefaultTabWidthInTwips, iFillColor, iHorizontalAlignment, iIndentInTwips, iKeepTogether, iKeepWithNext, iLanguage, iLeftMarginInTwips, iLineSpacingControl, iLineSpacingInTwips, iRightMarginInTwips, iSpaceAfterInTwips, iSpaceBeforeInTwips, iStartNewPage, iVerticalAlignment, iWidowOrphan, iWrap, ~CParaFormat()

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

static IMPORT_C CParaFormat *NewL();

Description

Allocates and constructs a CParaFormat object. All attributes are initialised with default values.

Return value

CParaFormat * The new CParaFormat object.

static IMPORT_C CParaFormat *NewLC();

Description

Allocates and constructs a CParaFormat object. All attributes are initialised with default values. Leaves the object on the cleanup stack.

Return value

CParaFormat * The new CParaFormat object.

static IMPORT_C CParaFormat *NewL(const CParaFormat &aFormat);

Description

Allocates and constructs a new CParaFormat. All attributes are initialised to the values contained in the aFormat argument.

Parameters

const CParaFormat &aFormat Paragraph format container whose values are used to initialise the new CParaFormat.

Return value

CParaFormat * The new CParaFormat object.

IMPORT_C CParaFormat();

Description

The default C++ constructor constructs a new CParaFormat initialising all attributes to the default settings.

Note: This function allows a CParaFormat object to be created on the stack. This should only be done if it is known in advance that the object will not be used to store tab stops, bullets or borders.

IMPORT_C ~CParaFormat();

Description

The destructor frees all resources owned by the paragraph format container (tabs, borders and bullets), prior to its destruction.

Note that Strip() also sets the resource pointers to NULL. This is important in case CParaFormat is on the stack and gets deleted twice: once by the cleanup stack and once by exceptions being unwound.

IMPORT_C void ResetNonDestructive();

Description

Resets all paragraph format attributes to their default values, but any allocated tab stops, bullet points and paragraph borders are preserved.

IMPORT_C void Reset();

Description

Resets all paragraph format attributes to their default values. All tab stops, paragraph borders and bullet points which have been allocated are deleted and set to NULL.

IMPORT_C void CopyL(const CParaFormat &aFormat, const TParaFormatMask &aMask);

Description

Copies selected attribute values from another paragraph format container. Only the attributes which are set in the mask are copied.

Parameters

const CParaFormat &aFormat Contains the attribute values to copy. const TParaFormatMask &aMask Bitmask specifying the attributes to copy.

IMPORT_C void CopyL(const CParaFormat &aFormat);

Description

Copies all attribute values from another paragraph format container.

Parameters

const CParaFormat &aFormat Contains the attribute values to copy.

IMPORT_C void Strip();

Description

Deletes all paragraph borders, bullets and tab stops. No other attributes are affected.

IMPORT_C TBool IsEqual(const CParaFormat &aFormat, const TParaFormatMask &aMask) const;

Description

Compares selected attribute values for equality. Only the attributes specified in the mask are involved in the comparison.

Parameters

const CParaFormat &aFormat Contains the attribute values to compare. const TParaFormatMask &aMask Bitmask specifying the attributes to compare.

Return value

TBool ETrue if the two format containers have the same values for the attributes specified in the mask, EFalse if not.

IMPORT_C TBool IsEqual(const CParaFormat &aFormat) const;

Description

Compares all attribute values for equality.

Parameters

const CParaFormat &aFormat Contains the attribute values to compare.

Return value

TBool ETrue if the two format containers have the same values for all attributes, EFalse if not.

IMPORT_C void StoreTabL(const TTabStop &aTabStop);

Description

Adds a tab stop to the list of tab stops, maintaining the ordering of the list, (ascending order of twips position). Multiple tabs with the same twips position are not allowed, so that if aTabStop shares the same twips position as an existing tab stop, regardless of its alignment, the existing tab stop is replaced by aTabStop.

Parameters

const TTabStop &aTabStop The tab stop to be stored.

IMPORT_C void RemoveTab(TInt aTabTwipsPosition);

Description

Deletes a tab stop identified by its twips position. If the specified tab stop does not exist, the function has no effect.

Parameters

TInt aTabTwipsPosition The twips position of the tab stop to remove.

inline void RemoveAllTabs();

Description

Removes all tab stops from the object.

IMPORT_C const TTabStop TabStop(TInt aTabIndex) const;

Description

Gets the tab stop located at the specified index within the tab list (counting from zero). Tab stops are ordered in ascending order of twips position. If the object has no tab list, then a default tab stop is returned.

Parameters

TInt aTabIndex The offset of the tab stop in the tab list. Must be less than the total number of tab stops, or a panic occurs. To find the total number of tab stops, use TabCount().

Return value

const TTabStop The tab stop located at the specified index.

inline TInt TabCount() const;

Description

Gets a count of the total number of tab stops in the object's tab list. If the object has no tab list, returns zero.

Return value

TInt The number of tab stops.

IMPORT_C TInt LocateTab(TInt aTabTwipsPosition) const;

Description

Locates the tab stop specified by its twips position, and returns its offset in the tab list.

Parameters

TInt aTabTwipsPosition The twips position of the tab stop.

Return value

TInt The tab stop's index within the tab list (counting from zero). KTabNotFound indicates that no tab stop has the specified twips position, or that no tab list has been allocated.

IMPORT_C void SetParaBorderL(TParaBorderSide aSide, const TParaBorder &aBorder);

Description

Sets one side of the object's paragraph border. If a border on the specified side already exists, it is replaced.

Note: Setting a single side of the object's paragraph border incurs the overhead of allocating storage for the three other sides, which are assigned default values.

Parameters

TParaBorderSide aSide The side for the paragraph border. const TParaBorder &aBorder Specification for the paragraph border.

IMPORT_C void RemoveAllBorders();

Description

Deletes all paragraph borders.

IMPORT_C const TParaBorder ParaBorder(TParaBorderSide aSide) const;

Description

Gets the paragraph border on the side specified. If no paragraph border array has been allocated, returns a default paragraph border.

Parameters

TParaBorderSide aSide The side for the paragraph border.

Return value

const TParaBorder The paragraph border on the specified side.

inline TBool BordersPresent() const;

Description

Tests whether any paragraph borders have been set.

Return value

TBool ETrue if any paragraph borders have been set, EFalse if not.

inline TParaBorder *ParaBorderPtr(TParaBorderSide aSide);

Description

Gets a pointer to the paragraph border on the side specified. If no paragraph border array has been allocated, returns NULL.

Parameters

TParaBorderSide aSide The side for the paragraph border.

Return value

TParaBorder * Pointer to the paragraph border on the specified side.

IMPORT_C TBool AllBordersEqual(const CParaFormat &aFormat) const;

Description

Tests whether all paragraph borders in the specified paragraph format container are identical to the paragraph borders of this paragraph format container.

Parameters

const CParaFormat &aFormat Contains the set of paragraph borders to compare.

Return value

TBool ETrue if both objects have exactly the same set of paragraph borders. EFalse if not.

IMPORT_C TBool IsBorderEqual(TParaBorderSide aSide, const CParaFormat &aFormat) const;

Description

Tests whether the paragraph border located on the specified side is the same as the border on the corresponding side in this object. For two borders to be equal, they must both either be set or unset, and if set, they must have the same characteristics.

Parameters

TParaBorderSide aSide Indicates which side should be compared. const CParaFormat &aFormat Contains the paragraph border to compare.

Return value

TBool ETrue if the border sides are identical. EFalse if not.

n/a

Description

Miscellaneous constants.

EMaxParaBorder The maximum number of paragraph borders (= 4).

TParaBorderSide

Description

Paragraph border sides

EParaBorderTop The border at the top of the paragraph. EParaBorderBottom The border at the bottom of the paragraph. EParaBorderLeft The border on the left hand side. EParaBorderRight The border on the right hand side.

TLineSpacingControl

Description

Line spacing control

ELineSpacingAtLeastInTwips Twips line spacing must be at least as wide as the iLineSpacingInTwips value. ELineSpacingExactlyInTwips Twips line spacing must be exactly the iLineSpacingInTwips value. ELineSpacingAtLeastInPixels Pixels line spacing must be at least as wide as the line spacing value in pixels. ELineSpacingExactlyInPixels Pixels line spacing must be exactly the same as the line spacing value in pixels.

TAlignment

Description

Paragraph alignment

ELeftAlign Paragraph aligned to the leading margin (left for left-to-right paragraphs, right for right-to-left paragraphs). ETopAlign Paragraph top aligned. ECenterAlign Paragraph centre aligned. ERightAlign Paragraph aligned to the trailing margin (right for left-to-right paragraphs, left for right-to-left paragraphs). EBottomAlign Paragraph bottom aligned. EJustifiedAlign Paragraph justified. EUnspecifiedAlign Used by the spreadsheet application. Unlike ETopAlign and EBottomAlign, provides no default implementation. ECustomAlign User-defined paragraph alignment. EAbsoluteLeftAlign Absolute left alignment EAbsoluteRightAlign Absolute right alignment

TParaFormatGetMode

Description

Attribute sense mode

EAllAttributes Indicates that all paragraph format attributes are written to the result when sensing paragraph format attributes. EFixedAttributes Indicates that tabs, bullets and borders are not sensed.

TLogicalRgb iFillColor;

Description

The background colour of the paragraph. By default the default system background colour. This colour applies to the area bounded by the paragraph border, if one exists.

TInt32 iLanguage;

Description

The language of the paragraph for proofing. By default KParaDefaultLanguage. Used for example when spell checking a document which contains text in more than one language, so that the program recognises the text as being in another language.

TInt32 iLeftMarginInTwips;

Description

The width in twips of the leading margin (left for left-to-right paragraphs, right for right-to-left paragraphs). By default KParaDefaultLeftMargin (zero).

TInt32 iRightMarginInTwips;

Description

The width in twips of the trailing margin (right for left-to-right paragraphs, left for right-to-left paragraphs). By default KParaDefaultRightMargin (zero).

TInt32 iIndentInTwips;

Description

An indent for the first line in the paragraph, relative to the leading margin (left for left-to-right paragraphs, right for right-to-left paragraphs). By default KParaDefaultIndent (zero).

TAlignment iHorizontalAlignment;

Description

Horizontal alignment of paragraph. By default KParaDefaultHorizAlign (left).

TAlignment iVerticalAlignment;

Description

Vertical alignment of paragraph, (intended for use by spreadsheet applications). By default KParaDefaultVertAlign (unspecified).

TInt32 iLineSpacingInTwips;

Description

Inter-line spacing within the paragraph, in twips. By default KParaDefaultLineSpacing (200 twips).

TLineSpacingControl iLineSpacingControl;

Description

Control for the iLineSpacingInTwips value. By default, KParaDefaultLineSpacingControl (ELineSpacingAtLeastInTwips).

TInt32 iSpaceBeforeInTwips;

Description

Space above paragraph. By default KParaDefaultSpaceBefore (zero).

TInt32 iSpaceAfterInTwips;

Description

Space below paragraph. By default KParaDefaultSpaceAfter (zero).

TBool iKeepTogether;

Description

Prevents a page break within paragraph if ETrue. By default KParaDefaultKeepTogether (EFalse).

TBool iKeepWithNext;

Description

Prevents a page break between this paragraph and the following paragraph if ETrue. By default, KParaDefaultKeepWithNext (EFalse).

TBool iStartNewPage;

Description

Inserts a page break immediately before this paragraph if ETrue. By default, KParaDefaultStartNewPage (EFalse).

TBool iWidowOrphan;

Description

Prevents the printing of the last line of a paragraph at the top of the page (referred to as a widow), or the first line of a paragraph at the bottom of the page, (referred to as an orphan). By default, KParaDefaultWidowOrphan (EFalse).

TBool iWrap;

Description

Specifies whether the paragraph should line wrap at the right margin. By default KParaDefaultWrap (ETrue).

TInt32 iBorderMarginInTwips;

Description

Distance in twips between the paragraph border and the enclosed text. By default KParaDefaultBorderMargin (zero).

TBullet * iBullet;

Description

The bullet point associated with the paragraph. A NULL value indicates no bullet point. By default NULL.

TUint32 iDefaultTabWidthInTwips;

Description

Specifies the default tab stop width. By default KParaDefaultTabWidth (360 twips).