<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-837333EB-8BD1-551A-BFB4-05BE2056E2DA"><title>Introduction to formatting</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Editable text and plain text have content, but no formatting. This means they can be stored and manipulated, but cannot be viewed, because viewing needs format information — obviously, it needs a font and, more subtly, it also needs paragraph alignment, colour etc.</p> <p>There are two types of format: character and paragraph formats</p> <ul><li id="GUID-96460816-4F52-5FCC-86F6-EB9EC80C8AE8"><p>character format information includes font, colour, bold, italic, underline. Each character has an associated <keyword>effective format</keyword> which consists of any format attributes which have been applied directly to that character or applied via a character style, or inherited from the formatting of preceding text. </p> <p>The <xref href="GUID-3518B92C-D1BD-36D1-B447-728A1052292F.dita"><apiname>TCharFormat</apiname></xref> class contains all information necessary to specify a character format.</p> </li> <li id="GUID-2021FA70-3C2E-525E-B925-C1D02BE472A0"><p>paragraph format information includes left, right and hanging indent, space before, between and after lines, tabs, shading and borders and bullet points. Every paragraph has an <keyword>effective format</keyword>. This consists of the format attributes which have either been explicitly applied to that paragraph or applied via a paragraph style, or inherited from the formatting of preceding text.</p> </li> <li id="GUID-2EB43E75-ADB0-5ECE-B94B-2299A0BF70F7"><p>The <xref href="GUID-2F795E02-0704-39AE-8EC6-06CB5D5D670F.dita"><apiname>CParaFormat</apiname></xref> class contains all information necessary to specify a paragraph format.</p> <p>Paragraph format is a <codeph>C</codeph> class, rather than a <codeph>T</codeph>, because the object owns potentially unbounded arrays, such as the tab stops. Also, the representation of border specification is optimised to use minimum space if no borders are specified. So the paragraph format class needs a destructor, and it is therefore a <codeph>C</codeph>.</p> </li> </ul> <p>In order to economise on space, format specifications are built up in format layers <xref href="GUID-C5A6B3D4-1BDE-35B4-AC6B-DF517A4D4147.dita"><apiname>CParaFormatLayer</apiname></xref> and <xref href="GUID-7BEFAAD5-15C3-35A0-BDEF-BC56380D6CE5.dita"><apiname>CCharFormatLayer</apiname></xref>. Each layer specifies a number of attributes and their values. Functions are provided to manipulate and interrogate the attributes and values in a layer, and to find out the effective format from all the layers applying to a region of the text object. Format mask classes <xref href="GUID-C4220B5C-1037-342E-A409-B62F0429E7F2.dita"><apiname>TParaFormatMask</apiname></xref> and <xref href="GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D.dita"><apiname>TCharFormatMask</apiname></xref> play a key role in specifying which attributes are involved in these operations.</p> <p>For global text, the same formatting applies to the entire text object. A character and paragraph format layer are specified for the global text object's constructor, and are used throughout the lifetime of the object. The effective format is taken by layering these over a default format which specifies values for all attributes.</p> <p>For rich text, format layers may be overlaid, and may apply to any region of the text object. By this means, formatting for each character and paragraph may be controlled individually.</p> <p>A paragraph style is a named format, represented by the <codeph>CParagraphStyle</codeph> class, which may be applied to a paragraph. A style may either replace all attributes already set, or change only the attributes specified in the layer. The paragraph style is a paragraph format layer with a name and, also, a character format layer which sets character formatting in the paragraph.</p> </conbody></concept>