Led Class Library 3.0 / ReferenceManual

Led 3.0 Class Library Documentation

Module WordWrappedTextImager

Classes and Global Functions Index

TrivialWordWrappedImager < TEXTSTORE, IMAGER >

WordWrappedTextImager

qDefaultLedSoftLineBreakChar

qExtraWordWrapDebugging

Module Description:

This module implements the WordWrappedTextImager class. This class provides a TextImager which wraps its text into rows, at word-boudaries, filling in as much of a row of text as possible, before wrapping (subject to standard text UI rules).

Class: `TrivialWordWrappedImager < TEXTSTORE, IMAGER > [public]`

Base Classes: `TrivialImager < TEXTSTORE,IMAGER >`

Description:

Handy little class to image text directly. Like Mac "TextBox" or Win32 "DrawText", in that you can directly use it (no setup), and it images and wraps the text into the given box.

The usuage can be as simple as: void SomeAppDrawCall (Led_Tablet t, const Led_Rect& r, bool printing) { TrivialWordWrappedImager (t, r, LED_TCHAR_OF ("Hi mom")).Draw (); }

See also TrivialImager, and TrivialImager_Interactor.

Class: `WordWrappedTextImager [public]`

Base Classes: `MultiRowTextImager`

Description:

Implement the multirow calculations of a MultiRowTextImager using standard word-wrapping algorithms. Though this will be commonly used for word-wrapping text editors, it isn't the only plasible way to break rows. Some other sort of semantic content in the text might be taken as the thing which guides breaking rows.

Member Details

Member Details
`WordWrappedTextImager::ContainsMappedDisplayCharacters [public]` `bool WordWrappedTextImager::ContainsMappedDisplayCharacters (const Led_tChar* text, size_t nTChars) const` Override `TextImager::ContainsMappedDisplayCharacters` to hide kSoftLineBreakChar characters. See `qDefaultLedSoftLineBreakChar`.
`WordWrappedTextImager::DrawRowHilight [public]` `void WordWrappedTextImager::DrawRowHilight (const RowReference& row, Led_Tablet tablet, const Led_Rect& currentRowRect, const Led_Rect& /invalidRowRect/,` Override `MultiRowTextImager::DrawRowHilight` to handle margins.
`WordWrappedTextImager::FillCache [public]` `void WordWrappedTextImager::FillCache (MultiRowPartitionMarker* pm)` Hook the MultiRowTextImager's FillCache () call to compute the row information for the given MultiRowPartitionMarker. Basicly, this is where we start the word-wrap process (on demand, per line).
`WordWrappedTextImager::FindWrapPointForMeasuredText [public]` `size_t WordWrappedTextImager::FindWrapPointForMeasuredText (const Led_tChar* text, size_t length, Led_Distance wrapWidth,` Helper for word wrapping text. This function is given text, and pre-computed text measurements for the width of each character (Led_tChar, more accurately). Before calling this, the offsets have been adjused for tabstops. This just computes the appropriate place to break the line into rows (just first row).
`WordWrappedTextImager::GetLayoutMargins [public]` `virtual void GetLayoutMargins (RowReference row, Led_Coordinate* lhs, Led_Coordinate* rhs) const = 0;` NB: this routine must `Led_Ensure` that the rhs and lhs results be valid after a call (garbage in), and must ensure rhs > lhs, assuming that both 'lhs' and 'rhs' are non-null pointers (either or both of these pointers can be null). You must specify the wrap-width for each paragraph in a subclass. This routine can be overriden to return a constant width - eg. width of the window, or a different per-paragraph width. But note, it is the subclassers responsability to invalidate whatever caches need to be invalidated (typically in MutliRowTextImager) when the layout width is changed. (nb: this changed in Led 2.2 - 970623-LGP). It is because of the need to notify / invalidate caches that we don't provide a default implementation here. The most likely default would be to wrap to the width of the window, and to successfully implement that strategy, we would need to override SetWindowRect () here. But that would leave those subclassing us with the job of circumventing that needless invalidation, and that seems ugly, and awkward. Better to keep the choice of specifying this width in the same place as where we handle the invalidation. NB: CLOSELY BASED ON Led 2.2's WordWrappedTextImager::GetLayoutWidth, which is now obsolete. Temporarily, this routine will call back to the Led 2.2 GetLayoutWidth() call for backward compatability. But subclasses and callers should all promptly switch to using GetLayoutMargins().
`WordWrappedTextImager::PatchWidthRemoveMappedDisplayCharacters [public]` `void WordWrappedTextImager::PatchWidthRemoveMappedDisplayCharacters (const Led_tChar* srcText, Led_Distance* distanceResults, size_t nTChars) const` Override `TextImager::PatchWidthRemoveMappedDisplayCharacters` to hide kSoftLineBreakChar characters.
`WordWrappedTextImager::RemoveMappedDisplayCharacters [public]` `size_t WordWrappedTextImager::RemoveMappedDisplayCharacters (Led_tChar* copyText, size_t nTChars) const` Override `TextImager::RemoveMappedDisplayCharacters` to hide kSoftLineBreakChar characters.
`WordWrappedTextImager::kSoftLineBreakChar [public]` `static const Led_tChar kSoftLineBreakChar;` Sentinal character used to mark a soft line-break.

WordWrappedTextImager::ContainsMappedDisplayCharacters [public]

bool WordWrappedTextImager::ContainsMappedDisplayCharacters (const Led_tChar* text, size_t nTChars) const

Override TextImager::ContainsMappedDisplayCharacters to hide kSoftLineBreakChar characters. See qDefaultLedSoftLineBreakChar.

WordWrappedTextImager::DrawRowHilight [public]

void WordWrappedTextImager::DrawRowHilight (const RowReference& row, Led_Tablet tablet, const Led_Rect& currentRowRect, const Led_Rect& /*invalidRowRect*/,

Override MultiRowTextImager::DrawRowHilight to handle margins.

WordWrappedTextImager::FillCache [public]

void WordWrappedTextImager::FillCache (MultiRowPartitionMarker* pm)

Hook the MultiRowTextImager's FillCache () call to compute the row information for the given MultiRowPartitionMarker.

Basicly, this is where we start the word-wrap process (on demand, per line).

WordWrappedTextImager::FindWrapPointForMeasuredText [public]

size_t WordWrappedTextImager::FindWrapPointForMeasuredText (const Led_tChar* text, size_t length, Led_Distance wrapWidth,

Helper for word wrapping text. This function is given text, and pre-computed text measurements for the width of each character (Led_tChar, more accurately). Before calling this, the offsets have been adjused for tabstops. This just computes the appropriate place to break the line into rows (just first row).

WordWrappedTextImager::GetLayoutMargins [public]

virtual void GetLayoutMargins (RowReference row, Led_Coordinate* lhs, Led_Coordinate* rhs) const = 0;

NB: this routine must Led_Ensure that the *rhs and *lhs results be valid after a call (garbage in), and must ensure *rhs > *lhs, assuming that both 'lhs' and 'rhs' are non-null pointers (either or both of these pointers can be null).

You must specify the wrap-width for each paragraph in a subclass. This routine can be overriden to return a constant width - eg. width of the window, or a different per-paragraph width. But note, it is the subclassers responsability to invalidate whatever caches need to be invalidated (typically in MutliRowTextImager) when the layout width is changed. (nb: this changed in Led 2.2 - 970623-LGP).

It is because of the need to notify / invalidate caches that we don't provide a default implementation here. The most likely default would be to wrap to the width of the window, and to successfully implement that strategy, we would need to override SetWindowRect () here. But that would leave those subclassing us with the job of circumventing that needless invalidation, and that seems ugly, and awkward. Better to keep the choice of specifying this width in the same place as where we handle the invalidation.

NB: CLOSELY BASED ON Led 2.2's WordWrappedTextImager::GetLayoutWidth, which is now obsolete. Temporarily, this routine will call back to the Led 2.2 GetLayoutWidth() call for backward compatability. But subclasses and callers should all promptly switch to using GetLayoutMargins().

WordWrappedTextImager::PatchWidthRemoveMappedDisplayCharacters [public]

void WordWrappedTextImager::PatchWidthRemoveMappedDisplayCharacters (const Led_tChar* srcText, Led_Distance* distanceResults, size_t nTChars) const

Override TextImager::PatchWidthRemoveMappedDisplayCharacters to hide kSoftLineBreakChar characters.

WordWrappedTextImager::RemoveMappedDisplayCharacters [public]

size_t WordWrappedTextImager::RemoveMappedDisplayCharacters (Led_tChar* copyText, size_t nTChars) const

Override TextImager::RemoveMappedDisplayCharacters to hide kSoftLineBreakChar characters.

WordWrappedTextImager::kSoftLineBreakChar [public]

static const Led_tChar kSoftLineBreakChar;

Sentinal character used to mark a soft line-break.

Config Variable: `qDefaultLedSoftLineBreakChar [public]`

Description:

This is the magic (sentinal) character that will appear in a Led text buffer to indicate a soft line break. This is generated in MSWord (on Mac 5.1 and Windows WinWord 7.0) by the SHIFT-RETURN key combination. I have no idea what value is stored internally in MSWord. This is the value WE will store internally for Led. And so its somewhat subject to change - if I find THIS value conflicts with anything useful.