<?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-3E7193C2-143E-58EF-B21F-9C0E1C65226F"><title>Text Views Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>Provides access to the layout information needed to format text for display. </p> <p>The text itself and its formatting are accessed separately, using the Text and Text Attributes API. Text views obtain text and formatting information via an abstract interface class (<xref href="GUID-51B3C34F-2F8E-3181-93C4-00F073B1207C.dita"><apiname>MLayDoc</apiname></xref>).</p> </section> <section><title>Architectural relationships</title> <p>Uses the Text and Text Attributes API to store the text content and formatting attributes.</p> <p>The Text Views API is used by the Uikon Core API for editable text windows. Higher-level objects such as 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> <p>The Graphics API provides a graphics device to draw to, for instance the screen or a printer, and a graphics context (contains the draw functions and the settings they use e.g. pen size and colour).</p> </section> <section><title>Description</title> <p>The API has the following key concepts:</p> <p><b>View and layout</b> </p> <p>The two principal classes in the Text Views API are <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref> and <xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita"><apiname>CTextLayout</apiname></xref>.</p> <p>Most of the Text Views API is provided by the <codeph>CTextView</codeph> class. It allows clients to do horizontal and vertical scrolling, set a text selection, change the cursor position and appearance and to set margin widths. It also does intelligent scrolling using block transfer (blit) and does automatic redrawing if necessary. It is optimised to reformat the minimum amount necessary. It also does conversion between document positions and x,y coordinates.</p> <p><xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita"><apiname>CTextLayout</apiname></xref> is a lower level class than <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref>. Many of its functions only exist for the convenience of other classes in the API. It is used by <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref> to calculate the layout information. It should be used by clients to set layout attributes, including the wrap width, the height of the visible portion of the document (the "band"), whether formatting should be set to the band only, or to the whole document, and it sets the text object which is the source of the text and formatting information.</p> <p><b>x-y coordinates</b> </p> <p>As in most bitmapped graphics systems, x coordinates increase rightwards and y coordinates increase downwards.</p> <p>The Text Views API uses two slightly different coordinate systems. In the system used by the <xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita"><apiname>CTextLayout</apiname></xref> class (see for instance <xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita#GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF/GUID-9F9DE7DE-FECD-34BF-94EE-296841514154"><apiname>CTextLayout::DocPosToXyPosL()</apiname></xref>), the origin for x-y pixel coordinates is the top left hand corner of the visible area of the body text, to the right of any margins which may have been set, so that the left edge of a non-indented line is at x coordinate 0. These are called layout coordinates.</p> <p>In the system used by the <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref> class, the origin for x-y pixel coordinates is at the top left corner of the view window, to the left of any margins which may have been set. These are called window coordinates.</p> <p><b>Scrolling polarity</b> </p> <p>When scrolling vertically, the Text Views API uses the convention that positive numbers of pixels, lines, paragraphs, pages, etc., mean that the text moves down, and vice versa. When scrolling horizontally, positive numbers of pixels mean that the text moves left and vice versa.</p> <p><b>Band formatting</b> </p> <p>The Text Views API support two format states. In one, the visible portion of a document only is formatted, and in the other, the entire document is formatted. The visible portion of the document is referred to as the band. Setting the formatting to the band may be useful to save memory when displaying large documents. The height of the band also controls the amount of scroll caused by a page up or down.</p> <p><b>Redrawing and scrolling</b> </p> <p>If you need automatic scrolling and redrawing you should use <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita"><apiname>CTextView</apiname></xref> rather than <xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita"><apiname>CTextLayout</apiname></xref> (see for instance <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-903D1087-42CB-32EB-8379-7B019936AD16"><apiname>CTextView::HandleGlobalChangeL()</apiname></xref>). When using the <xref href="GUID-FEE7C848-2E93-3848-A3DA-7EAA533615AF.dita"><apiname>CTextLayout</apiname></xref> class, redrawing and scrolling must be done by the user.</p> </section> <section><title>See also</title> <p><xref href="GUID-0AA6186C-DD10-5811-940F-D26A7D34C66F.dita">Text and Text Attributes Overview</xref> </p> <p><xref href="GUID-0AB9B221-38AE-576E-AC5A-C4C106E3D93B.dita">Graphics Overview</xref> </p> </section> </conbody></concept>