Provides access to the layout information needed to format text for display.
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 (MLayDoc).
Uses the Text and Text Attributes API to store the text content and formatting attributes.
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.
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).
The API has the following key concepts:
View and layout
The two principal classes in the Text Views API are CTextView and CTextLayout.
Most of the Text Views API is provided by the CTextView 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.
CTextLayout is a lower level class than CTextView. Many of its functions only exist for the convenience of other classes in the API. It is used by CTextView 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.
x-y coordinates
As in most bitmapped graphics systems, x coordinates increase rightwards and y coordinates increase downwards.
The Text Views API uses two slightly different coordinate systems. In the system used by the CTextLayout class (see for instance CTextLayout::DocPosToXyPosL()), 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.
In the system used by the CTextView 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.
Scrolling polarity
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.
Band formatting
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.
Redrawing and scrolling
If you need automatic scrolling and redrawing you should use CTextView rather than CTextLayout (see for instance CTextView::HandleGlobalChangeL()). When using the CTextLayout class, redrawing and scrolling must be done by the user.