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