Symbian
Symbian OS Library

SYMBIAN OS V9.3

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



Location: TXTFRMAT.H
Link against: etext.lib

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

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


Construction and destruction


NewL()

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.


NewLC()

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.


NewL()

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.


CParaFormat()

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.


~CParaFormat()

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.

[Top]


Member functions


ResetNonDestructive()

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.


Reset()

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.


CopyL()

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.


CopyL()

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.


Strip()

IMPORT_C void Strip();

Description

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


IsEqual()

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.


IsEqual()

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.


StoreTabL()

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.


RemoveTab()

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.


RemoveAllTabs()

inline void RemoveAllTabs();

Description

Removes all tab stops from the object.


TabStop()

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.


TabCount()

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.


LocateTab()

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.


SetParaBorderL()

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.


RemoveAllBorders()

IMPORT_C void RemoveAllBorders();

Description

Deletes all paragraph borders.


ParaBorder()

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.


BordersPresent()

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.


ParaBorderPtr()

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.


AllBordersEqual()

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.


IsBorderEqual()

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.

[Top]


Member enumerations


Enum anonymous

n/a

Description

Miscellaneous constants.

EMaxParaBorder

The maximum number of paragraph borders (= 4).


Enum TParaBorderSide

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.


Enum TLineSpacingControl

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.


Enum TAlignment

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


Enum TParaFormatGetMode

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.

[Top]


Member data


iFillColor

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.


iLanguage

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.


iLeftMarginInTwips

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


iRightMarginInTwips

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


iIndentInTwips

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


iHorizontalAlignment

TAlignment iHorizontalAlignment;

Description

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


iVerticalAlignment

TAlignment iVerticalAlignment;

Description

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


iLineSpacingInTwips

TInt32 iLineSpacingInTwips;

Description

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


iLineSpacingControl

TLineSpacingControl iLineSpacingControl;

Description

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


iSpaceBeforeInTwips

TInt32 iSpaceBeforeInTwips;

Description

Space above paragraph. By default KParaDefaultSpaceBefore (zero).


iSpaceAfterInTwips

TInt32 iSpaceAfterInTwips;

Description

Space below paragraph. By default KParaDefaultSpaceAfter (zero).


iKeepTogether

TBool iKeepTogether;

Description

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


iKeepWithNext

TBool iKeepWithNext;

Description

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


iStartNewPage

TBool iStartNewPage;

Description

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


iWidowOrphan

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


iWrap

TBool iWrap;

Description

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


iBorderMarginInTwips

TInt32 iBorderMarginInTwips;

Description

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


iBullet

TBullet * iBullet;

Description

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


iDefaultTabWidthInTwips

TUint32 iDefaultTabWidthInTwips;

Description

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