<?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-0AA6186C-DD10-5811-940F-D26A7D34C66F"><title>Text and Text Attributes Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>Stores editable text and the formatting attributes which are applied to it.</p> <p>The API does not store the layout information needed to display the text. This is done by a separate API called Text Views.</p> <p>Text content is a string of Unicode characters separated into words and paragraphs by space characters and paragraph delimiters. The text is stored in the order used to input the text. A wide range of paragraph and character formatting attributes is supported, including paragraph alignment and character font, etc.</p> </section> <section><title>Architectural relationships</title> <p>Text and Text Attributes uses the Text Views API to format the text for display. Text Views objects contain the layout information, but not the text itself or the attributes. These are obtained via an abstract interface class.</p> <p>Text and Text Attributes classes are used for implementing editable text windows. UI-level objects like editable text windows typically own an editable text object to hold the rich text and attributes, and a Text Views object to store the layout and draw the text.</p> </section> <section><title>Description</title> <p>The API has five key concepts: global text and rich text, document position and range, setting/sensing formatting, format layering and the <xref href="GUID-51B3C34F-2F8E-3181-93C4-00F073B1207C.dita"><apiname>MLayDoc</apiname></xref> interface.</p> <p><b>Global text and rich text</b> </p> <p>Global text is text in which formatting is applied globally, so that the same character and paragraph formatting applies throughout the document. Rich text is text with rich formatting, so that formatting can apply to any portion of the document. Paragraph styles may be applied to rich text but not to global text, and pictures may be inserted into rich text but not global text.</p> <p>The interface to global text is provided by <xref href="GUID-4F502FE5-44D4-3947-9D73-67EF4886059A.dita"><apiname>CGlobalText</apiname></xref>. The interface to rich text is provided by <xref href="GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934.dita"><apiname>CRichText</apiname></xref>.</p> <p><b>Document position and range</b> </p> <p>When editing an editable text object, many functions require a start position and a length to be specified. These values indicate the range of characters to which the function should apply. The range usually has to be valid: that is, it must not extend beyond the bounds of the document. Document position zero is before the first character in the document. If the document contains n characters, position n is after the last character. Valid document positions are therefore between zero and the length of the document, inclusive.</p> <p><b>Setting/sensing formatting</b> </p> <p>When setting or sensing a text object's formatting, a mask and a container are specified. The container has data members which store the value for every format attribute. The mask indicates which attributes are relevant to the operation.</p> <p>The paragraph and character formatting containers are provided by <xref href="GUID-2F795E02-0704-39AE-8EC6-06CB5D5D670F.dita"><apiname>CParaFormat</apiname></xref> and <xref href="GUID-3518B92C-D1BD-36D1-B447-728A1052292F.dita"><apiname>TCharFormat</apiname></xref> respectively, and the corresponding masks are provided by <xref href="GUID-C4220B5C-1037-342E-A409-B62F0429E7F2.dita"><apiname>TParaFormatMask</apiname></xref> and by <xref href="GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D.dita"><apiname>TCharFormatMask</apiname></xref>.</p> <p><b>Format layering</b> </p> <p>Formatting is stored in format layers. Format layers are owned by the text object. A format layer may own a pointer to another format layer. This pointer is called a based-on link. The effective formatting of a text object is the set of attributes specified in its two format layers, as well as any attributes inherited from the layers' chain of based-on links. Note that in rich text, additional formatting may be applied on top of the two owned format layers. This additional formatting is referred to as "specific formatting".</p> <p>The <xref href="GUID-7BEFAAD5-15C3-35A0-BDEF-BC56380D6CE5.dita"><apiname>CCharFormatLayer</apiname></xref> class represents the character format layer and the <xref href="GUID-C5A6B3D4-1BDE-35B4-AC6B-DF517A4D4147.dita"><apiname>CParaFormatLayer</apiname></xref> class represents the paragraph format layer.</p> <p><b>The MLayDoc interface</b> </p> <p>The text and its attributes are stored separately from the layout information. Text Views objects (which calculate and store the layout information) access the text and its attributes via an abstract interface class called <codeph>MLayDoc</codeph>. This class provides all the information needed by the text layout engine to lay out the text for display. By viewing the text object purely in terms of the <xref href="GUID-51B3C34F-2F8E-3181-93C4-00F073B1207C.dita"><apiname>MLayDoc</apiname></xref> interface, the layout engine is insulated from any editable text implementation issues.</p> <p>The <xref href="GUID-51B3C34F-2F8E-3181-93C4-00F073B1207C.dita"><apiname>MLayDoc</apiname></xref> interface is implemented by classes <xref href="GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934.dita"><apiname>CRichText</apiname></xref> and <xref href="GUID-4F502FE5-44D4-3947-9D73-67EF4886059A.dita"><apiname>CGlobalText</apiname></xref>.</p> </section> <section><title>See also</title> <p><xref href="GUID-3E7193C2-143E-58EF-B21F-9C0E1C65226F.dita">Text Views Overview</xref> </p> </section> </conbody></concept>